做后端这几年我在错误处理上摔过的跟头比在数据库里遇到的死锁还多。上个月线上出了一次事故一个日请求量上百万的查询接口突然开始大面积报错监控面板上全是NullPointerException。翻代码发现这个接口的历史版本返回User对象查不到人就返回null后来同事为了消灭空指针把null改成了抛出UserNotFoundException但调用方有十几个只改了其中两个其余的全部炸了。复盘时大家嘴里蹦出一个词——错误模型。然后我们才意识到这个项目里压根没有一个统一的错误模型。错误模型听着很高深其实就是你对数据、异常、正常返回这三类状态定下的规则什么情况下返回数据什么情况下抛异常什么情况下只返回一个状态码必须白纸黑字说清楚。这篇文章我会先讲事故和原理再分享我最终落地的统一方案包括 Result 包装、错误码枚举、异常边界以及校验失败、第三方调用、并发超时这些灰色地带的处理。适合正在做接口设计、重构老系统、或者被各种空指针和业务异常搞到崩溃的同学。1. 为什么一条查询语句能拖垮整条链路错误模型混乱的代价1.1 真实事故boolean返回值、null和异常混用的现场先还原一下现场。老项目里有个UserService.getUser(String id)最初版本是这样写的// 版本1查无此人返回 null public User getUser(String id) { if (id null) { return null; } return userRepository.findById(id).orElse(null); }调用方有两种用法。少部分调用方会判空User user userService.getUser(123); if (user ! null) { orderService.createOrder(user.getId(), ...); }但更多的调用方是直接拿到对象就往下传User user userService.getUser(123); String email user.getEmail(); // 这里 NPE后来有人看不下去了把getUser改成查不到就抛异常public User getUser(String id) { return userRepository.findById(id) .orElseThrow(() - new UserNotFoundException(id)); }问题来了异常抛出来后调用方如果没有 try-catch整个链路直接中断。那十几个调用方里只有两个跟着改了捕获逻辑其余的全部在“查无此人”这种业务分支上直接失败。为什么大家没发现因为这个接口的签名没有任何“此处可能失败”的强提示null也好、异常也好都要跑到运行时才暴露。这暴露的是典型的错误模型混乱同一个接口不同版本下“用户不存在”有时是null有时是异常有时可能又是false。调用方无法用一套固定的模式消费这个接口数据、异常、正常返回被随意替换谁也不欠谁一个明确的约定。1.2 错误模型的三要素数据、异常、正常返回之间的关系从本质上看这三者的关系很像快递公司。数据是包裹本身业务处理完成后的产物比如用户对象、订单列表、商品库存。正常返回是快递员完成配送后按下门铃把包裹交给你你作为接收方决定接下来怎么处理。异常是途中遇到车祸、包裹丢失快递公司直接给你发事故通知并且后面的流程全部改变不管你想不想听这个通知都会以最高优先级打断你。在程序里数据必须依附于某条返回路径。正常返回路径上可以携带数据异常返回路径上应该携带错误原因。但很多代码把“返回 null 表示失败”“返回 -1 表示失败”“抛异常表示失败”混在一起本质上就是没有区分“这条路是不是走得通”和“这条路到了之后给我带来了什么货物”。所以一个清晰的错误模型至少要回答三个问题哪些情况属于“业务上正常但结果不成功”比如余额不足、用户不存在、订单已关闭。哪些情况属于“系统出了意外”比如网络断开、数据库抖动、空指针。正常情况下的数据如何返回业务失败时错误信息如何返回这三个问题定死了整个团队才有统一的语言。这也是我从那次事故之后重建错误模型的起点。2. 异常和正常返回表面看是语法问题实际是控制权交接问题2.1 异常机制的底层原理栈展开、调用方强制介入很多人以为throw new XxxException()和return new XxxResult()只是语法上不一样其实它们在控制流上完全是两种东西。异常被抛出后当前函数会立即中断后续代码不再执行。运行时会在当前线程的调用栈上从抛出点往上找逐个看每个调用方的catch块是否能匹配这个异常类型找到就执行对应的处理器同时让沿途所有活跃的finally块执行。这个动作叫栈展开stack unwinding。这里有一个非常容易被新手忽略的语义一旦抛了异常当前函数“正常流程已完成”这个前提就没了。调用方能不能处理、会不会被全局兜底处理完全取决于它有没有在恰当的位置加try-catch。像数组越界异常、非法参数异常都属于运行时异常编译器不会强制你捕获。如果写代码时没有前置校验等到运行期爆出来错误模型再漂亮也拦不住因为错误模型只管“错误怎么表达”不管“错误怎么避免”。不过异常并不是一无是处。它最大的优点是“不处理就会一路打断到全局兜底”适合表达真正的系统级事故。比如数据库连接池耗尽、内存溢出这些如果不立即中断后续的操作只会产生更多连带故障。这里也顺带说一句编译期异常checked exception是 Java 特有的强制手段它逼着调用方处理可恢复问题但如果你把参数校验这类高频分支也用受检异常表达接口调用会变得非常啰嗦且难以维护。2.2 正常返回的语义把决策权留给调用方正常返回就温和得多。函数执行完后把控制权交回给调用方调用方用一个if或者switch就能决定接下来做什么。这种语义特别适合业务分支订单状态不对、用户余额不够、某个字段缺失这些都是业务流程中的“分岔路口”不是“山体滑坡”。我常举一个例子你去餐厅点菜服务员说“这道菜今天没有了”。这是一个正常返回——你听完后可以换一道菜而不是被强制拖出餐厅。如果服务员突然开始尖叫并拉响了火警那才是异常。很多后端接口的问题在于把“这道菜没有了”也当成火警去拉结果消费者端一碰到余额不足就直接 500连个友好提示都给不出来。正常返回的另一个好处是性能。异常需要构建异常对象、填充调用栈、逐层匹配catch成本比普通return大很多。如果一个失败分支会被高频触发比如用户输入了非法参数那么用返回值表达会比用异常划算得多。2.3 数据在错误模型中的位置业务结果与状态不要混在一起那么数据呢它既不是异常也不是状态它应该是“状态下面的附属信息”。成功时数据是Result.ok(user)失败时数据位是null或空附上错误码和信息。糟糕的写法是用数据本身表示状态比如null表示失败、空数组表示没权限、-1表示余额不足。这种设计的坑在于一旦业务上真的需要返回一个null数据或[]空数据约定就会冲突。我见过一个接口data字段在正常查询时返回 JSON 数组没权限时返回code200但data是空数组message写“无权限”。调用方只能通过data是否为空来判断有没有权限后来权限边界变严格真的允许返回空数据时前后端就打架了。所以记住一条铁律状态走状态字段数据走数据字段永远别让数据本身兼职状态。3. 我自己落地的统一错误模型Result包装 错误码 异常边界3.1 为什么选 Result 包装而不是纯错误码当时团队里有人提议直接用错误码像 C 语言一样返回int成功了返回0失败了返回-1。我坚决反对。原因很简单错误码是魔法数字没人知道-2048是什么意思调用方还要去全局文档里找而且编译器帮不了你你可以轻易地把-1当成另一个业务数据继续传下去。我一直偏爱 Java 社区里常见的泛型ResultT包装它本质上就是Optional的增强版——不仅知道有没有值还知道没值时为什么没值。类结构可以很简单public final class ResultT { private final int code; private final String message; private final T data; private final boolean retryable; private Result(int code, String message, T data, boolean retryable) { this.code code; this.message message; this.data data; this.retryable retryable; } public static T ResultT ok(T data) { return new Result(0, success, data, false); } public static T ResultT fail(BizError error) { return new Result(error.getCode(), error.getMessage(), null, error.isRetryable()); } public boolean isSuccess() { return code 0; } public T getData() { if (!isSuccess()) { throw new IllegalStateException(result is not success); } return data; } public int getCode() { return code; } public String getMessage() { return message; } public boolean isRetryable() { return retryable; } }Result的好处是类型安全ResultUser明确告诉你成功时返回的是User成功和失败是同一个对象调用方不用猜可以扩展retryable这类元信息。代价是调用方多了一行.isSuccess()判断但这比埋在异常里好太多。在 Go 语言里常见的(value, error)双返回值其实就是这种模型的元组版。在 Kotlin/Swift 里也有Result或Either类型。可以说现代语言都在朝这个方向靠拢。3.2 错误码枚举怎么设计才不会被业务带偏有了Result壳下一步是设计错误码。我把错误码分为四大段错误码段含义示例0成功code0, messagesuccess1xxx系统错误1001 数据库不可用, 1002 缓存超时, 1003 消息队列异常2xxx参数/校验错误2001 缺少参数, 2002 参数格式错误3xxx业务规则错误3001 用户不存在, 3002 订单状态不允许4xxx外部依赖错误4001 第三方超时, 4002 第三方限流分段的好处是看错误码第一位数就知道该找谁、该不该重试。2xxx 是调用方写错重试也没用1xxx 是运维要盯3xxx 是产品规则变化4xxx 要查第三方。错误码必须用枚举收敛禁止各业务线自己发明错误码。我见过某项目里错误码有 173 个其中-1用了 21 种意思。后来我把它们清理成BizError枚举每个枚举带上 code、英文标识、中文消息、是否可重试public enum BizError { PARAM_MISSING(2001, param_missing, 缺少必要参数, false), PARAM_FORMAT_INVALID(2002, param_format_invalid, 参数格式错误, false), USER_NOT_FOUND(3001, user_not_found, 用户不存在, false), ORDER_STATUS_INVALID(3002, order_status_invalid, 订单状态不允许该操作, false), THIRD_PARTY_TIMEOUT(4001, third_party_timeout, 第三方服务超时, true), THIRD_PARTY_RATE_LIMIT(4002, third_party_rate_limit, 第三方限流, true); }这里有个小技巧retryable字段非常重要。对于 1xxx 和部分 4xxx监控系统看到retryabletrue可以自动重试或告警对于 2xxx、3xxx重试只会加剧问题。很多团队的错误模型一开始没考虑这个导致报警系统一看到错误码就乱重试把下游打挂了。3.3 异常只保留给“系统意外”业务校验全部走正常返回那异常在错误模型里还有位置吗有但位置很窄。我现在的约定是业务校验失败、资源不存在、状态非法全部走Result.fail(...)正常返回。不应该出现的编程错误、环境错误、基础设施故障抛异常由全局兜底捕获并转成 1xxx 错误码。在应用内部可以抛运行时异常但绝对不能把裸异常直接透传给调用方或前端所有异常在出口处必须经过统一转换。这条约定有反直觉之处UserNotFoundException该抛吗我认为在对外 API 中不该抛它只是一个分支条件但在领域层处理详细数据时抛一个UserNotFoundException可以快速终止链路然后被应用层 catch 后转成Result.fail(USER_NOT_FOUND)。也就是说异常可以作为“内部打断机制”但不能作为“外部契约”。为此我在入口处加了一个全局异常处理器比如 Spring 的RestControllerAdvice捕获所有未处理异常转成统一错误码。同时业务方法里除了Result.fail不能随意吞异常这样才能保证错误模型不出现旁路。4. 实战中的三个灰色地带校验失败、第三方调用、并发超时4.1 参数校验失败到底算异常还是正常返回参数校验是所有团队争论最多的灰色地带。以 Java 为例Valid注解的参数校验失败Spring MVC 默认会抛MethodArgumentNotValidException如果不处理返回的是 400 异常结构。很多同学就会写一个ExceptionHandler把这东西转成Result。这么做对外部 HTTP 接口没问题客户端能拿到明确的错误码。但如果你写的不是 HTTP 接口而是内部 RPC 方法我强烈建议把参数校验结果做成Result.fail(PARAM_MISSING)返回。原因很直接RPC 调用方需要在业务代码里根据校验结果做分支而全局异常处理器无法让调用方在调用点上继续执行逻辑。比如调用方可能在PARAM_MISSING时走默认参数重试在PARAM_FORMAT_INVALID时直接提示用户修改。用异常表达校验失败他只能 catch 再判断异常类型绕了一圈又回到返回值。另一个要注意的点编译期异常和校验失败不要混为一谈。Java 的受检异常是为了强制调用方处理“可恢复异常”但业务校验失败本质上是“调用方传入的数据不满足约束”它不属于异常而属于正常返回。如果你非要用受检异常会造成接口签名被异常污染调用方被迫 catch 一堆根本不可能是故障的东西。4.2 第三方调用失败如何区分“服务不可用”和“业务拒绝”调用第三方支付、风控、物流接口时错误模型要分两层看。第一层是技术层连接超时、读取超时、5xx、连接池耗尽这些属于系统异常你不能把它们当作业务返回直接透传。比如第三方网关 502 了你把 502 包装成Result.fail返回给前端前端一看以为用户操作失败其实真实问题是第三方故障。正确做法是这类错误抛异常进入熔断和重试策略全局兜底最终转成THIRD_PARTY_TIMEOUT或THIRD_PARTY_UNAVAILABLE。第二层是业务层第三方返回的 JSON 里带着业务错误码比如“余额不足”“风控拒绝”。这时候它已经不是一个技术故障而是第三方给你的业务裁决。你应该把这个错误码透传到自己的Result.fail中让调用方按业务逻辑处理。实际落地时我给每个第三方调用封装了一个SafeInvoker它统一捕获技术异常处理重试计数并区分TechnicalError和BusinessError保证两者不会混淆。没有这层封装最典型的问题就是下游一超时上游就返回“系统繁忙”用户疯狂重试然后下游彻底被打死。4.3 超时与并发最容易被错误模型撕裂的场景还有个更隐蔽的坑缓存超时。很多同事一看到 Redis 超时就 catch 住然后返回一个默认值比如商品名称返回“默认商品”。这看起来是降级但问题在于 Result 的code0调用方完全不知道这是一个降级数据。如果这个默认值进入后续的订单计算结果会很糟糕。我的建议是如果降级必须让Result中的data仍在但code变成一个特殊的DEGRADED错误码或者给Result加一个degradedtrue标志。调用方看到降级标志后可以决定继续使用还是返回失败。并发冲突也是一样。乐观锁更新失败返回Result.fail(CONCURRENT_CONFLICT, retryabletrue)这属于正常返回因为用户刷新一下重试就好。但如果是数据库连接池等待超时那就是系统异常必须抛出去。这两个场景的灰度区别恰恰是错误模型最难落地的部分。我最后用一个retryable字段统一解决凡是可以靠调用方重试恢复的都标记为retryabletrue凡是重试无用的标记为false。5. 错误模型落地的四大反模式与我的避坑清单5.1 把异常当业务跳转用先说第一个反模式把异常当跳转。有些老代码会这样写try { createOrder(); } catch (UserNotFoundException e) { router.toLogin(); } catch (BalanceNotEnoughException e) { router.toRecharge(); }这看着挺省事实际上每次余额不足都会创建一个异常对象填充完整的调用栈哪怕你根本不打印它。在高频场景下这是纯性能黑洞。更关键的是它把业务流程打碎了阅读代码的人需要同时记住三个 catch 块才能理解一段顺序逻辑而用返回值的话一个switch (result)就能读完。我个人体会异常适合做“跨层中止”比如领域层发现订单已被关闭直接抛一个内部状态异常中止当前事务。但到了应用层应该 catch 住并转为正常返回让控制流恢复成顺序结构。不要用异常去表达“业务分支”。5.2 吞异常后返回成功最隐蔽的数据污染第二个反模式是 catch 住异常后返回Result.ok(null)或者true。我见过不止一起因这种方式导致的数据不一致某个同步库存的定时任务调用库存服务失败后 catch 住返回了成功消息队列认为同步完成直接确认了任务结果库存永远停在旧值。如果确实要降级至少要遵循前面说的把降级状态反映到 Result 的code或degraded字段中。同时降级逻辑必须写在调用方的代码里而不是在异常 catch 里偷偷做。否则调用方以为成功后续链路带着脏数据继续跑这种问题排查起来极其痛苦。5.3 跨层传递裸异常错误信息的“三手转述”第三个反模式是把底层异常原封不动抛出。DAO 层的SQLException、外部系统的ConnectException如果一路 throw 到 Controller前端会看到java.sql.SQLException: Connection refused这不安全也不友好。更重要的是底层异常带有非常具体的内部信息一旦泄露容易暴露表结构、IP、机器名。正确的做法是在每一层做“翻译”DAO 层异常翻译成DATA_ACCESS_ERROR第三方异常翻译成THIRD_PARTY_ERROR业务异常直接是Result.fail。内部日志用统一的log.error(opxxx, err{}, ..., e)保留完整异常链对外返回值只保留可读的错误码和消息。这就像安保和前台的分工访客只需要知道“今天不接待”不需要知道是哪个管子爆了。5.4 缺少全局兜底一切模型的最后防线最后说兜底。错误模型再完整也不可能保证所有人都不漏 catch。所以必须有一个全局兜底机制在所有 HTTP/RPC 入口注册异常过滤器或切面。捕获未被处理的所有Exception转成通用系统错误码。捕获Error如StackOverflowError、OutOfMemoryError记录日志转成友好响应。兜底返回的 message 不要带堆栈千万不能把原始异常直接序列化给客户端。我踩过的坑是有一段时间某个内部服务没有加兜底一次 NPE 直接给调用方返回了堆栈文本调用方解析 JSON 失败反手又抛一个 JSON 解析异常形成连环故障。加上兜底切面之后至少所有出口的响应结构是稳定的后续排查也只需要看错误码和 traceId。最后说一点个人的体会。错误模型不像缓存和消息队列它没有炫酷的架构图但它决定了系统在出问题时人和机器能不能快速达成一致。那次线上事故之后我把团队所有接口的返回值清单重新过了一遍砍掉了十几种表示错误的方式最终统一成 Result 错误码 兜底异常。过程很琐碎但收益非常明显后续排查线上问题的时间至少少了一半。如果你也在重构老系统建议先从错误模型开始这是投入产出比最高的一项改革。
