@ControllerAdvice配合@ExceptionHandler可统一处理Controller层异常，需用@RestControllerAdvice返回JSON；非Web环境用Thread.setDefaultUncaughtExceptionHandler兜底；自定义异常无需继承RuntimeException，但推荐继承以符合业务异常设计规范。
Spring Boot 项目中用 @ControllerAdvice 拦截所有 Controller 异常
只要你的异常是从 Controller 层抛出的（包括 @RestController），@ControllerAdvice 就是最直接有效的统一处理方式。它不拦截 Filter、Interceptor 或 Service 层未上抛到 Web 层的异常。
关键点：
- 必须配合
@ExceptionHandler使用，每个方法处理一类异常 - 推荐单独写一个类，加上
@RestControllerAdvice（比@ControllerAdvice+@ResponseBody更简洁） - 方法返回值会自动序列化为 JSON，前提是项目引入了
spring-boot-starter-web - 多个
@ExceptionHandler方法之间按继承关系匹配：子类异常优先于父类（如IllegalArgumentException优先于RuntimeException）
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(NullPointerException.class)
public ResponseEntity handleNPE(NullPointerException e) {
return ResponseEntity.status(400).body("参数为空");
}
@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity> handleValidation(MethodArgumentNotValidException e) {
Map errors = new HashMap<>();
e.getBindingResult().getFieldErrors().forEach(error ->
errors.put(error.getField(), error.getDefaultMessage())
);
return ResponseEntity.badRequest().body(errors);
}
}
非 Spring MVC 环境下无法用 @ControllerAdvice？用 Thread.setDefaultUncaughtExceptionHandler
如果你在写工具类、定时任务（@Scheduled）、或纯 Java SE 模块，@ControllerAdvice 完全不生效。此时要靠 JVM 级别的兜底机制。
注意：Thread.setDefaultUncaughtExceptionHandler 只捕获未被任何 try-catch 捕获的、线程内抛出的异常，且仅对当前 JVM 生效，不适用于已显式 catch 并吞掉异常的代码。
立即学习“Java免费学习笔记（深入）”；
- 适合场景：全局日志记录、JVM 退出前保存状态、发送告警
- 不适用于构造 HTTP 响应体（因为没有 request/response 上下文）
- 务必在应用启动早期注册，比如
main方法第一行，或 Spring 的@PostConstruct中 - 该 handler 不会自动传播异常，也不会中断当前线程执行流以外的行为
public class UncaughtHandler implements Thread.UncaughtExceptionHandler {
@Override
public void uncaughtException(Thread t, Throwable e) {
System.err.println("线程 [" + t.getName() + "] 未捕获异常: " + e.getMessage());
// 记录到 ELK / Sentry / 文件等
}
}
// 启动时注册
public static void main(String[] args) {
Thread.setDefaultUncaughtExceptionHandler(new UncaughtHandler());
SpringApplication.run(App.class, args);
}
自定义异常类必须继承 RuntimeException 才能被 @ControllerAdvice 捕获？
不是必须，但取决于你是否希望它「默认不强制 try-catch」。Spring 的异常解析机制本身不区分 checked/unchecked，@ExceptionHandler 能匹配任意类型异常——只要你显式声明了对应类型。
真正影响行为的是两点：
-
Exception子类（checked 异常）：调用方必须try-catch或声明throws，否则编译失败 -
RuntimeException子类（unchecked 异常）：可自由抛出，适合业务逻辑中“不该发生但发生了”的错误（如参数校验失败、状态不一致） - Spring 默认的
ResponseStatusExceptionResolver仅对带@ResponseStatus注解的异常生效，与是否继承RuntimeException无关
建议实践：
- 定义统一基类，如
BusinessException extends RuntimeException - 所有业务异常都继承它，并携带
errorCode和message - 在
@ExceptionHandler中统一处理BusinessException，返回标准错误结构
为什么 500 错误没进 @ControllerAdvice，却进了 Tomcat 默认错误页？
典型现象：接口抛了 RuntimeException，但浏览器看到的是白页或 Tomcat 的 “HTTP Status 500”，而不是你定义的 JSON 错误响应。原因通常是以下之一：
- 异常发生在
@Controller之外：比如 Filter 中抛异常、Servlet 初始化失败、静态资源请求出错 - 项目里配置了
server.error.whitelabel.enabled=false但没配ErrorController，导致 Spring Boot 退回到容器默认错误处理 -
@ControllerAdvice类不在 Spring 扫描路径下（比如没加@Component或所在包没被@SpringBootApplication扫到） - 异常被更上层的 AOP、或者第三方库（如 Feign）提前捕获并转换了
快速验证方式：
- 在
@ControllerAdvice的方法里加断点或日志，看是否触发 - 临时在某个
@GetMapping里手动 throw new RuntimeException("test")，确认是否走你的 handler - 检查
application.properties是否有server.error.path=/error类配置，避免覆盖默认错误映射
@ControllerAdvice，异步任务归 ExecutorService 的 uncaughtExceptionHandler，定时任务归 @Scheduled 的 errorHandler 配置，而过滤器链中的异常需要额外通过 OncePerRequestFilter 包裹或自定义 ErrorPageFilter。不同位置得用不同的钩子，混用会导致漏处理。 
