SpringBoot 三大核心注解精讲：@ControllerAdvice、@RestControllerAdvice 与 @Validated 分组校验

在构建 RESTful 服务时，参数校验是保障数据一致性与接口健壮性的第一道防线。然而，许多开发者对校验失败后的处理方式仅仅停留在“抛出异常”阶段，导致前端收到 500 错误码与一大段堆栈信息，既无法定位用户输入问题，也破坏了接口的友好性。

这些现象的背后，往往是对 @ControllerAdvice、@RestControllerAdvice 以及 @Validated 分组校验这三个核心注解的理解不够深入。本文将从底层机制、适用场景与高级用法三个维度展开，帮助你构建一套完整的参数校验与统一异常处理体系。

一、为什么需要全局异常处理与分组校验

在未引入全局处理机制时，典型的控制器代码如下：

@PostMapping("/user")
public Result createUser(@RequestBody UserForm form) {
    if (form.getName() == null || form.getName().isBlank()) {
        throw new IllegalArgumentException("用户名不能为空");
    }
    // 更多手写校验...
    return Result.success(userService.create(form));
}

这种写法存在三个明显问题：

1. 校验逻辑与业务逻辑耦合：每个接口都要重复编写参数判断代码，违反 DRY 原则。
2. 异常响应格式不统一：不同接口抛出的异常类型不同，前端需要针对每种异常单独处理。
3. 错误信息暴露内部细节：未捕获的异常可能将堆栈信息直接返回给客户端，存在安全风险。

而 Spring 提供的 @Validated 与 @RestControllerAdvice 组合，恰好能解决上述痛点：前者负责声明式校验，后者负责统一拦截并格式化异常响应。

二、@ControllerAdvice 与 @RestControllerAdvice 的本质区别

2.1 注解的底层机制

@ControllerAdvice 是 Spring MVC 提供的一个增强型注解，其核心作用是将类标记为全局控制器增强器。被它标注的类可以包含以下三类方法：

• @ExceptionHandler：全局异常处理
• @InitBinder：全局请求参数绑定规则
• @ModelAttribute：全局模型属性填充

Spring 在启动时会扫描所有被 @ControllerAdvice 标记的类，并将其中带有上述注解的方法注册到相应的处理器映射中。当控制器抛出异常时，ExceptionHandlerExceptionResolver 会优先查找匹配的全局异常处理方法。

2.2 两者的唯一差异

@RestControllerAdvice 本质上是 @ControllerAdvice 与 @ResponseBody 的组合注解。它的定义如下：

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ControllerAdvice
@ResponseBody
public @interface RestControllerAdvice {
}

这意味着：

• 使用 @ControllerAdvice 时，若处理方法的返回值是对象，默认会作为视图名进行解析，适合传统页面渲染场景。
• 使用 @RestControllerAdvice 时，返回值会自动通过消息转换器序列化为 JSON，适合前后端分离的 RESTful 接口。

选型建议：在纯 RESTful 项目中统一使用 @RestControllerAdvice，避免因忘记添加 @ResponseBody 而导致返回视图解析异常。

2.3 统一异常处理的实战写法

以下是一个完整的全局异常处理器示例：

@RestControllerAdvice
public class GlobalExceptionHandler {
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationException(
            MethodArgumentNotValidException ex) {
        List<String> messages = ex.getBindingResult()
                .getFieldErrors()
                .stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.toList());
        ErrorResponse response = new ErrorResponse(
                HttpStatus.BAD_REQUEST.value(), "参数校验失败", messages);
        return ResponseEntity.badRequest().body(response);
    }
    @ExceptionHandler(ConstraintViolationException.class)
    public ResponseEntity<ErrorResponse> handleConstraintViolation(
            ConstraintViolationException ex) {
        List<String> messages = ex.getConstraintViolations()
                .stream()
                .map(ConstraintViolation::getMessage)
                .collect(Collectors.toList());
        return ResponseEntity.badRequest()
                .body(new ErrorResponse(400, "参数校验失败", messages));
    }
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleGenericException(Exception ex) {
        // 记录日志但不向前端暴露堆栈
        log.error("未预期异常", ex);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(new ErrorResponse(500, "服务器内部错误", null));
    }
}

上述代码中有三个关键点值得注意：

1. 异常类型精确匹配：MethodArgumentNotValidException 对应 @RequestBody 校验失败，ConstraintViolationException 对应方法参数级校验失败，两者需要分别处理。
2. 错误信息聚合：将多个字段的校验错误收集为列表返回，前端可一次性展示所有问题。
3. 兜底处理：通过 @ExceptionHandler(Exception.class) 捕获未预期异常，避免堆栈泄露。

三、@Validated 分组校验的高级用法

3.1 为什么需要分组校验

同一个实体在不同业务场景下往往有不同的校验规则。例如，创建用户时 ID 必须为空，而更新用户时 ID 必须非空。若只使用一套约束注解，就无法区分场景。

3.2 分组接口的定义与使用

首先定义分组标记接口：

public interface CreateGroup {}
public interface UpdateGroup {}

然后在实体上通过 groups 属性指定约束所属分组：

public class UserForm {
    @Null(message = "创建时ID必须为空", groups = CreateGroup.class)
    @NotNull(message = "更新时ID不能为空", groups = UpdateGroup.class)
    private Long id;
    @NotBlank(message = "用户名不能为空", groups = {CreateGroup.class, UpdateGroup.class})
    private String name;
    @Email(message = "邮箱格式不正确", groups = CreateGroup.class)
    private String email;
}

在控制器中通过 @Validated 指定激活的分组：

@PostMapping("/user")
public Result createUser(
        @Validated(CreateGroup.class) @RequestBody UserForm form) {
    return Result.success(userService.create(form));
}
@PutMapping("/user")
public Result updateUser(
        @Validated(UpdateGroup.class) @RequestBody UserForm form) {
    return Result.success(userService.update(form));
}

3.3 分组校验的继承与顺序

分组接口支持继承。若定义 public interface CreateGroup extends Default {}，则未显式指定分组的约束也会在 CreateGroup 激活时生效。此外，还可以通过 @GroupSequence 指定分组的校验顺序，实现“先校验基础字段，再校验复杂字段”的渐进式校验策略。

@GroupSequence({BasicCheck.class, AdvancedCheck.class, UserForm.class})
public interface OrderedCheck {}

四、常见陷阱与最佳实践

陷阱	表现	解决方案
异常类型混淆	@RequestBody 校验失败抛 MethodArgumentNotValidException，方法参数校验失败抛 ConstraintViolationException	分别编写处理方法
分组未生效	在 @Valid 上使用分组，而非 @Validated	分组校验必须使用 @Validated
嵌套对象校验失效	对象属性未添加 @Valid	在嵌套字段上补充 @Valid
全局异常处理器顺序错误	具体异常被通用异常拦截	将具体异常处理方法置于通用方法之前，或使用 @Order 控制优先级

五、总结

@ControllerAdvice 与 @RestControllerAdvice 解决了异常响应的统一性问题，而 @Validated 分组校验则解决了同一实体在不同场景下的差异化校验需求。三者结合使用，可以构建出一套既简洁又健壮的参数校验体系。

核心要点回顾：

• @RestControllerAdvice = @ControllerAdvice + @ResponseBody，RESTful 项目首选。
• 不同校验场景抛出的异常类型不同，需分别处理并聚合错误信息。
• 分组校验必须通过 @Validated 激活，并注意分组接口的继承与顺序。
• 始终保留兜底异常处理，避免堆栈信息泄露给客户端。

掌握这些机制后，参数校验将不再是“加了就能用”的黑盒，而是可观测、可定制、可复用的基础设施。