Spring Boot 接口参数校验实战指南

一、为什么参数校验必须前置

一个典型的注册接口，接收用户名、邮箱、年龄三个字段。Controller 写法如下：

@PostMapping("/register")
public Result register(@RequestBody UserDTO user) {
    userService.register(user);
    return Result.ok();
}

这段代码在正常输入下工作良好，但一旦遇到异常输入，问题就会以各种意想不到的方式暴露：

• 前端传入空用户名，数据库的非空约束报错，接口返回 500；
• 传入 age = -5，数据被顺利写入，后续按年龄区间过滤时逻辑出现偏差；
• 传入 email = abc，同样被存入，直到异步发送验证邮件时才抛出异常。

这些脏数据的共同特征是：写入时毫无阻碍，暴露时已经远离入口。排查问题时，往往只能顺着数据链路反向追溯，很难第一时间定位是哪个接口放进了不合法的数据。更严重的是，一旦脏数据已经落库，清洗成本远高于拦截成本。

正确的做法是把校验前移到请求进入业务逻辑的第一时间。Spring Boot 通过 Bean Validation（JSR 380 规范）提供了声明式的校验能力，在 DTO 字段上添加约束注解，配合控制器上的触发标记，即可在参数绑定完成后、方法体执行前完成校验。校验不通过时抛出异常，业务代码一行都不会执行。

二、三步完成基础校验

2.1 第一步：在 DTO 字段上声明约束

public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(min = 2, max = 20, message = "用户名长度需为 2-20 个字符")
    private String username;
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄不能为负数")
    @Max(value = 150, message = "年龄不合理")
    private Integer age;
    @NotBlank(message = "密码不能为空")
    @Size(min = 8, max = 32, message = "密码长度需为 8-32 个字符")
    private String password;
}

三个注解的语义需要区分清楚：

• @NotBlank 作用于字符串，要求不为 null、长度大于 0 且不全为空白字符，是字符串场景下最常用的非空判断；
• @NotNull 只要求不为 null，对空字符串不做限制，适用于数值、对象等非字符串类型；
• @Email 按正则规则校验邮箱格式，允许 null（配合 @NotBlank 使用可同时保证非空与格式）。

需要注意包名的版本差异：Spring Boot 3.x 使用 jakarta.validation.constraints 包，2.x 使用 javax.validation.constraints 包，注解本身的行为一致，仅命名空间随规范迁移而变化。升级项目时这是常见的编译错误来源。

2.2 第二步：在控制器上触发校验

@PostMapping("/register")
public Result register(@Validated @RequestBody UserDTO user) {
    userService.register(user);
    return Result.ok();
}

@Validated 告诉 Spring 在参数绑定完成后执行校验。校验失败会抛出 MethodArgumentNotValidException，请求不会进入方法体。@Valid 与 @Validated 在此场景下都能生效，区别在于后者是 Spring 提供的注解，支持分组校验等扩展能力，前者是规范注解，主要用于嵌套对象的级联触发。

2.3 第三步：让错误信息可读

默认的异常响应只包含状态码、时间戳和路径，具体哪个字段失败、失败原因是什么全部丢失：

{
  "timestamp": "2025-03-10T08:30:00.000+00:00",
  "status": 400,
  "error": "Bad Request",
  "path": "/api/register"
}

这样的响应对调用方几乎没有指导价值。需要增加全局异常处理，把字段级错误提取出来并统一格式。

三、全局异常处理：统一错误响应

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidation(
            MethodArgumentNotValidException ex) {
        List<FieldError> fieldErrors = ex.getBindingResult().getFieldErrors();
        List<String> details = fieldErrors.stream()
                .map(e -> e.getField() + ": " + e.getDefaultMessage())
                .collect(Collectors.toList());
        ErrorResponse body = new ErrorResponse(
                "PARAM_VALIDATION_FAILED", "请求参数校验未通过", details);
        return ResponseEntity.badRequest().body(body);
    }
}

返回结构建议包含三部分：稳定的错误码（便于调用方做程序化判断）、面向人的概要信息、字段级明细列表。错误码不要直接复用异常类名，而应定义业务语义明确的常量，避免实现细节泄漏到接口契约中。

如果同一个字段同时触发多个约束，getFieldErrors() 会返回多条记录。是否需要去重或只保留首条，取决于产品的交互设计；一般建议全部返回，让调用方一次修正所有问题，减少往返次数。

四、容易被忽略的几种场景

4.1 简单参数与路径变量

@RequestBody 包装的对象校验由 @Validated 直接触发，但方法上的简单参数（如 @RequestParam、@PathVariable）需要把注解标注在方法参数上，并且控制器类上要有 @Validated：

@RestController
@Validated
public class UserController {
    @GetMapping("/user/{id}")
    public Result detail(@PathVariable @Min(1) Long id) {
        ...
    }
}

这类校验失败抛出的是 ConstraintViolationException，与请求体校验的异常类型不同，全局异常处理器需要分别处理，否则会落到默认的 500 分支。

4.2 嵌套对象校验

当 DTO 中包含另一个对象字段时，仅在外层标注约束不会自动递归。需要在嵌套字段上添加 @Valid，级联校验才会生效：

public class OrderDTO {
    @NotNull(message = "收货地址不能为空")
    @Valid
    private AddressDTO address;
}

遗漏 @Valid 是嵌套校验失效最常见的原因，表现为内层字段的约束注解完全不触发。

4.3 分组校验

同一 DTO 在新增和修改场景下约束往往不同：新增时 ID 必须为空，修改时 ID 必须存在。Bean Validation 通过分组接口解决这个问题：定义标记接口，在注解的 groups 属性中指定，控制器上通过 @Validated(Group.class) 激活对应分组。未指定分组的约束属于 Default 分组，只有在不指定分组时才会执行。

4.4 自定义约束

内置注解覆盖不到的业务规则，可以通过自定义约束实现。做法是编写一个注解，用 @Constraint 指定校验器类，校验器实现 ConstraintValidator 接口：

@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PhoneValidator.class)
public @interface Phone {
    String message() default "手机号格式不正确";
    Class<?>[] groups() default {};
    Class<? extends Payload>[] payload() default {};
}

校验器中应把 null 视为通过，非空判断交给 @NotNull 负责，保持单一职责。这样组合使用时语义清晰，也符合规范对约束注解的约定。

五、实践建议

第一，校验规则集中放在 DTO 上，不要在 Service 层重复编写 if 判断。规则只有一处来源，修改时不会遗漏。

第二，错误信息面向调用方编写。消息内容应说明期望的格式或范围，而不是简单重复字段名。

第三，区分校验失败与业务失败。参数格式错误返回 400，业务规则不满足（如用户名已存在）返回业务错误码，两者不要混用同一套响应结构。

第四，为校验逻辑补充测试。针对每个约束至少构造一个非法输入，验证异常类型与响应结构，避免后续重构时规则被悄悄削弱。

第五，注意性能边界。校验本身开销很小，但正则类约束（如邮箱、手机号）在超高 QPS 下仍有成本，正则表达式应避免灾难性回溯的写法。

参数校验不是可选的锦上添花，而是接口契约的组成部分。把规则声明在入口、把错误暴露在入口、把响应格式稳定在入口，业务代码才能专注于真正的业务逻辑，脏数据也就失去了进入系统的机会。