Java异常处理设计思路全解析

本文深入解析了Spring Boot项目中Java统一异常处理的核心设计思路，强调@ControllerAdvice作为处理Controller层业务与系统异常的主流方案，明确区分其与Filter的适用边界；主张业务异常继承RuntimeException以保持流程简洁，系统异常继承Exception并显式转换，所有自定义异常须内置不可变errorCode字段且避免污染getMessage()；同时厘清ResponseBodyAdvice仅负责成功响应包装、@ControllerAdvice专司异常响应格式化的职责分工，并给出日志记录（如MDC注入traceId、精准提取异常关键信息、过滤敏感数据）和异常分类边界的实战建议，直击统一异常体系落地中最易被忽视的设计难点与陷阱。

统一异常处理该用@ControllerAdvice还是Filter

Spring Boot项目里，@ControllerAdvice 是拦截 Controller 层异常的主流选择，它天然适配 Spring MVC 的异常传播链，能捕获 @ExceptionHandler 显式声明的异常类型，也能配合 @ResponseStatus 返回对应 HTTP 状态码。而 Filter 在 DispatcherServlet 前就介入，拿不到 Spring 的上下文和返回值封装能力，强行在 Filter 里做全局异常格式化会导致重复响应、状态码错乱，甚至 HttpMessageNotWritableException。

真正需要 Filter 的场景只有一种：非 Spring MVC 流量（比如直接访问静态资源、Actuator 端点出错）或必须在请求头解析前就拦截的底层异常（如非法字符导致的 IllegalStateException）。日常业务异常统一走 @ControllerAdvice 就够了。

自定义异常类要不要继承RuntimeException

要，但得按语义分层。业务异常（如参数校验失败、余额不足）应继承 RuntimeException，避免强制 try-catch 干扰主流程；系统异常（如数据库连接中断、Redis 超时）建议继承 Exception，并在调用处显式捕获后转为统一业务异常返回，防止底层错误暴露给前端。

关键点：

• 所有自定义异常必须带 errorCode 字段（String 或 int），用于前端分流或日志追踪
• 不要重写 getMessage() 去拼接错误码——前端不需要看到“ERR_001: 用户不存在”，只要 “用户不存在”
• 构造函数里把 errorCode 存为 final 字段，避免子类篡改

ResponseBodyAdvice 与 @ControllerAdvice 怎么分工

@ControllerAdvice 负责“出错怎么报”，ResponseBodyAdvice 负责“没出错怎么包”。后者常被误用来做统一成功响应包装（如 {“code”:0, “data”:xxx}），但它不处理异常路径——异常发生时，ResponseBodyAdvice 根本不会执行。

所以： - 成功响应统一包装用 ResponseBodyAdvice（注意排除异常类型，用 !ClassUtils.isAssignableValue(Exception.class, body) 判断） - 异常响应统一格式用 @ControllerAdvice + @ExceptionHandler - 两者共用同一套响应结构体（如 Result），避免前后端对“成功/失败”结构理解错位

日志记录和敏感信息过滤怎么做

在 @ExceptionHandler 方法里打日志，别在自定义异常的构造器里打——异常可能被吞掉（比如被更上层的 @ExceptionHandler 拦截），导致日志缺失。

实操要点：

• 记录 exception.getClass().getName() 和 exception.getMessage()，但绝不打印 exception.printStackTrace() 到业务日志（堆栈太长，干扰排查）
• 对 SQLException、HttpClientErrorException 这类带原始请求/响应的异常，提取关键字段（如 SQL 状态码、HTTP 状态码），过滤掉敏感 header（Authorization、Cookie）
• 使用 MDC（Mapped Diagnostic Context）注入 traceId，确保异常日志能和正常请求日志串联

统一异常方案最难的部分不是代码怎么写，而是异常分类边界的定义——比如“库存扣减失败”该算业务异常还是系统异常？这直接影响重试策略、告警级别和前端提示方式。边界模糊时，宁可多建一个异常子类，也不要靠 if-else 分支硬扛。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。