错误码体系 v2 全量上线(#1391)

日期: 2026-04-25 影响范围: 全部服务 Result.code 字段 关联 PR: #1392 / #1393 / #1394 / #1395 / #1396 / #1397 / #1398 工单: #1391

🚨 前端接入提示

✅ 好消息:401/403/404 保留,现有拦截器零改动

HTTP 认证相关错误码(401 未授权 / 403 无权限 / 404 未找到)完全保留
前端 axios 拦截器 / 跳登录页逻辑 无需任何改动
400 参数校验 / 500 系统错误 保留原语义

🆕 业务错误码升级为 6 位数字,前端可选接入

所有业务模块的 Result.code 字段不再是 400/500 通用码,变为 6 位数字业务码
如 400101 = 产品不存在、500311 = 订单当前状态不允许取消、510411 = 合同签约失败 等
message 字段保留原业务提示中文,所有已有 uni.showToast(res.data.message) 代码继续生效

📋 6 位码段位表

段位前缀	模块	示例
`100xxx`	common 通用	`100501` 流控拦截 / `100502` 幂等拦截 / `100901` Feign 空数据
`110xxx`	auth 认证授权	`110001` 未认证(预留)
`200xxx-299xxx`	user 用户	`230301` 短信频率限制 / `230302` 短信日发送上限 / `260204` 状态列无权管理
`300xxx-399xxx`	resource 资源	`300106` 景点无权操作 / `310xxx` 酒店 / `340xxx` 用车 / `380001` 备品审批进行中不可删
`400xxx-499xxx`	product 产品	`400101` 产品不存在 / `410xxx` 价格 / `430xxx` 行程 / `460xxx` 高德地图
`500xxx-509xxx`	order 订单核心	`500xxx` 订单 CRUD / `500311` 状态不允许取消
`510xxx-549xxx`	order 扩展	`510xxx` 合同 / `520xxx` 支付 / `530xxx` 退款 / `540xxx` 保险 / `549xxx` 投诉
`550xxx-599xxx`	order 子域	`550xxx` 行程 / `560xxx` 团报 / `580xxx` 到达/工单 / `590xxx` 加价折扣 / `593xxx` 发票
`600xxx-699xxx`	mp 小程序 BFF	`610xxx` 天气
`900xxx-999xxx`	system 系统级	`900001` 限流 / `900002` 熔断

🎯 前端可选接入(3 种粒度)

大多数场景:继续用 message 弹 toast,无需关心 code。

需要差异化处理的场景,可按以下 3 种粒度分支:

Level 1 粒度:HTTP 类(优先)

if (res.data.code === 401) // 跳登录
if (res.data.code === 403) // 无权限提示
if (res.data.code === 404) // 404 页
// 已有代码完全兼容,继续用即可

Level 2 粒度:按段位分支(业务大类)

const code = res.data.code;
if (code >= 400000 && code <= 499999) {
  // 产品相关错误,可选跳商品首页
} else if (code >= 500000 && code <= 599999) {
  // 订单相关错误
}

Level 3 粒度:按具体 code 分支(细粒度 UX)

if (res.data.code === 400301) {
  // 产品下架,跳首页
  uni.reLaunch({ url: '/pages/index/index' });
} else if (res.data.code === 510411) {
  // 合同签约失败,重试按钮
}

接入优先级建议:Level 1 必做(已有)→ Level 3 按 UX 需求逐个接入(非强制)。

🔧 技术变更细节

1. Feign 链路透传修复

修复前:下游服务抛 BusinessException(400301, "产品下架"),Feign 调用方 getCheckedData() 会吞码降级为 500。 修复后:上游 code 完整透传,前端能看到真实业务码。

2. 所有 admin/mp 接口的 Result.code 升级

之前:{code: 400, message: "产品不存在"} / {code: 500, message: "订单状态不允许取消"}
现在:{code: 400101, message: "产品不存在,ID=xxx"} / {code: 500311, message: "当前状态不允许取消,状态=PAID"}

3. message 字段保留关键子串

迁移采用 MessageFormat 占位符,所有原 message 关键中文子串保留(如"产品不存在"/"审批进行中"等),前端若用 message.includes(xxx) 判断仍可工作。

🧪 新 code 速查接口

各服务启动时自动注册所有错误码到中央 ErrorCodeRegistry,如需完整码表可通过以下方式查询:

后端日志:每个服务启动日志含 ErrorCodeRegistry scan complete, totalCodes=X, segments=Y
容量告警:任何段位使用率 ≥ 80% 自动 WARN 日志
未来扩展:计划提供 /internal/errorcode/catalog 接口导出 yaml 码表

⚠️ 3 日反馈窗口

如前端需要按具体 code 做差异化处理(Level 3),请在 2026-04-28 前 反馈:

哪个业务 code 需要特殊 UI 行为(跳页/重试/不展示等)
是否需要前端配置化 code-action 映射

超过 3 日无反馈视为按 Level 1 + message 继续使用,不阻塞迭代。

4.6 KiB 原始文件 Blame 文件历史