Spring Boot 项目如何优雅的实现接口参数校验

一、问题背景：脏数据为何总能穿透到下游

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

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

看起来简洁，但实际运行中会暴露一系列问题：

• 前端传了空用户名，数据库 NOT NULL 约束报错，接口返回 500；
• 传了 age = -5，数据被正常写入，后续按年龄过滤时逻辑出错；
• 传了 email = abc，同样入库成功，直到发送验证邮件时才抛出异常。

这些脏数据的共同特征是：校验缺失或校验滞后。它们往往在 Service 层甚至更下游才暴露，排查时很难快速定位是哪个接口、哪次请求放入的。更严重的是，一旦脏数据落库，修复成本远高于在入口处拦截。

因此，接口参数校验的核心目标不是“写几个注解”，而是建立一套分层、可复用、可观测的校验体系，让非法请求在进入业务逻辑之前就被拒绝。

二、校验的分层思路

在实际项目中，参数校验不应只依赖某一层，而应按成本从低到高分层布防：

层级	职责	典型手段
接入层	拦截明显非法请求	网关规则、限流、基础格式校验
Controller 层	校验请求参数结构与语义	Bean Validation 注解、@Valid
Service 层	校验业务规则与状态	业务断言、领域校验
持久层	兜底约束	数据库 NOT NULL、唯一索引、CHECK

本文重点讨论 Controller 层的优雅实现，因为这是成本最低、收益最直接的一层。

三、基于 Bean Validation 的基础校验

Spring Boot 对 Bean Validation 提供了开箱即用的支持。只需引入依赖（通常由 web starter 间接带入），即可在 DTO 上使用标准注解。

3.1 定义带校验规则的 DTO

public class UserDTO {
    @NotBlank(message = "用户名不能为空")
    @Size(max = 32, message = "用户名长度不能超过32")
    private String username;
    @NotBlank(message = "邮箱不能为空")
    @Email(message = "邮箱格式不正确")
    private String email;
    @NotNull(message = "年龄不能为空")
    @Min(value = 0, message = "年龄不能小于0")
    @Max(value = 150, message = "年龄不能大于150")
    private Integer age;
    // getter / setter
}

3.2 在 Controller 中触发校验

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

关键点在于 @Valid（或 @Validated）。一旦校验失败，Spring 会抛出 MethodArgumentNotValidException，默认返回 400。但默认错误信息可读性差，需要统一处理。

四、统一异常处理：让错误信息可读

通过 @RestControllerAdvice 集中拦截校验异常，返回结构化错误信息：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result handleValidException(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
                .map(f -> f.getField() + ": " + f.getDefaultMessage())
                .collect(Collectors.joining("; "));
        return Result.fail(400, msg);
    }
    @ExceptionHandler(ConstraintViolationException.class)
    public Result handleConstraintViolation(ConstraintViolationException e) {
        String msg = e.getConstraintViolations().stream()
                .map(ConstraintViolation::getMessage)
                .collect(Collectors.joining("; "));
        return Result.fail(400, msg);
    }
}

这样，前端收到的不再是 500，而是明确的字段级错误提示，排查成本大幅降低。

五、进阶场景与常见坑

5.1 分组校验

同一个 DTO 在新增和更新时校验规则不同。可通过分组接口解决：

public interface Create {}
public interface Update {}
public class UserDTO {
    @Null(groups = Create.class, message = "新增时不能指定ID")
    @NotNull(groups = Update.class, message = "更新时必须指定ID")
    private Long id;
}

Controller 中使用 @Validated(Create.class) 指定分组。

5.2 嵌套对象校验

DTO 中嵌套其他对象时，需在字段上追加 @Valid，否则嵌套规则不会生效：

public class OrderDTO {
    @Valid
    @NotNull(message = "用户信息不能为空")
    private UserDTO user;
}

5.3 自定义约束

标准注解无法覆盖业务语义时，可实现自定义注解。例如校验“手机号”：

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

校验器实现 ConstraintValidator 接口，内部编写具体逻辑。自定义约束适合复用频率高、规则稳定的场景。

5.4 方法级校验

对于非 DTO 参数（如路径变量、查询参数），可在 Controller 类上标注 @Validated，并在方法参数上直接使用约束注解：

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

此时校验失败会抛出 ConstraintViolationException，需在全局异常处理器中单独处理。

六、校验之外的兜底与观测

参数校验解决的是“入口拦截”，但要构建完整防护体系，还需注意：

1. 数据库约束不可省略。NOT NULL、唯一索引、CHECK 是最后一道防线，即使应用层校验被绕过，也能防止脏数据落库。
2. 业务规则下沉到 Service。例如“用户名不能重复”“年龄必须与身份证一致”等依赖外部状态的规则，无法通过注解完成，需在 Service 层显式校验。
3. 日志与监控。对校验失败请求记录关键字段（注意脱敏），便于分析攻击模式或前端 bug。
4. 错误码规范。区分参数错误、业务错误、系统错误，便于前端分类处理。

七、总结

优雅的接口参数校验，本质是在正确的层次做正确的事：

• Controller 层用 Bean Validation 做结构与语义校验，成本低、覆盖面广；
• 全局异常处理让错误信息可读、可定位；
• 分组、嵌套、自定义约束应对复杂场景；
• Service 层与数据库约束作为业务规则与兜底保障；
• 日志与错误码体系提升可观测性。

把这些组合起来，才能真正避免“空用户名返回 500”“年龄为负入库成功”“邮箱格式错误延迟爆炸”这类问题，让接口在入口处就保持干净与可靠。