参数校验失败时应返回结构化中文提示,统一用@controlleradvice捕获methodargumentnotvalidexception,遍历bindingresult提取错误,将字段名映射为前端一致的可读名称,并按field+message格式组织details数组,兼顾用户友好与开发调试。

参数校验失败时返回友好的提示,核心是:把技术性错误(比如“must not be null”)转成用户能看懂、知道怎么改的中文描述,并明确指出哪个字段出了问题。
统一捕获校验异常,避免堆栈暴露
Spring Boot 中常用 @Valid 或 @Validated 触发校验,失败会抛出 MethodArgumentNotValidException。不要让它直接返回 500 或堆栈,应在全局异常处理器中拦截:
- 用
@ControllerAdvice+@ExceptionHandler(MethodArgumentNotValidException.class)捕获 - 遍历
BindingResult.getAllErrors(),提取每个字段的校验错误 - 把默认的英文消息(如
NotBlank.user.name)替换为可读的中文提示
字段名友好化,不暴露内部属性名
前端传的是 user_name,后端实体字段可能是 userName,直接返回 “userName must not be blank” 不直观。建议:
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
- 在
@NotBlank(message = "用户名不能为空")中直接写中文提示(最简单) - 或用
@NotBlank(message = "{user.name.notblank}")配合ValidationMessages.properties管理提示,便于多语言 - 若需动态字段名(如校验 List 中的第 2 个元素),可用
FieldError.getField()+ 自定义映射表转成“用户列表第2项的手机号”
结构化返回,方便前端定位和展示
别只返回一句“参数错误”,应提供清晰的错误结构,例如:
{
"code": 400,
"message": "请求参数校验失败",
"details": [
{ "field": "phone", "message": "手机号格式不正确" },
{ "field": "age", "message": "年龄必须在 1~150 之间" }
]
}
-
details数组让前端可逐条展示红字提示 -
field值尽量与前端请求字段名一致(如user_phone而非userPhone),必要时做映射 - 对嵌套对象(如
address.city),可转成“收货地址-城市”提升可读性
兼顾开发调试与用户提示
同一套校验,既要给用户看简洁提示,也要让开发快速定位问题:
- 生产环境返回精简友好提示;测试/本地环境可额外带上原始字段路径和约束类型(如 “@Pattern(regexp=‘^1[3-9]\d{9}$’)”)
- 日志中记录完整校验上下文(请求 ID、参数快照、全部
FieldError),不暴露给前端 - 对业务强相关的校验(如“手机号不能与当前账号重复”),不用注解,而用
@AssertTrue或手动校验,并写明业务含义










