深入理解 Spring 的 @ControllerAdvice

在构建 Spring MVC Web 应用时，我们每天都在编写 @Controller 或 @RestController 来处理各类请求。但你是否遇到过这些令人头疼的场景？

• 重复的异常处理：在每个控制器中一遍又一遍地写着相同的 try-catch 来处理 NullPointerException 或 ServiceException。
• 全局数据绑定：需要为每一个页面的渲染提前注入一些通用数据，比如用户信息、系统配置等。
• 统一的模型增强：在所有控制器方法执行后，都想对 Model 模型做一些统一的加工处理。

如果你对上述问题频频点头，那么恭喜你，Spring 为你准备了一把名为 @ControllerAdvice 的“瑞士军刀”。它允许你将这些横切关注点（Cross-Cutting Concerns）从具体的业务控制器中剥离出来，实现优雅、集中式的全局处理。

一、什么是 @ControllerAdvice？

简单来说，@ControllerAdvice 是一个组件注解（被 @Component 元注解标注），它允许你将一个类声明为一个全局的、跨多个控制器的增强器（Advice）。

你可以把它理解为 Spring MVC 版本的 AOP（面向切面编程），但它不是基于代理，而是专门为控制器层设计的。它能够拦截所有或指定的控制器方法，在其执行前后施加统一的逻辑，实现三大核心功能：

1. 全局异常处理 (@ExceptionHandler)
2. 全局数据绑定 (@ModelAttribute)
3. 全局数据预处理 (@InitBinder)

二、核心功能与实战代码

让我们通过代码来逐一感受它的强大之处。

1. 全局异常处理 (@ExceptionHandler)

这是 @ControllerAdvice 最常用、最受欢迎的功能。

场景：避免在单个 Controller 中处理异常，提供统一的 API 错误响应或错误页面。

@RestControllerAdvice // 等同于 @ControllerAdvice + @ResponseBody
public class GlobalExceptionHandler {
   
   

    /**
     * 处理自定义的业务异常
     */
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ApiResponse<?>> handleBusinessException(BusinessException ex) {
   
   
        ApiResponse<?> apiResponse = ApiResponse.fail(ex.getCode(), ex.getMessage());
        return new ResponseEntity<>(apiResponse, HttpStatus.BAD_REQUEST);
    }

    /**
     * 处理系统内置的异常，如参数缺失等
     */
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ApiResponse<?>> handleValidationException(MethodArgumentNotValidException ex) {
   
   
        String errorMessage = ex.getBindingResult().getFieldErrors().stream()
                .map(FieldError::getDefaultMessage)
                .collect(Collectors.joining(", "));
        ApiResponse<?> apiResponse = ApiResponse.fail(400, "参数校验失败: " + errorMessage);
        return new ResponseEntity<>(apiResponse, HttpStatus.BAD_REQUEST);
    }

    /**
     * 处理所有未明确捕获的异常，作为最后的兜底方案
     */
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ApiResponse<?>> handleGlobalException(Exception ex) {