spring mvc 异常处理中@RestControllerAdvice 和 @ControllerAdvice 对比详解

@RestControllerAdvice 和 @ControllerAdvice 对比详解

---

1. 基本概念

注解	等效组合	核心作用
@ControllerAdvice	@Component + @RequestMapping（隐式）	定义全局控制器增强类，处理跨控制器的异常、数据绑定或全局响应逻辑。
@RestControllerAdvice	@ControllerAdvice + @ResponseBody	继承 @ControllerAdvice，并默认将返回值序列化为 HTTP 响应体（如 JSON）。

---

2. 核心区别

对比维度	@ControllerAdvice	@RestControllerAdvice
返回值处理	默认返回视图名称（需配合 @ResponseBody 才能序列化）	直接返回数据对象，自动序列化为响应体（如 JSON）
适用场景	传统 MVC 应用（如返回 HTML 视图或混合响应）	RESTful API（需返回 JSON/XML 格式数据）
注解组合	需手动添加 @ResponseBody 才能返回 JSON	内置 @ResponseBody，无需额外声明
返回类型示例	String（视图名称）、ModelAndView	ResponseEntity, Map, 自定义 POJO

---

3. 代码示例对比

场景：全局异常处理

@ControllerAdvice 示例（返回视图名称）

@ControllerAdvice
public class GlobalViewExceptionHandler {
    @ExceptionHandler(IOException.class)
    public String handleIOException() {
        return "error/500"; // 返回视图名称（如 Thymeleaf 模板）
    }
}

@RestControllerAdvice 示例（返回 JSON）

@RestControllerAdvice
public class GlobalApiExceptionHandler {
    @ExceptionHandler(IOException.class)
    public ResponseEntity<ErrorDetails> handleIOException() {
        ErrorDetails error = new ErrorDetails(500, "Internal Server Error", null);
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(error);
    }
}

---

4. 关键功能对比

功能	@ControllerAdvice	@RestControllerAdvice
异常处理	支持，需手动定义返回类型（视图或 JSON）	支持，直接返回 JSON 格式错误对象
数据绑定	可通过 @InitBinder 统一配置绑定规则	同样支持 @InitBinder，但返回值默认序列化
全局方法增强	可通过 @ModelAttribute 注入公共数据	同样支持，但返回数据自动序列化
响应体控制	需显式使用 @ResponseBody 或 ResponseEntity	内置 @ResponseBody，无需额外声明

---

5. 配置与扩展

共同特性

• 包级作用域：通过 basePackages 指定需要增强的控制器包：

  @ControllerAdvice(basePackages = "com.example.controllers")
  

• 方法级过滤：通过 annotations 指定仅处理特定注解的控制器：

  @ControllerAdvice(annotations = RestController.class)
  

差异点

• 响应体格式：

  • @ControllerAdvice 需显式配置 @ResponseBody 或 ResponseEntity 才能返回 JSON：

    @ControllerAdvice
    public class MixHandler {
        @ResponseBody // 显式声明返回 JSON
        @ExceptionHandler(IOException.class)
        public ErrorDetails handleIOException() { ... }
    }
    

  • @RestControllerAdvice 默认支持序列化：

    @RestControllerAdvice
    public class ApiHandler {
        @ExceptionHandler(IOException.class)
        public ErrorDetails handleIOException() { ... } // 自动序列化为 JSON
    }
    

---

6. 典型使用场景

场景	推荐注解	原因
传统 Web 应用（返回 HTML）	@ControllerAdvice	需返回视图名称（如 Thymeleaf 模板路径）。
RESTful API 异常处理	@RestControllerAdvice	直接返回结构化的 JSON 错误信息，无需额外配置 @ResponseBody。
混合场景（需同时处理视图和 JSON）	@ControllerAdvice	需通过 @ResponseBody 区分返回类型，或使用 ResponseEntity 控制响应格式。

---

7. 总结表格

维度	@ControllerAdvice	@RestControllerAdvice
核心作用	全局异常处理、数据绑定、视图增强	专为 REST API 设计，返回 JSON 格式响应
返回值默认行为	返回视图名称或需 @ResponseBody 显式声明	直接返回数据对象，自动序列化为响应体
适用场景	传统 MVC 应用、混合响应场景	纯 REST API 开发（如 Spring Boot 微服务）
注解组合关系	独立注解，需手动配置响应格式	等效于 @ControllerAdvice + @ResponseBody

---

关键总结

1. 选择原则：
   • REST API：优先使用 @RestControllerAdvice，简化 JSON 响应处理。
   • 传统 MVC：使用 @ControllerAdvice，灵活控制视图或 JSON 响应（需配合 @ResponseBody）。
2. 注意事项：
   • @ControllerAdvice 若需返回 JSON，必须显式添加 @ResponseBody 或使用 ResponseEntity。
   • @RestControllerAdvice 内置 @ResponseBody，无需额外声明，适合统一 API 响应格式。
3. 最佳实践：
   • 对于纯 API 项目，用 @RestControllerAdvice 集中处理异常和响应。
   • 在混合项目中，通过 basePackages 区分不同场景的增强类。