【工具链】错误码体系：统一错误码的分配与查询

实战应用：用在哪里

前后端的每一个错误都需要一个可查询的错误码：散落的字符串错误信息让客户端无法程序化处理，统一错误码的分配让错误有编号有语义有出处。错误码体系是前后端协作的基础协议。

错误码的分配

---错误码的定义与分配
local ERROR_CODES = {
    [1001] = { msg = "余额不足", module = "trade" },
    [1002] = { msg = "等级不够", module = "trade" },
    [2001] = { msg = "背包已满", module = "item" },
    [2002] = { msg = "物品不存在", module = "item" },
}
function ErrorCode.get(code)
    return ERROR_CODES[code] or { msg = "未知错误" }
end

错误码按模块分段：1000 段交易、2000 段物品、3000 段任务，段位的分配表防止跨模块冲突。错误码的 msg 支持格式化占位符，动态参数（如还差多少金币）在发送时填充。

错误的分发

---错误码的分发：服务端推错误码，前端查表显示
function ErrorCode.send(actor, code, params)
    local def = ERROR_CODES[code]
    if not def then return end
    local msg = def.msg
    if params then
        msg = string.format(msg, table.unpack(params))
    end
    sendmsg(actor, 1, "【" .. code .. "】" .. msg)
end

错误码的发送统一走 ErrorCode.send，前端按 code 查本地化的文案模板。错误码的查询接口给客服系统用，玩家报错时提供错误码，客服按码查到具体的错误原因。错误码的新增走审批：段位的分配与语义的定义由架构组统一管理。

验证与监控

错误码的触发频次按模块日统计，高频错误码是优化的优先目标。

踩坑记录

错误码的段位冲突曾经让交易模块的 2001 与物品模块的 2001 含义不同，段位分配表的唯一性约束在定义时校验。错误码的废弃没有标记，已废弃的错误码仍被业务引用，废弃的标记与清理的流程是错误码生命周期的收尾。

上线要点

错误码的分配表进版本管理，段位的申请与释放走流程。错误码的文案支持多语言，国际化版本的文案在语言表里映射。错误码的触发频次按模块日统计，高频错误码是体验优化的优先目标。

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