真正有效的顶层统一拦截需分场景、有层次地收口：Web层用@RestControllerAdvice按异常类型分级处理并返回统一结构；非Web或异步场景设Thread默认处理器记录堆栈与上下文；须自定义语义化异常类并配合日志与MDC追踪。
Java 运行时异常（RuntimeException 及其子类）默认不强制捕获，但若放任不管，会导致接口突然报错、日志散乱、前端收到 500 或空响应。真正有效的顶层统一拦截，不是靠层层 try-catch，而是分场景、有层次地收口。
Web 层：用 @RestControllerAdvice 拦截 Controller 抛出的异常
这是 Spring Boot 项目中最常用、最推荐的第一道防线。它只捕获从 @Controller 或 @RestController 方法中向上抛出的异常，不涉及 Service 异步线程或 Filter 中的异常。
- 定义一个全局处理器类，加上
@RestControllerAdvice注解（比@ControllerAdvice + @ResponseBody更简洁） - 用多个
@ExceptionHandler方法分别处理不同异常类型，例如：-
@ExceptionHandler(NullPointerException.class)→ 记录为“参数校验缺失”，返回 400 -
@ExceptionHandler(IllegalArgumentException.class)→ 归为“客户端输入错误”，附带错误码 -
@ExceptionHandler(BusinessException.class)→ 直接映射业务语义，如订单超时、库存不足 -
@ExceptionHandler(RuntimeException.class)→ 最后兜底，避免漏掉未明确定义的运行时异常
-
- 每个方法返回统一结构体（如
Result, Error>或ErrorResponse），含状态码、错误码、提示消息
非 Web 环境或异步线程：设置 Thread 默认未捕获处理器
@RestControllerAdvice 对 @Async 方法、定时任务、线程池任务、静态块初始化等场景无效。这时需 JVM 级兜底：
java-api-doc-generator
下载
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 在应用启动时（如
@PostConstruct或main方法开头）调用：Thread.setDefaultUncaughtExceptionHandler((t, e) -> { ... }) - 处理器中应至少做三件事：记录完整堆栈（用 logger.error）、标记线程名与上下文、发送告警（可选）
- 注意：该处理器不会捕获
Error（如OutOfMemoryError），这类问题需靠监控和 JVM 参数提前规避
让异常语义清晰，而不是泛泛而捕
统一拦截的前提是异常本身有区分度。不建议只写 catch (RuntimeException e) 然后一概打日志了事。
立即学习“Java免费学习笔记（深入）”；
- 自定义运行时异常类（如
ValidationFailedException、ResourceLockedException），继承RuntimeException - 业务方法中主动抛出这些语义明确的异常，而非依赖
NullPointerException等底层异常来传递业务含义 - 在
@ExceptionHandler方法里，根据异常类型返回不同 HTTP 状态码（如 400、409、422）和错误码，便于前端精准处理
补充：别忘了日志与可观测性
拦截不是终点，而是统一治理的起点：
- 所有拦截逻辑必须记录 ERROR 级别日志，包含异常全类名、消息、堆栈，以及关键业务字段（如 orderNo、userId）
- 结合 MDC（Mapped Diagnostic Context）注入请求 ID，让日志可追踪
- 对高频出现的运行时异常（如重复提交导致的乐观锁失败），可加埋点统计，推动上游优化
