一段段带着异常堆栈的报错信息七零八落地散落在每个Controller里每个方法都塞满了try-catch返回给前端的错误结构五花八门有时是{“msg”:“失败”}有时是{“message”:“系统错误”}甚至还有直接把Exception的toString丢出去的。这绝不是少数SpringBoot项目的真实写照。统一异常处理不是为了少写几行代码而是为了把“出错”这件事变得可预测、可控制、可解释。异常处理不是后端开发的收尾工作而是接口契约的第一道防线。别再用try-catch包裹一切很多开发者习惯在业务方法里加一层try-catch捕获后返回一个Result对象试图让调用方“感知”错误。这种做法最大的问题是让业务代码和错误处理逻辑纠缠在一起。你会在一个查询订单的方法里看到catch (NullPointerException e) { return Result.error(500, 订单不存在) }这种荒谬的代码——空指针被当成了业务分支。把异常捕获在业务层等于把错误处理的责任打散到了每一处业务逻辑里最终无人能说清楚系统到底有哪些异常边界。正确的做法是业务代码只管抛出异常无论是业务异常如订单不存在、库存不足还是系统异常如数据库连接失败、文件读写错误都让它们向上传播。统一异常处理的第一原则就是“让异常飞一会儿”直到它们抵达全局异常处理器。这样Controller里的方法可以保持干净只关心正常流程错误分支全部交给一个集中地。看到这里你可能会担心难道业务代码里连判断都不做了当然要做判断但判断后的动作是throw new OrderNotFoundException(orderId)而不是return Result.error()。前者保留了异常的类型、上下文和堆栈后者则把错误降级成了一个普通返回值丢失了一切诊断价值。让异常处理器成为唯一的出口SpringBoot提供了RestControllerAdvice和ExceptionHandler的组合这正是统一异常处理的正统机制。一个全局异常处理器可以捕获所有Controller层抛出的异常并根据异常类型返回统一的响应体。写一个全局异常处理器并不难难的是让它成为系统里唯一处理异常的出口。这意味着你要克制住到处添加局部try-catch的冲动也要避免在Service层捕获后吞掉异常或重新包装成模糊的运行时异常。一个清晰的做法是定义一个GlobalExceptionHandler类内部针对不同异常类型编写处理方法。对业务异常返回对应的错误码和提示信息对参数校验异常返回字段级别的错误详情对未知异常返回兜底的“系统繁忙”提示并记录完整日志。每个异常处理方法只做三件事提取上下文、记录日志、构造标准响应体。不要在这个类里写业务逻辑也不要让它依赖具体的Controller或者Service。它就像一个路由器输入是异常对象输出是HTTP响应。它的存在让其他人再也无需关心“异常应该怎么返回”这个问题。业务异常与系统异常必须分家如果你的项目里只有一种Exception类所有错误都用它来表示那么统一异常处理很快就会演化成一场灾难。因为调用方无法区分“这个错误是可预期的业务规则冲突”还是“系统出了不可恢复的故障”。业务异常和系统异常的边界就是产品与技术的边界。建议至少设计两类异常BizException业务异常和SystemException系统异常两者都继承自一个自定义的BaseException。业务异常里携带错误码、错误消息、可能还有导致错误的业务参数。系统异常则通常由底层技术框架抛出比如数据库异常、Redis连接异常、第三方接口超时等。对业务异常响应码通常是200但业务码为非零对系统异常HTTP状态码应如实反映错误性质如500。这种区分让你在前端拿到响应后可以立刻判断是弹提示框还是跳错误页。更进一步系统异常应该包装成统一的自定义异常后抛出而不是裸抛NullPointerException或SQLException。“裸抛”系统底层异常等于把你的数据库表结构或缓存策略泄露给了前端调用者。虽然最终返回给用户的消息是统一的但异常链上的堆栈信息可能包含敏感细节。全局处理器要负责把这些底层异常转换为SystemException并输出到服务端日志而前端只能看到“系统繁忙”。错误码是契约不是字符串很多项目用code字段表示错误但随便定义几个数字比如1代表成功-1代表失败。这种错误码体系既无法表达错误的具体场景也不具备扩展性。错误码应当是一份精心维护的契约文档而不是随手写的魔数。推荐用“模块编号 错误场景编号”的格式例如1101表示“订单模块-订单不存在”2203表示“库存模块-库存不足”。每个错误码对应一个标准的message和可能的补救动作提示。错误码的管理要集中在一个常量类或枚举类中并且和全局异常处理器联动。比如BizException构造时传入ErrorCodeOrderEnum.ORDER_NOT_FOUND处理器再从枚举中提取message返回。不要在异常抛出位置写死message字符串否则一旦产品要求修改提示语你就要chase所有出现该字符串的地方。当你把错误码作为唯一的契约前端就能根据错误码做精准的交互逻辑而不是用正则匹配message里的关键词。同时错误码必须覆盖所有可能的异常分支。有些异常比如参数校验失败Spring默认返回MethodArgumentNotValidException其结构包含fields、rejectedValue等。你应当用统一的错误码如PARAM_ERROR包装它并把字段名和校验信息放进data字段而不是直接把异常内部的DefaultMessage丢给前端。参数校验异常是接口开发中最常见、最容易被忽视的异常不加处理就会露出Spring的默认响应结构。全局处理器里要专门为MethodArgumentNotValidException、BindException、ConstraintViolationException编写处理方法把这些异常转换成统一格式。参数校验异常别让它裸奔当你在Controller里写Valid RequestBody UserDTO userDTO时一旦参数校验失败Spring会抛出MethodArgumentNotValidException。如果不做任何处理Spring的默认错误响应是400状态返回一个比较啰嗦的JSON。很多项目在开发初期不管这些前端拿到什么就是什么但到了联调阶段前端会很痛苦。参数校验异常的处理是衡量一个项目异常处理规范程度的试金石。建议在全局处理器中捕获MethodArgumentNotValidException遍历bindingResult.getFieldErrors()提取每个字段的field和defaultMessage组装成一个ListFieldErrorVO放进统一响应体的data里。这样前端可以精确地告诉用户“邮箱格式不正确”“密码长度不能少于6位”。如果你用的是Validated配合DTO上的NotNull等注解同样要处理ConstraintViolationException它的异常结构不同于前者不要漏掉。这还引出一个关键点统一异常处理不是只处理你自己抛出的异常还要处理框架抛出的、Spring Security抛出的、甚至JDK发起的异常。每一个出口都要堵上。当异常发生在过滤器里怎么办RestControllerAdvice只能捕获进入DispatcherServlet后的异常也就是Controller层及其调用链上的异常。但如果异常发生在Filter中比如自定义的认证过滤器里抛出了AuthenticationException或者OncePerRequestFilter里读取请求体时发生了IOException全局异常处理器是捕获不到的。这是一个常见的陷阱你以为统一异常处理已经覆盖了所有却漏了过滤器这个最前置的关卡。解决方案有两种。第一种在Filter里自己try-catch然后手动写入响应。但这样你没法把错误码、标准响应体统一封装除非你在Filter里硬编码JSON序列化这很丑陋。第二种把拦截器链的异常通过HandlerExceptionResolver转发给全局处理器。具体做法是注入HandlerExceptionResolver在Filter的catch块中调用resolver.resolveException(request, response, handler, exception)。这样异常就能复用ExceptionHandler中的逻辑响应体格式保持一致。过滤器的异常处理不是例外而是全局异常处理的一部分。此外还有DispatcherServlet中的processDispatchResult阶段可能出现的异常比如视图解析失败或者响应已经被提交后抛出的异常这些情况很难再返回自定义JSON。一个务实的做法是在网关层或反向代理层兜底统一对非200响应做结构转换。对于大多数微服务场景SpringBoot只处理自己能处理的那一段真正对外的统一要交给网关。异步任务里的异常不会自己消失Async方法抛出的异常默认情况下不会自动进入RestControllerAdvice因为全局异常处理器监听的是请求线程的异常传播路径而异步线程有自己的调用栈。异步任务里的异常如果没有处理会直接跑到线程池的Thread.UncaughtExceptionHandler甚至被静默吞掉。这是很多系统出现“偶发数据不一致”却查不到日志的根源。解决异步异常有几个层次。如果异步任务在线程池中执行你可以为线程池设置UncaughtExceptionHandler在那里记录日志和上报监控。更好的方式是在异步任务中显式地捕获异常并通过一个回调接口或Future的get()方法获取异常。如果你用了Async那么调用方应该具备拿到异步结果或异常的能力而不是“发出去就不管了”。对于消息消费场景比如RocketMQ或Kafka的consumer建议单独建立一套“消息异常处理机制”把反序列化失败、业务处理失败的消息发送到死信队列而不是尝试在全局异常处理器中统一处理。异步世界里的异常注定和同步请求的异常是两条路但都要有明确的归属。对于使用CompletableFuture组合调用的场景注意异常传播的特殊性。whenComplete、exceptionally是捕获异步异常的常规手段但如果你只是join()异常会被包装为CompletionException。全局处理器不会自动解开这层包装你需要手动处理。异步异常处理的核心思想是不要假设异常会自动被谁接住所有离线任务都要有兜底的异常捕获和记录。日志要打在正确的地方统一异常处理不只是“返回一个好看的JSON”它还承担着记录日志的功能。但这个日志不是简单的log.error(e.getMessage(), e)。错误日志要包含请求的方法、URL、参数、用户ID如果有、异常类名、错误码、对应的堆栈。只有把这些上下文信息都记录下来事后排查问题才不至于去猜是哪条请求触发的。建议在全局异常处理器的“未知异常”处理分支中用log.error记录完整堆栈在业务异常处理分支中用log.warn记录因为业务异常属于可预期情况未必需要报警。区分日志级别是异常处理规范化的体现。同时要避免在业务代码中反复打印同样的日志。比如在Service里捕获异常打印了一次又在Controller里打印了一次到了全局处理器又打一次最终日志文件膨胀且排查困难。建议的日志策略是底层异常必须打印在“第一次捕获到该异常的地方”全局处理器只记录未被捕获的异常和异常处理结果。这样同一个异常的日志不会重复且总有记录。某些情况下全局处理器可能会在返回前将异常信息脱敏。例如异常消息中包含手机号或身份证号必须在写入日志前进行脱敏处理。日志不是给用户看的但用户可能通过下载日志文件看到泄露数据。所以全局异常处理器在构造日志时要主动过滤掉敏感字段这比事后审计要便宜得多。把异常处理变成可观测的一部分统一异常处理的最终目标是让异常变成系统可观测性的一部分而不是埋藏在雪花般的日志文件里。每个被处理器接住的异常都应该可以关联到一个全局唯一的traceId。如果在网关层或Filter里引入了traceId生成器如MDC那么异常日志就可以与调用链日志串联起来。异常响应体中带上traceId是给用户最好的“凭证”。当用户反馈“订单支付失败”前端把traceId提交过来后端就能直接定位到那几行日志。更进一步建议对异常类型和错误码做监控统计。比如每分钟记录“订单模块-库存不足”触发了多少次如果超过阈值就发出告警。错误码的分布就是系统健康度的晴雨表。没有统一的异常处理你很难做到这种统计因为错误散落在各处格式都不一致。有了全局异常处理器你可以在其中埋点把异常类型、错误码、请求路径、耗时等信息发送到Prometheus或自定义计数器里。异常处理不该是一个被动的“兜底”而应该是一个主动的“感知层”。统一异常处理背后体现的是对系统边界感的尊重。你不可能让异常不出现但你可以让异常出现时系统依然保持优雅。最大的风险不是代码有bug而是bug发生时你连发生了什么都不知道。别再到处写try-catch了让全局异常处理器成为你的遮阳伞但不要指望它能挡住所有地方的雨。过滤器、异步任务、消息队列每一个异常逃逸点都值得你重新审视一遍——这就是统一异常处理远不止一个注解那么简单。