Java项目统一异常处理设计技巧

本文深入剖析了Java项目中构建高可用统一异常处理机制的关键实践，涵盖@ControllerAdvice失效的三大常见原因（扫描范围、优先级冲突、默认错误页干扰）、业务异常与系统异常的语义化分层策略、@ExceptionHandler参数与返回值的精准写法（推荐ResponseEntity以灵活控制状态码和响应体），以及日志记录中不可或缺的请求上下文捕获与敏感信息脱敏技巧——不仅教你“怎么写”，更强调“为什么这样写”才能让异常真正成为可定位、可感知、可运维的系统能力。

SpringMVC里@ControllerAdvice不生效？检查这三处

最常见的情况不是写得不对，而是没被扫描到或优先级冲突。@ControllerAdvice 类必须被 Spring 容器管理，且不能和 @RestController 或其他异常处理器重叠覆盖。

• 确保该类在 @ComponentScan 范围内，或显式用 @Configuration + @Bean 注册
• 如果用了多个 @ControllerAdvice，通过 order 属性明确优先级，比如 @Order(Ordered.HIGHEST_PRECEDENCE)
• 确认没同时启用 Spring Boot 的默认错误页（server.error.whitelabel.enabled=false），否则会拦截掉你的响应体

捕获Exception还是RuntimeException？按业务语义分层处理

统一异常处理不是“兜底所有 throw”，而是区分「可预期的业务异常」和「不可控的系统异常」。混在一起会导致日志模糊、前端无法精准提示。

• BusinessException（继承 RuntimeException）：用于参数校验失败、余额不足等业务规则拒绝，应返回 HTTP 200 + 自定义 code/message
• IllegalArgumentException、NullPointerException 等：属于编程缺陷，建议转为 500 并记录堆栈，但不要暴露给前端
• 数据库异常如 DataAccessException 建议包装成 SystemException，避免泄露 JPA/Hibernate 细节

@ExceptionHandler参数类型写错，406 Not Acceptable 就来了

Spring MVC 根据方法签名匹配异常类型，但容易忽略泛型擦除和继承链。比如写了 @ExceptionHandler 却捕获不到子类，或者返回值没配好 HttpMessageConverter。

• 参数必须是具体异常类，不能是泛型接口（如 ResponseEntity 不行）
• 返回值推荐用 ResponseEntity，别直接 return Result —— 否则状态码只能靠 @ResponseStatus，灵活性差
• 如果前端 Accept 头是 application/json，但你返回了 String 或未注册 Jackson2ObjectMapperBuilder，就会触发 406

全局异常里做日志记录，别漏掉原始请求上下文

只记 e.getMessage() 没用，排查时根本不知道是哪个用户、哪个接口、什么参数出的问题。

• 用 RequestContextHolder 拿当前请求，提取 request.getRequestURL()、request.getQueryString()、request.getMethod()
• 敏感字段如密码、token 要脱敏，别直接 JSON.toJSONString(requestParams)
• 异步线程中 RequestContextHolder 默认不可用，需提前把必要信息存入 MDC 或传参

真正难的不是写一个 @ControllerAdvice，而是让每种异常都落到它该去的地方，而不是靠 try-catch 到处补洞。路径、状态码、日志粒度、前端友好性——少一个，线上查问题就多绕两圈。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Java项目统一异常处理设计技巧》文章吧，也可关注golang学习网公众号了解相关技术文章。