@ControllerAdvice 是 Spring Boot 全局异常处理核心机制，通过 @ExceptionHandler 统一捕获控制器层异常；支持按异常类型分类响应、灵活控制 HTTP 状态码与返回结构；需注意仅拦截控制器直接抛出的异常，避免异步或已捕获异常绕过处理。
@ControllerAdvice 是 Spring Boot 中用于实现全局异常处理的核心机制，它能统一捕获控制器层（@Controller 或 @RestController）抛出的异常，避免重复编写 try-catch，提升代码可维护性和响应一致性。
一、基础用法：定义全局异常处理器
创建一个被 @ControllerAdvice 注解标记的类，再配合 @ExceptionHandler 方法，即可拦截指定类型的异常：
- 该类默认作用于所有 @Controller 和 @RestController，也可通过
basePackages或assignableTypes限定范围 - 每个 @ExceptionHandler 方法接收对应异常类型参数，并返回统一响应（如 ResponseEntity 或自定义 JSON 结构）
- 方法内可记录日志、转换错误码、屏蔽敏感信息
二、处理不同异常类型，返回结构化响应
推荐按异常严重程度和业务场景分类处理，例如：
- 业务异常（如 ServiceException）：返回 200 状态码 + 自定义错误码和提示，前端友好
- 参数校验异常（MethodArgumentNotValidException）：提取 @Valid 校验失败字段，返回详细错误信息
- 系统异常（Exception）：记录堆栈日志，返回通用错误码（如 500），不暴露内部细节
- HTTP 状态异常（如 HttpRequestMethodNotSupportedException）：映射为 405，明确提示请求方法不支持
三、配合 @ResponseBody 和 ResponseEntity 灵活控制响应
若类上加了 @RestControllerAdvice（等价于 @ControllerAdvice + @ResponseBody），方法可直接返回对象，Spring 自动序列化为 JSON；否则需显式使用 ResponseEntity 控制状态码与响应体：
立即学习“Java免费学习笔记（深入）”；
- 返回
ResponseEntity<Result>可精确设置 HTTP 状态码（如 HttpStatus.BAD_REQUEST） - 避免在异常处理器中抛出新异常，防止二次进入异常处理链
- 可通过 @Order 或实现 Ordered 接口控制多个 @ControllerAdvice 的执行优先级
四、注意事项与常见陷阱
实际使用中容易忽略的关键点：
- 异常必须是控制器方法**直接抛出**的，异步线程（如 @Async）、过滤器、拦截器中的异常不会被拦截
- 若 Controller 中已用 try-catch 吞掉异常，或手动 return 错误响应，则 @ExceptionHandler 不会触发
- 自定义异常建议继承 RuntimeException，避免强制声明 throws，更符合 REST API 设计习惯
- 生产环境务必关闭堆栈信息输出，敏感字段（如数据库错误）需脱敏或替换为通用提示
