【框架设计】统一错误码表：协议返回值的规范设计

实战应用：用在哪里

客户端提示"操作失败"却不知道为什么，客服只能逐个复现——错误码表缺失的代价每天都在支付。统一错误码表让协议返回值规范化：每个错误一个唯一编号、一段固定文案、一个处理指引。适用于全部前后端协议与后台接口。

错误码分段规则

0        成功
1xxx     通用错误（1001 参数缺失、1002 参数类型错误、1003 频率限制）
2xxx     背包与物品（2001 背包已满、2002 物品不足、2003 物品不可交易）
3xxx     任务系统（3001 任务未接取、3002 任务未完成、3003 奖励已领取）
4xxx     副本系统（4001 副本未开放、4002 次数用尽、4003 队伍条件不满足）
9xxx     安全类（9001 会话过期、9002 权限不足、9003 风控拦截）

分段规则让错误码自带可读性：看到 2xxx 就知道与物品相关。新功能申请新的百位区段，编号永不复用。

三条设计约定

码与文案分离。错误码是协议契约（永不变更语义），文案是运营素材（可随时调整），客户端展示文案、上报错误码。每个错误带上下文。返回结构里附带失败对象（哪个任务、哪个物品），前端提示才能精确。未知错误统一兜底。客户端收到未知码时展示通用失败文案并上报，服务端新增错误码不需要老客户端同步升级。

落地维护

错误码表进版本库（与协议 schema 同级管理），新增错误走 code review；接入 CI 检查脚本扫出"硬编码的错误数字"（不允许代码里直接写 3002，必须引用常量表）。错误码的统计进监控日报（哪个码本周突增），错误码突增往往就是新 bug 的第一个信号。错误码表定稿后，前后端关于"失败原因"的沟通成本归零——这是协议设计里回报率最高的一份文档。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。