前端API错误码设计为何总在两端扯皮？我的一份建议规范

几乎每个前端团队都经历过这样的场景：联调群里甩出一张截图，接口返回 200，code 是 5001，页面白屏。前端问后端“这个码什么意思”，后端回“文档里有”；前端翻文档，发现文档上写的 5001 是“余额不足”，而这次报的是“活动已结束”。于是一来一回，问题从技术问题变成了态度问题。

扯皮的根源从来不是谁不专业，而是边界没划清。HTTP 状态码、业务错误码、展示文案，这三件事被硬塞进了一个字段里，谁都能解释，谁都不负责。

根源：三重语义被压进同一个字段

一个错误响应其实同时承载了三种完全不同的信息：

• 传输层：这次请求在网络上、协议上是否成功（HTTP status）
• 业务层：这次操作在业务规则上为什么失败（业务码）
• 展示层：这句话要不要给用户看、怎么看（文案与交互）

当后端用 HTTP 200 + code:500 表达业务失败时，监控、网关、重试中间件全部失明；当前端拿到 message: "系统异常" 直接弹 toast 时，用户看到的是开发者的内部语言。三者混用，扯皮就是必然。

五个典型翻车现场

1. 一切皆 200，业务失败藏在自己的 code 里，网关和 APM 无法统计错误率。
2. message 直接透传给用户，出现 NullPointerException 或者英文堆栈。
3. 错误码复用且无命名空间，1001 在订单模块是“库存不足”，在用户模块是“未登录”。
4. 前端硬编码判断 if (res.code === 40001)，后端一改码，前端全量发版。
5. 文档漂移：接口加了新码，文档还是三个月前的版本。

建议规范：三层分离，各归其位

原则一句话：**HTTP 状态码只表达传输结果，业务码只表达业务语义，文案只负责展示，三者不互相替代。**

编码规则：分段、定长、可读

建议 6 位字符串：模块(2) + 类型(2) + 序号(2)，例如 10-20-01。

类型段可以固定含义：

• 10 参数类（客户端可自查）
• 20 认证授权类（需要跳登录或无权限提示）
• 30 业务规则类（需要展示具体原因）
• 40 依赖类（下游服务、第三方）
• 50 系统类（未知，兜底）

全局预留 0 表示成功，1xxxxx 作为通用码（未登录、token 过期、无权限、限流）。码用字符串而非数字，避免 0 与 "0"、前导零、JS 精度这些历史坑。

统一响应体

{
  "code": "30201",
  "message": "sku 1234 stock insufficient",   // 给开发看
  "userMessage": "该商品暂时缺货",              // 给用户看，可空
  "traceId": "a1b2c3d4",
  "data": null
}

message 面向排查，允许技术细节；userMessage 面向终端，前端没有覆写需求时直接用；traceId 是排障时双方唯一不用吵架的凭据。

前端只认「可操作性分类」，不认具体码

前端不应该、也没必要理解每一个业务码。它只需要知道这个错该做什么动作：

具体码只在需要特殊交互（比如弹确认框）时例外处理，且必须写进 registry 备注。

单一事实来源与类型生成

维护一份 error-codes.yaml，由它生成三样东西：接口文档、后端枚举、前端 TS 联合类型。

type BizCode = '10001' | '10002' | '30201' | '30202';

这样前端写 switch 时是编译期检查，后端改码时是 CI 报错，而不是线上事故。

变更规则：只增不删不改语义

• 新增码：走新序号，不占用废弃码。
• 废弃码：标 deprecated，保留至少两个大版本。
• 修改语义：禁止。语义变了就是新码。
• 删码：需要跨端评审，不允许单方面操作。

一份最小落地清单

1. 业务码与 HTTP 状态码解耦，HTTP 只表达传输结果。
2. 错误码注册中心化，文档和类型由它生成。
3. 响应体固定包含 code / message / userMessage / traceId。
4. 前端按前缀做分类兜底，不硬编码具体码。
5. 变更走评审，废弃有过渡期。

扯皮的本质是权责不清，不是能力问题。把“谁定义、谁消费、怎么改”写进规范，两端就不会再为同一个 5001 来回甩截图了。规范不用一次到位，但第一次对齐之后，后面每一次联调都会便宜一点。