Spring全局异常处理自定义方法详解

本文深入剖析了Spring应用中全局异常处理的常见误区与最佳实践，揭示了@ControllerAdvice为何无法捕获404/500等容器级错误，并系统梳理了分层解决方案：控制器异常用@ControllerAdvice+@ExceptionHandler精准拦截，非控制器异常则需通过自定义ErrorController或ErrorPageRegistrar接管/error端点；同时延伸覆盖Java原生线程异常兜底、Jackson序列化字段对齐、生产环境敏感信息屏蔽、网关/Nginx错误响应透传、以及跨服务调用异常链路断裂等高频痛点，为构建健壮、统一、前后端友好的异常处理体系提供全栈视角的落地指南。

Spring Boot 里用 @ControllerAdvice 拦不住 404 和 500？

不是 @ControllerAdvice 失效，而是它默认只捕获控制器层抛出的异常（比如 @RequestMapping 方法里 throw 的），不处理容器级错误，比如路径不存在（404）、Servlet 初始化失败（500）、静态资源找不到等。

真正要统一格式，得区分两层：控制器异常（可用 @ControllerAdvice）和非控制器异常（需配置 ErrorPageRegistrar 或 server.error.whitelabel.enabled=false + 自定义 ErrorController）。

• 404、405、500 这类由 Spring Boot 内置 BasicErrorController 处理，它会走 /error 端点 —— 所以你得自己写一个 @RestController 实现 ErrorController 接口，而不是只靠 @ControllerAdvice
• @ControllerAdvice 配合 @ExceptionHandler 只对 @Controller / @RestController 方法中显式抛出的异常生效；如果 filter 中 throw 异常、或 AOP around 切面里没 catch，它也收不到
• 别在 @ControllerAdvice 里返回 ModelAndView，前后端分离项目统一用 @ResponseBody 或直接继承 ResponseEntityExceptionHandler

普通 Java 项目（非 Spring）怎么全局捕获未处理异常？

靠 Thread.setDefaultUncaughtExceptionHandler，但注意它只管「当前线程」，主线程、线程池里的子线程都得单独设，否则照样打印堆栈到控制台。

常见漏点是：用了 Executors.newFixedThreadPool 却没给线程池配 ThreadFactory，导致 worker 线程崩溃时没人兜底。

• 主线程异常直接设：Thread.setDefaultUncaughtExceptionHandler((t, e) -> log.error("Uncaught in thread {}", t.getName(), e));
• 线程池必须自定义 ThreadFactory，把 handler 传进去：new ThreadFactoryBuilder().setUncaughtExceptionHandler(handler).build()（用 Guava）或手写实现 ThreadFactory
• 千万别在 handler 里 throw 新异常，否则 JVM 直接退出；日志记录后应静默结束
• 这个机制捕获不到 OutOfMemoryError 这类致命错误，JVM 可能来不及调用 handler

@ControllerAdvice 返回 JSON 格式但字段名不对？

因为默认用的是 Jackson 序列化，而你的异常类字段是 errorCode，前端却想要 code —— 不是框架问题，是序列化配置没对齐。

别改异常类加 @JsonProperty，那样污染业务代码；应该统一在全局配置里做映射。

• 在 @ControllerAdvice 的 @ExceptionHandler 方法里，手动构造 Map 或用专用响应类（如 Result），确保 key 名固定
• 如果想复用已有异常类，加配置：spring.jackson.property-naming-strategy=KEBAB_CASE（对应 error_code → error-code），但不如显式构造可控
• 注意 ResponseEntityExceptionHandler 默认返回的 timestamp 是 Instant，前端解析可能出错，建议转成 long 毫秒或标准 ISO 字符串

为什么线上环境还是看到白页或原始堆栈？

大概率是 server.error.include-message 和 server.error.include-binding-errors 在生产环境没关，或者前端没正确处理 HTTP 状态码，把 500 当 200 解析了。

Spring Boot 2.3+ 默认关闭敏感信息输出，但老版本或自定义配置可能开着；更隐蔽的是 Nginx 或网关层吞掉了错误响应体，只返回空 500。

• 确认配置：server.error.include-message=never、server.error.include-stacktrace=never（生产必须关）
• 检查网关（如 Spring Cloud Gateway）是否配置了 GlobalFilter 吞异常，或 Nginx 的 error_page 500 /500.html 覆盖了后端响应
• 前端 fetch 必须检查 response.ok === false 或 response.status >= 400，不能只看 data.code === 0

最麻烦的其实是跨服务调用场景：A 服务抛了异常，B 服务用 RestTemplate 调用时没设置 setErrorHandler，结果 B 收到的是 500 响应体字符串，根本进不了自己的异常处理器。这种链路得靠统一的 client SDK 封装，而不是每个地方重复判断。

理论要掌握，实操不能落！以上关于《Spring全局异常处理自定义方法详解》的详细介绍，大家都掌握了吧！如果想要继续提升自己的能力，那么就来关注golang学习网公众号吧！