异常处理这件事从来不是把try-catch塞满每个方法那么简单。很多SpringBoot项目跑着跑着前端突然甩来一句“接口返回了一个奇怪的错误格式”你一看可能是NPE的堆栈直接怼到了JSON里也可能是某个校验失败抛了个IllegalArgumentException返回体却是200 OK加一段英文提示。这种混乱本质上是异常处理缺乏统一的战略设计。如果你愿意花几分钟把异常当成一种业务流程来看待而不是偶然的故障就会发现优雅处理异常与统一返回格式其实是一套可以量化的工程实践。这篇文章不打算讲太基础的ControllerAdvice用法而是想聊聊那些真正影响项目维护体验的设计决策。返回格式先定义清楚再说不管是成功还是失败前端只希望拿到一个可预测的结构。很多团队喜欢定义code、message、data三件套这没错但致命的细节在于code的语义必须全局唯一。有人用HTTP状态码直接当业务码结果业务上“未找到”和“没有权限”都映射成404前端只能靠猜。更糟糕的是有些人把code设计成String类型里面塞了“SUCCESS”“ERROR”“USER_NOT_FOUND”看起来可读但一旦业务状态超过五十种字符串比较的成本和拼写错误会让所有常量类变成垃圾场。我的建议是统一返回对象采用泛型ResultT字段至少包含code、message、data并且让所有接口都返回这个对象。这里有个反直觉的陷阱很多人喜欢把Result直接放在Controller方法的返回值里这倒不是不行但会让Service层也耦合这个类。更好的做法是Controller层负责包装Service层只返回业务数据或抛出异常。这样你的核心业务代码不会到处是Result.success()。另一个细节是code应该是int类型并且用静态常量或枚举集中管理。比如SUCCESS0BIZ_ERROR1001PARAM_ERROR1002。不要用正负号区分成功失败因为0代表成功已经是行业默契非0代表异常。你还需要一个全局的message兜底比如“系统繁忙请稍后重试”而不是把异常消息直接抛给前端——除非是API文档明确约定的字段校验提示。业务异常必须有一套自己的语言Java里的RuntimeException体系虽然庞大但你绝不能指望NullPointerException或IndexOutOfBoundsException能表达任何业务语义。优雅处理异常的第一步是定义你自己的业务异常基类。这个基类至少要包含code和message两个属性构造函数允许传入枚举或常量。比如public class BizException extends RuntimeException { private final int code; public BizException(int code, String message) { super(message); this.code code; } }有了这个基类你可以在任何地方抛throw new BizException(ErrorCode.ORDER_NOT_FOUND, 订单不存在)。但真正的高级用法是让业务异常支持参数化消息。比如用户查询订单时传入订单号你可以用String.format预先填充“订单[id123456]不存在”这样前端拿到消息后不需要自己拼接也避免了消息模板散落在各处。更值得深思的是不要为每个业务场景单独创建异常类。见过有人建了UserNotFoundException、OrderNotFoundException、ProductNotFoundException这些类除了类名不同逻辑一模一样。你真正需要的是异常里的code和message不同而不是类的多态。所以一个BizException配合枚举或常量表完全够用。当然如果你非要为“系统级异常”和“业务级异常”做区分那顶多再加一个SystemException表示不可预料的运行时故障。全局异常处理器别只写一个ExceptionHandler很多教程会让你在ControllerAdvice里写一个方法捕捉Exception然后返回Result.failure()。这看起来简单但粗暴地捕获所有异常会掩盖很多关键问题。比如数据库连接断开抛出的DataAccessResourceFailureException你能把它当作普通业务失败返回给前端吗显然不行这种异常应该记录大量上下文并返回一个通用的“系统内部错误”。所以建议至少分三个层次处理异常。第一层捕获你自定义的BizException轻松自然地从异常对象里取出code和message这是既定流程。第二层捕获常见的框架异常比如MethodArgumentNotValidException、ConstraintViolationException、HttpMessageNotReadableException。这些异常要么是参数校验失败要么是JSON解析错误你需要把具体字段名和校验规则转换成友好的提示例如“用户名为必填项”而不是“JSON parse error: Unexpected token”。第三层捕获最顶层的Exception但这条兜底路径必须返回一个固定且模糊的提示并在日志中打印完整的堆栈。这里有个很容易被忽略的细节异常处理器的顺序很重要。SpringBoot会优先匹配更具体的异常类型但要是你自作聪明地写了两个ExceptionHandler(Exception.class)那就会产生冲突。另外你可以在ControllerAdvice上指定basePackages这样不同模块可以有不同的异常处理策略。但大部分中小项目不需要拆分得那么细一个全局处理器足矣。参数校验异常值得你单独写一个分支统一返回格式最大的坑往往出现在参数校验环节。你用了Valid注解用了NotNull校验失败后会抛出MethodArgumentNotValidException。默认的响应体充满了FieldError的列表每个元素还带着英文的field和defaultMessage。这不是我们想要的统一格式。你得在全局处理器里专门写一个方法把这个异常转换成标准的Result。关键点在于你既要保留字段名又要把消息尽量改成中文或符合用户习惯的文案。可以遍历BindingResult的getFieldErrors()取出getField()和getDefaultMessage()。但默认消息通常来自注解的message属性如果你没有配置就会是“must not be blank”这种英文。所以建议所有校验注解都写上message属性例如NotNull(message用户ID不能为空)。这样异常处理逻辑就非常简洁把FieldError里的field和defaultMessage拼装成“用户ID不能为空”即可。还有一类参数校验是方法级别的Validated配合RequestParam时异常类型是ConstraintViolationException。它的处理略有不同因为异常里持有的是SetConstraintViolation?你要遍历它获取getPropertyPath()和getMessage()。另外HttpMessageNotReadableException通常表示请求体不是合法JSON你可以返回“请求体格式错误”。这三种异常分别写好处理逻辑前端拿到的错误提示才称得上“优雅”。统一返回格式要处理好“正常”和“异常”的边界有人喜欢在所有Controller方法的返回值上都写ResultUser这没错但也带来了一个麻烦如果你用Spring Data REST或某些自动生成的接口它们可能不经过你的Result包装。而且在异步调用或Feign调用时如果你把Result作为Feign的返回类型那么每个调用方都要检查code是不是0这非常繁琐。优雅的做法是只在对外API层面使用Result内部服务间调用可以抛异常或直接返回裸数据。另外一个边界是文件下载、流式响应这类接口不适合返回Result。你不可能把PDF或图片的二进制塞进data字段里让前端再解析。所以统一返回格式并不要求100%覆盖所有端点接口文档里要明确哪些是二进制流。这一点不说明白前端同事一定会来问你“为什么下载接口返回的是JSON”。还要警惕一个场景过滤器或拦截器里抛出的异常不会进入ControllerAdvice。例如在Filter中做Token校验如果直接抛异常全局处理器根本感知不到响应会是容器默认的HTML错误页。对于这种情况你需要自己在Filter里写try-catch然后用response.getWriter()输出一段JSON。或者更优雅的方式使用HandlerInterceptor的afterCompletion处理但Filter的优先级更高所以你必须在异常处理的边界上想清楚过滤器层级的职责。日志记录异常处理不可分割的一部分统一返回格式只是把异常“包装”了一下但日志才是真正让问题定位成为可能的证据。很多项目在ExceptionHandler里只调用log.error(e.getMessage())这远远不够。你需要记录至少三类信息异常发生的类和方法、请求URL和参数、唯一请求ID。如果可能将请求体也打印出来但要注意敏感字段脱敏比如密码、手机号、身份证号。你可以在全局异常处理器里注入HttpServletRequest然后从MDC中取出预先放好的traceId这样一条日志就能串联起完整的调用链。比较推荐的做法是在网关或入口Filter中生成traceId放入MDC然后在所有日志模板里输出%X{traceId}。当异常发生时异常处理器的日志会自动携带traceId前端也能在错误响应里拿到这个ID来反馈给运维。让异常信息可追踪比让异常信息可读更重要。异常码还能怎么用聊聊幂等和重试统一返回格式里的code字段不仅仅是给用户看的。你可以约定某些特定的异常码告诉调用方“这个请求应该重试”。比如一个订单支付接口后端返回“订单已锁定请重试”code2001。另一个接口返回“库存不足”code2002这种错误重试多少次都没用。将这些信息编码进code配合ErrorMessage里的提示就能实现半自动化的重试策略。但要注意永远不要用message来判断业务状态因为前端切了国际化message可能变成英文或日文。code才是唯一的程序可读标识。所以你的枚举或常量类里不仅要定义code值还要定义对应的默认message模板甚至可以带几个占位符。这样在抛出异常时你只需要提供参数数组由异常构造器完成格式化。开箱即用的异常处理还是自己造轮子很多框架号称提供“统一异常处理”和“统一返回格式”的starter比如Sa-Token或微服务框架自带的全局异常。但当你真正接进去会发现它们要么过度设计要么和你的业务枚举冲突。我的建议是不要为了简洁引入一个重型抽象。最优雅的往往是极简的一个Result类、一个BizException类、一个GlobalExceptionHandler类加上一个异常码常量类足够了。如果你团队喜欢用枚举也可以把异常码定义成枚举但一定要避免把几百个错误码放在一个巨大的类里。按模块拆分异常码常量类比如OrderErrorCode、UserErrorCode每个类里放十来个静态常量维护成本低也不会互相污染。真正的优雅是让你不需要思考“到底该返回什么”。当每个开发者都遵循同一个套路业务逻辑出错就抛BizException参数问题就用框架的校验注解然后由全局处理器统一兜底。你的代码里几乎看不到try-catch更看不到ResponseEntity的奇怪用法。这种一致性带来的信心无法量化但会让你的代码评审变得极度舒适。从“能用”到“好使”的最后一公里光有统一返回格式和异常处理还不够你还需要在API文档中明确说明这些格式。比如Swagger注解ApiResponse可以描述每个接口可能返回的错误码。更进一步你可以在Result里增加一个traceId字段让前端报错时能直接粘贴traceId给后端查日志。一旦这个字段被双方约定并长期使用你的线上问题处理效率会提升一个数量级。最后检查几个容易被忽略的细节异步方法里的异常不会自动传入ControllerAdvice。如果你在Async方法里抛了异常它会被线程池吞掉或记录到独立日志所以异步任务里必须自己try-catch并处理。还有测试一定要为全局异常处理器写单元测试尤其是校验异常和未知异常。你可以用MockMvc发一个非法请求断言返回体里的code是不是你预期的值。这一层测不透将来改错一个注解影响面会非常大。回到最初的问题优雅地处理异常与统一返回格式其实是在追求一种“可预见的混乱”。业务会错参数会错系统也会错但只有错误的表现形式是统一、可控、可追踪的你的项目才真正称得上工程化。当你把异常当作二等公民它就会在凌晨三点给你打电话当你把异常当作头等公民它就会安静地躺在日志文件里甚至帮你自动定位到出错的代码行。选择权在你手里。