@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 區分不同場景的增強類。