Spring异常处理指南：@ExceptionHandler实战应用

本文深入剖析了Spring中@ExceptionHandler的实战陷阱与最佳实践，揭示其仅限单个Controller生效的本质，并强调全局异常处理必须搭配@ControllerAdvice；明确区分运行时异常与受检异常的处理机制，指出盲目使用@ExceptionHandler(Exception.class)往往失效的根本原因；同时强调返回值必须选用ResponseEntity以精准控制HTTP状态码和响应体，避免前后端分离场景下的序列化混乱；最后直击日志痛点——唯有正确记录完整堆栈、请求上下文和异常链，才能让线上问题排查真正高效可靠。

@ExceptionHandler 只对当前 Controller 有效，跨 Controller 不生效

很多人以为加了 @ExceptionHandler 就能捕获整个应用的异常，结果在 A Controller 里写的处理逻辑，B Controller 抛出同样异常却进不去——因为 @ExceptionHandler 默认只作用于声明它的那个 @Controller 类内部。

实操建议：

• 如果想全局生效，必须配合 @ControllerAdvice 使用，且该类不能被 @RestController 修饰（否则返回 JSON 的逻辑可能被干扰）
• @ControllerAdvice 类默认扫描所有 @Controller，但可通过 basePackages 或 assignableTypes 精确控制范围
• 多个 @ControllerAdvice 存在时，按类名字母序执行，顺序不可控；如需优先级，加 @Order 注解（值越小越靠前）

捕获 Exception 和 RuntimeException 的区别要写清楚

Spring MVC 默认只把未被捕获的 RuntimeException 和其子类交由异常处理器处理；而受检异常（比如 IOException）如果没在方法签名里显式 throws，编译都过不去，更不会走到 @ExceptionHandler。

常见错误现象：@ExceptionHandler(Exception.class) 看似“兜底”，但实际可能根本触发不了——因为很多业务异常是受检异常，没抛出来就被 try-catch 吞掉了，或者压根没 throw。

实操建议：

• 明确区分：用 @ExceptionHandler(RuntimeException.class) 捕运行时异常，用 @ExceptionHandler(CustomBizException.class) 捕自定义业务异常（推荐继承 RuntimeException）
• 不要依赖 Exception.class 做兜底，它容易掩盖真实问题；真要兜底，也建议限定为 Throwable.class 并记录完整堆栈
• 若必须处理受检异常，确保 controller 方法签名中声明了 throws，且没被中间层提前 catch

返回值类型决定响应体结构和 HTTP 状态码

@ExceptionHandler 方法返回值不是随便写的，它直接绑定到 HTTP 响应：返回 String 可能被当成视图名，返回 ResponseEntity 才能精确控制状态码和 body。

性能 / 兼容性影响：用 ModelAndView 返回页面在前后端分离项目里会引发 Content-Type 不一致、前端拿不到 JSON 等问题；而忽略状态码（比如始终返回 200）会让前端无法做统一错误拦截。

实操建议：

• WebFlux 或纯 REST API 场景下，一律用 ResponseEntity，手动设 HttpStatus
• 避免返回 String 或 void，除非你真在写传统 JSP 页面
• 如果用了 @ResponseBody，注意它和 @RestController 的隐式行为冲突，可能导致序列化两次

日志记录位置不对，线上排查就抓瞎

很多人把异常打印写在 @ExceptionHandler 方法开头，结果发现日志里只有 “xxxException: msg”，没有堆栈——因为 Spring 已经把原始异常对象传进来了，但你没调用 e.printStackTrace() 或用 log 框架的 error(String, Throwable) 重载。

容易踩的坑：

• 只记录 e.getMessage()，丢掉 cause chain 和 stack trace
• 在 finally 或其他地方又 catch 了一次，导致原始异常被覆盖
• 用 SLF4J 时写了 log.error("handle error", e) 却忘了第一个参数是格式化模板，实际应写成 log.error("handle error: {}", e.getMessage(), e) 才能输出堆栈

复杂点在于：有些异常（比如 HttpMessageNotReadableException）本身不带完整上下文，需要结合 request URI、body 内容一起记录，否则单看异常类型根本定位不到问题源头。

今天关于《Spring异常处理指南：@ExceptionHandler实战应用》的内容就介绍到这里了，是不是学起来一目了然！想要了解更多关于的内容请关注golang学习网公众号！