错误码体系设计指南：从编码规则到微服务落地实践

1. 错误码设计的整体思路拆解1.1 为什么错误码值得单独设计很多团队在项目初期对错误码的态度是“先随便定几个能跑就行”结果到了联调阶段前端拿着一个{code: 500, msg: 系统异常}完全不知道发生了什么客服拿着用户截图也定位不到问题运维翻日志只能靠时间戳大海捞针。错误码看起来是个小东西但它贯穿了整个系统的通信链路客户端、网关、业务服务、中间件、数据库每一层都可能产生错误每一层都需要把错误准确地传递给上层。我经历过一个项目早期错误码只有三个0 表示成功1 表示业务失败2 表示系统异常。上线三个月后光“业务失败”这一个码就对应了四十多种场景前端没法区分到底是用户没登录、余额不足还是商品下架最后被迫在 msg 字段里塞中文描述来做判断。这就是典型的错误码设计债——前期省下来的半小时后期要用几十个小时来还。合理的错误码设计核心目标是三件事第一让调用方能程序化地区分错误类型不需要解析文本第二让排查人员能快速定位错误来源知道是哪个系统、哪个模块出的问题第三让错误本身具备可扩展性新增业务线时不用推翻重来。1.2 错误码和异常、状态码的区别在动手设计之前有必要把几个容易混淆的概念理清楚。HTTP 状态码是传输层/协议层的语义比如 404 表示资源不存在500 表示服务端内部错误它描述的是“这次 HTTP 请求本身的结果”。而业务错误码是应用层的语义描述的是“这次业务操作的结果”。两者是不同层次的东西不能混为一谈。举个例子用户请求查询一个不存在的订单。从 HTTP 层面看请求本身是成功的服务器正常处理并返回了响应所以 HTTP 状态码可以是 200但从业务层面看这个查询是失败的因为订单不存在所以业务错误码应该是一个表示“订单不存在”的码。很多新手会直接把业务错误映射成 HTTP 500这是不对的500 会让网关、监控系统误以为服务出了故障触发不必要的告警。异常则是编程语言层面的机制是代码执行过程中抛出的信号。错误码是异常经过捕获、转换之后对外暴露的标准化结果。三者关系可以这样理解异常是内部实现细节HTTP 状态码是协议约定业务错误码是面向调用方的契约。1.3 设计错误码时要回答的几个核心问题我在设计任何一套错误码体系之前都会先问自己几个问题这几个问题的答案直接决定了最终的结构。谁来消费这个错误码是前端、是第三方开发者、还是内部服务之间调用面向 C 端的错误码要尽量简单面向开发者的可以携带更多信息。错误码需要全局唯一吗如果系统拆成了多个微服务每个服务独立编号那全局唯一就需要靠分段或前缀来保证。错误码是固定枚举还是动态生成固定枚举便于文档化和国际化动态生成灵活但难以维护。错误信息要不要国际化如果有多语言需求错误码就不能直接携带面向用户的文案文案应该由调用方根据码去查表。把这几个问题想清楚后面的结构设计就是水到渠成的事。2. 错误码的结构与编码规则详解2.1 常见的几种编码结构对比错误码的结构没有绝对的标准但业界常见的做法可以归纳为几类各有适用场景。我整理了一个对比表方便你根据自己项目的情况选择。结构类型示例优点缺点适用场景纯数字递增10001, 10002简单直观无层次难定位来源小型单体应用分段数字1xxxx 用户2xxxx 订单能区分模块段位规划需提前做好中型单体/少量服务前缀数字USER_1001可读性强字符串比较略慢面向开发者的 API层级数字1020301信息密度高需要约定解读规则大型微服务集群字母数字混合A1B2C3灵活无规律难记忆特殊业务场景我个人的偏好是分段数字 模块前缀的组合。纯数字便于程序处理和存储分段能快速定位来源前缀在日志和文档里又能提供可读性。比如100101可以解读为10 代表用户中心01 代表登录模块01 代表具体的“密码错误”。2.2 分段编码的位数规划分段编码最关键的是位数规划。位数太少段位不够用位数太多记不住也写不对。我的经验是采用2-2-2 或 3-2-3 的六到八位结构。以六位AABBCC为例AA2位系统或服务编号最多支持 100 个服务00-99BB2位模块编号每个服务下最多 100 个模块CC2位具体错误编号每个模块下最多 100 个错误这套结构对绝大多数中型系统已经足够。如果服务数量可能超过 100可以把第一段扩展到 3 位变成AAABBCC的七位结构。我见过一些团队直接用 8 位前 4 位是服务后 4 位是错误序号简单粗暴但也可用缺点是模块维度丢失了。提示位数规划一定要在项目启动阶段就定死并且写进团队规范。中途改位数是灾难性的所有已经对接的调用方都要跟着改。2.3 错误码的命名与语义约定数字本身没有语义语义是靠约定赋予的。所以除了编码规则还需要一套命名和语义约定。我通常会在团队里推行这几条规则成功码统一为 0不要用 200 或 10 是最不容易产生歧义的。错误码不使用负数负数在某些语言和序列化格式里处理起来有坑。保留段位比如9999段专门留给系统级错误参数校验失败、限流、熔断等业务模块不占用。错误码一旦发布不修改语义只能废弃或新增。修改已发布错误码的含义是接口契约的破坏性变更。关于“成功码用 0 还是 200”团队里经常有争论。用 200 的人觉得和 HTTP 状态码对齐看着舒服用 0 的人觉得简洁。我的观点是如果你把业务码和 HTTP 码分开那用 0 更干净避免调用方误以为两者有关联。如果非要对齐那也要在文档里写清楚这只是巧合不是映射关系。3. 错误信息的组织与国际化处理3.1 错误码与错误信息的分离一个常见的错误做法是把面向用户的文案直接写进错误码的返回里比如{code: 100101, msg: 您的密码不正确请重新输入}。这样做在单语言环境下没问题但一旦要做国际化或者同一个错误在不同场景下需要不同文案就会很被动。正确的做法是错误码和错误信息分离。服务端只返回错误码和必要的上下文参数文案由调用方根据错误码去查对应的文案表。比如服务端返回{code: 100101, params: {retryCount: 3}}前端拿到码之后去自己的语言包里查100101对应的文案模板再把retryCount填进去。这样做的好处有三个第一文案可以随时调整而不需要服务端发版第二多语言支持只需要维护多套文案表第三同一个错误码在不同端App、Web、小程序可以有不同措辞。3.2 面向用户和面向开发者的双轨信息错误信息其实有两类受众终端用户和开发/运维人员。这两类人需要的信息完全不同。用户需要的是“我该怎么办”开发者需要的是“哪里出了什么问题”。我的做法是在返回结构里同时保留两个字段{ code: 100101, message: 密码错误请重新输入, detail: user login failed: password mismatch, userId8823, attempt3, traceId: a1b2c3d4e5f6 }message是给用户看的简洁、友好、可国际化detail是给开发者看的包含足够的上下文用于排查traceId是链路追踪 ID用于把这次请求和后台日志关联起来。注意detail在生产环境要谨慎不要泄露敏感信息比如完整的手机号、身份证号等。3.3 国际化场景下的错误码处理国际化场景下错误码的设计要额外注意几点。首先错误码本身不能包含任何语言相关的信息它只是一个标识符。其次文案表要按语言维度组织通常是一个code - {zh: ..., en: ...}的映射。第三文案模板里的占位符要统一规范比如统一用{name}这种形式避免有的地方用%s有的地方用${name}。还有一个容易被忽略的点不同语言的语序不同。比如中文说“用户张三的订单不存在”英文说“Order not found for user Zhang San”占位符的位置和句子结构完全不一样。所以文案模板不能只做简单的字符串替换要允许整个句子结构随语言变化。这就是为什么文案表要按语言完整存储而不是在代码里拼接。4. 实操从零搭建一套错误码体系4.1 第一步梳理业务模块和服务边界动手写代码之前先拿一张纸把系统的服务边界和模块划分画出来。假设我们有一个电商系统拆成了用户服务、商品服务、订单服务、支付服务四个微服务每个服务下面又有若干模块。用户服务注册、登录、资料管理、地址管理 商品服务商品查询、库存、分类 订单服务下单、取消、查询、售后 支付服务支付、退款、对账按照前面说的AABBCC结构先给服务分配段位服务段位用户服务10商品服务20订单服务30支付服务40系统通用994.2 第二步定义每个模块的错误码以用户服务的登录模块为例模块编号定为 01那么登录相关的错误码就是1001xx。具体定义如下错误码含义面向用户文案100101用户名不存在账号不存在请检查后重试100102密码错误密码不正确请重新输入100103账号被锁定账号已被锁定请联系客服100104验证码错误验证码不正确100105登录次数超限尝试次数过多请稍后再试系统通用段位99下面定义一些全局错误错误码含义990001参数校验失败990002请求频率超限990003服务暂时不可用990004权限不足990005系统内部错误4.3 第三步代码层面的落地实现在代码层面我建议用一个枚举或常量类来集中管理错误码避免散落在各个业务逻辑里。以 Java 为例public enum ErrorCode { // 用户服务 - 登录模块 USER_NOT_FOUND(100101, 账号不存在请检查后重试), PASSWORD_MISMATCH(100102, 密码不正确请重新输入), ACCOUNT_LOCKED(100103, 账号已被锁定请联系客服), CAPTCHA_ERROR(100104, 验证码不正确), LOGIN_ATTEMPT_EXCEEDED(100105, 尝试次数过多请稍后再试), // 系统通用 PARAM_VALIDATION_FAILED(990001, 参数校验失败), RATE_LIMIT_EXCEEDED(990002, 请求频率超限), SERVICE_UNAVAILABLE(990003, 服务暂时不可用), PERMISSION_DENIED(990004, 权限不足), INTERNAL_ERROR(990005, 系统内部错误); private final int code; private final String defaultMessage; ErrorCode(int code, String defaultMessage) { this.code code; this.defaultMessage defaultMessage; } public int getCode() { return code; } public String getDefaultMessage() { return defaultMessage; } }如果团队用 Python可以用一个字典或者 dataclass 来组织from dataclasses import dataclass dataclass(frozenTrue) class ErrorCode: code: int message: str class UserErrors: USER_NOT_FOUND ErrorCode(100101, 账号不存在请检查后重试) PASSWORD_MISMATCH ErrorCode(100102, 密码不正确请重新输入) ACCOUNT_LOCKED ErrorCode(100103, 账号已被锁定请联系客服)关键点是错误码的定义要集中不要散落。我见过有的项目在 A 文件里定义1001是“用户不存在”在 B 文件里又定义1001是“参数错误”这种冲突排查起来非常痛苦。4.4 第四步统一返回结构的封装错误码最终要通过统一的返回结构暴露出去。一个典型的返回结构长这样{ code: 0, message: success, data: {}, traceId: a1b2c3d4 }失败时{ code: 100102, message: 密码不正确请重新输入, data: null, traceId: a1b2c3d4 }在服务端我通常会写一个统一的响应包装类业务代码只需要抛出带有 ErrorCode 的异常由全局异常处理器统一转换成这个结构。这样业务代码里就不会到处出现return Response.error(...)这种重复代码。public class BizException extends RuntimeException { private final ErrorCode errorCode; private final Object[] params; public BizException(ErrorCode errorCode, Object... params) { super(errorCode.getDefaultMessage()); this.errorCode errorCode; this.params params; } public ErrorCode getErrorCode() { return errorCode; } public Object[] getParams() { return params; } }全局异常处理器捕获BizException取出错误码和参数组装成统一返回结构。非BizException的未知异常统一映射到990005并且记录完整堆栈到日志但返回给调用方的信息要脱敏。5. 常见问题与排查技巧实录5.1 错误码冲突和重复怎么办这是最常见的问题尤其是在多人协作、多个服务并行开发的时候。A 同学在用户服务里定义了100101B 同学在订单服务里也定义了100101联调的时候前端就懵了。解决这个问题的根本办法是建立错误码注册机制。可以是一个简单的内部文档也可以是一个配置中心里的错误码表任何新增错误码都要先查重再登记。如果团队规模不大用一个共享的枚举文件放在公共依赖里也能解决。关键是流程上要有约束不能各写各的。如果已经出现了冲突排查方法是在网关或日志里打印完整的错误码和来源服务名通过来源服务来区分。但这只是补救治本还是要靠注册机制。5.2 错误码文档和代码不同步文档里写着100103是“账号被锁定”代码里实际返回的是“账号不存在”这种不同步在快速迭代的项目里非常普遍。我的经验是让文档从代码生成而不是手工维护。可以在构建流程里加一步扫描错误码枚举自动生成 Markdown 或 HTML 格式的错误码文档发布到内部 Wiki 上。这样代码改了文档自动更新不会出现不一致。如果做不到自动生成至少要做到“改代码必须改文档”的 Code Review 检查项。我见过有团队把错误码文档的更新作为合并请求的必填项虽然麻烦但确实有效。5.3 错误码越加越多如何治理项目跑了一两年错误码从最初的几十个膨胀到几百个其中很多已经废弃不用了但没人敢删。这时候就需要做一次错误码治理。治理的思路是先统计每个错误码在过去一段时间内的实际调用次数把零调用的标记为“疑似废弃”然后和业务方确认确认废弃的在文档里标注 deprecated但不要直接删除因为可能有老版本客户端还在用新增错误码时要求必须说明使用场景避免继续无序膨胀。我个人的做法是每季度做一次错误码盘点把新增的、废弃的、高频的分别列出来同步给前后端和测试团队。这个习惯坚持下来错误码表就不会失控。5.4 常见问题速查表问题现象可能原因排查方向解决建议前端无法区分错误类型错误码粒度过粗检查是否所有失败都返回同一个码按业务场景细分错误码错误码重复冲突缺少注册机制全局搜索错误码定义建立统一注册表文档与代码不一致手工维护文档对比代码枚举和文档文档从代码自动生成错误信息泄露敏感数据detail 字段未脱敏检查返回结构生产环境过滤敏感字段国际化文案错位占位符不统一检查文案模板统一占位符规范老客户端不识别新错误码未做兼容处理检查客户端版本分布新码降级为通用码返回提示错误码的兼容性处理经常被忽略。当服务端新增了一个错误码而老版本客户端不认识它时客户端可能会直接崩溃或者显示空白。稳妥的做法是客户端对未知错误码统一降级显示为“操作失败请稍后重试”同时上报埋点便于后续分析。6. 错误码体系的演进与扩展思路6.1 从单体到微服务的平滑过渡很多系统一开始是单体应用错误码用简单的分段数字就够了。当拆成微服务之后错误码体系需要相应调整。我的建议是在拆分之前就把服务段位预留好即使当前还是单体也按照未来可能拆分的维度来分配段位。这样拆分的时候错误码不需要大改只需要把对应段位的代码迁移到新服务即可。如果已经拆分了但错误码还是混在一起的可以逐步迁移新服务用新段位老服务保持不动等老服务重构时再统一。不要为了错误码统一而专门做一次大迁移投入产出比不高。6.2 错误码与监控告警的联动错误码不只是给调用方看的它还是监控系统的重要数据源。我通常会在网关层对错误码做聚合统计比如每分钟统计各个错误码的出现次数当某个错误码的频率突增时触发告警。这里有个技巧不是所有错误码都值得告警。像“密码错误”这种用户输入导致的错误频率高是正常的不应该告警而像“系统内部错误”“服务不可用”这种频率突增往往意味着故障需要立即关注。所以错误码在设计时就应该标注严重级别监控系统根据级别决定是否告警。可以在错误码定义里加一个level字段public enum ErrorLevel { INFO, // 正常业务错误不告警 WARN, // 需要关注频率异常时告警 ERROR, // 需要立即处理 FATAL // 严重故障直接告警 }6.3 面向第三方开放时的错误码设计如果系统要对外开放 API 给第三方开发者使用错误码设计的要求会更高。第三方开发者没有你的内部文档他们只能依赖你公开的 API 文档。所以这时候错误码要做到文档完备、语义清晰、稳定不变。我建议对外开放的错误码单独一套不要和内部错误码混用。内部错误码可以随意调整对外开放的错误码一旦发布就要保持稳定。同时对外开放的错误码要提供详细的文档包括每个码的含义、可能的原因、建议的处理方式。最好还能提供一个在线的错误码查询工具开发者输入错误码就能看到详细信息。另外对外开放时错误信息要格外注意脱敏不能暴露内部服务名、IP、堆栈等敏感信息。返回给第三方的 detail 字段要经过严格过滤只保留必要的上下文。6.4 错误码的版本管理当 API 有多个版本时错误码也需要考虑版本管理。我的做法是错误码本身不区分版本但错误码的含义变更要通过新增码来实现。比如 v1 版本里100101表示“用户不存在”v2 版本里这个场景细分为“用户不存在”和“用户已注销”两个码那就新增100106表示“用户已注销”100101的含义保持不变。这样老版本的调用方不受影响新版本可以使用更细的码。如果确实需要废弃某个错误码要在文档里标注废弃时间并给出替代码给调用方足够的迁移时间。直接删除错误码是危险的会导致老调用方无法正确处理。7. 我踩过的几个坑和实操心得7.1 不要用错误码传递业务数据有一次我在设计一个抽奖接口时把“未中奖”和“中奖但奖品已发完”都用了同一个错误码然后想通过 message 里的文案来区分。结果前端做中奖动画时没法判断到底是哪种情况只能去解析文案非常脆弱。后来我新增了一个错误码专门表示“奖品已发完”前端就能准确处理了。这个教训是错误码要表达的是“结果类型”而不是“结果详情”。结果详情应该通过 data 字段传递错误码只负责分类。7.2 错误码的日志记录要包含足够上下文排查问题时光有一个错误码是不够的。我习惯在记录错误日志时把错误码、traceId、用户标识、请求参数的关键字段都带上。这样拿到一个错误码就能通过 traceId 快速找到对应的日志看到完整的上下文。但要注意日志里不能记录敏感信息比如密码、完整的身份证号、银行卡号等。这些字段要么不记录要么脱敏后再记录。7.3 错误码的测试要覆盖到错误码的测试经常被忽略。我建议在单元测试里对每个错误码至少有一个测试用例验证在对应场景下确实返回了正确的错误码。在集成测试里要验证错误码经过网关、经过序列化之后调用方拿到的还是正确的码。还有一个容易漏测的点并发场景下的错误码。比如限流错误码在低并发测试时永远不会触发上线后一压测就出问题。所以限流、熔断相关的错误码要有专门的压测用例来覆盖。7.4 给新人的建议如果你是第一次设计错误码体系我的建议是先不要追求完美先把框架搭起来定义好段位规则和注册流程然后随着业务发展逐步完善。错误码体系是演进而来的不是一次设计出来的。重要的是建立规范和维护习惯而不是一开始就设计出一套“终极方案”。另外多和前端、测试、运维沟通了解他们实际需要什么样的错误信息。很多时候设计者觉得已经很清楚的错误码使用者却觉得不够用。站在使用者的角度去设计才能做出真正好用的错误码体系。最后分享一个我一直在用的小技巧在错误码的注释里写上“什么场景下会返回这个码”和“调用方应该怎么处理”这样即使是几个月后回来看代码也能快速理解每个错误码的用途。这个习惯看起来不起眼但在长期维护中能省下大量时间。