@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。