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`

关键总结

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