@RestControllerAdvice 的注解作用和使用

@RestControllerAdvice 是 Spring Framework(4.3+)引入的一个组合注解,专门用于 RESTful API 的全局异常处理 和全局响应增强。

1. 核心作用

它本质上是 @ControllerAdvice + @ResponseBody 的组合:

  • 全局拦截:对指定范围内的 Controller 进行 AOP 切面拦截。
  • 自动序列化 :其内部方法(如 @ExceptionHandler、@ModelAttribute)的返回值会自动通过 HttpMessageConverter 序列化为 JSON/XML,无需再单独标注 @ResponseBody。
  • 统一封装:常用于统一异常响应格式、统一成功响应包装、全局参数绑定等。

2. 关键属性

属性 说明
value / basePackages 限定生效的包路径,不填则全局生效
assignableTypes 限定生效的 Controller 类类型
annotations 限定生效的 Controller 注解(如仅对 @RestController 生效)

3. 使用示例:统一异常处理

定义统一响应体
java 复制代码
@Data
@AllArgsConstructor
public class ApiResponse<T> {
    private int code;
    private String message;
    private T data;

    public static <T> ApiResponse<T> error(int code, String msg) {
        return new ApiResponse<>(code, msg, null);
    }
}
自定义业务异常
java 复制代码
@Getter
public class BusinessException extends RuntimeException {
    private final int code;
    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }
}
全局异常处理器
java 复制代码
@RestControllerAdvice(basePackages = "com.example.api")
@Slf4j
public class GlobalExceptionHandler {

    // 处理自定义业务异常
    @ExceptionHandler(BusinessException.class)
    public ApiResponse<?> handleBusiness(BusinessException e) {
        log.warn("业务异常: {}", e.getMessage());
        return ApiResponse.error(e.getCode(), e.getMessage());
    }

    // 处理参数校验异常 (JSR-303)
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResponse<?> handleValidation(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
                .map(f -> f.getField() + ": " + f.getDefaultMessage())
                .collect(Collectors.joining("; "));
        return ApiResponse.error(400, msg);
    }

    // 兜底:所有未捕获异常
    @ExceptionHandler(Exception.class)
    public ApiResponse<?> handleUnknown(Exception e) {
        log.error("未知异常", e);
        return ApiResponse.error(500, "服务器内部错误");
    }
}

4. 与 @ControllerAdvice 的区别

特性 @ControllerAdvice @RestControllerAdvice
返回视图 ✅ 支持 ❌ 不支持
自动 JSON 序列化 需配合 @ResponseBody ✅ 内置
适用场景 MVC 混合项目 纯 REST API 项目

最佳实践 :在纯前后端分离的 REST 项目中,优先使用 @RestControllerAdvice;若项目同时包含页面渲染和 API 接口,使用 @ControllerAdvice 并在需要 JSON 的方法上单独加 @ResponseBody。

相关推荐
学长毕设1 小时前
基于SpringBoot非遗文化展示与传播平台设计与实现-附源码
java·spring boot·后端
金銀銅鐵3 小时前
用 Swing 重做操作数栈演示
java·jvm·后端
琳少_3 小时前
java程序开发笔记
java·开发语言·数据库·笔记
叼烟扛炮5 小时前
[LangChain] 学习笔记(15):为什么你的重试没用——429、抖动、fallback 与熔断
java·服务器·前端
文丑颜不良啊5 小时前
LeetCode3401~3420题目解析
java·leetcode
文丑颜不良啊7 小时前
LeetCode3421~3440题目解析
java·leetcode
code2cat8 小时前
【随笔】Java客户端选了HTTP/3,怎样知道请求实际走了哪个版本
java·开发语言·http
码云社区9 小时前
Java在线租房系统源码:VR看房素材、房源图片与内容维护方案
java·vue.js·vr·租房小程序·在线租房·看房租房
码云社区9 小时前
Spring Boot智慧物业系统源码:合同到期提醒、续签资料与资产协作
java·spring boot·后端·物业管理·物业系统·智慧物业