在Java里如何统一异常处理_Java全局异常设计说明_技术教程

@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 并吞掉异常的代码。

适合场景：全局日志记录、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 类配置，避免覆盖默认错误映射

统一异常处理最易被忽略的其实是分层边界：Controller 层异常归 @ControllerAdvice，异步任务归 ExecutorService 的 uncaughtExceptionHandler，定时任务归 @Scheduled 的 errorHandler 配置，而过滤器链中的异常需要额外通过 OncePerRequestFilter 包裹或自定义 ErrorPageFilter。不同位置得用不同的钩子，混用会导致漏处理。