4. 错误码分类与设计原则：错误码结构、编码规则、层级关系、命名规范
适用场景
该章节适用于以下场景：
- 新系统或新功能模块设计初始错误码体系
- 已有系统需要规范化错误码，提升可观测性与排查效率
- 多团队、多服务协作时统一错误码策略，避免冲突与歧义
- Crash监控系统集成异常分类与根因分析时建立错误码映射规则
前置条件
- 已梳理业务模块划分（至少一级模块清单）
- 已定义错误严重等级（Fatal / Error / Warning / Info）
- 团队认可统一的错误码生命周期管理流程
- 已有或准备建立错误码登记系统（如数据库表或YAML存储库）
操作步骤
- 定义错误码整体结构：确定总位数（推荐8位十进制或16位十六进制），明确各分段含义。
- 设计编码规则：按“模块-系统-错误类型-序号”分层，每段固定长度（如2位），支持扩容预留。
- 建立层级关系：绘制树状层级图，保证父级编码能聚合子级错误。
- 制定命名规范：英文命名采用
UpperCamelCase + _ERROR_ + 描述，中文描述不超过20字。 - 编写设计文档：输出《错误码设计规范.md》及示例映射表。
- 评审与注册：涉及多团队的错误码需提交评审，通过后登记错误码仓库。
提示：推荐使用8位十进制
ABCDEFGH格式，每位0-9。例如：12010201 → 模块：12（媒体播放）、系统：01（Android）、错误类型：02（解码）、序号：01（参数无效）。
输入输出物
| 类型 | 条目 | 格式/示例 |
|---|---|---|
| 输入 | 模块划分清单 | JSON / YAML |
| 输入 | 现有错误码登记（如有） | CSV / 数据库导出 |
| 输出 | 错误码设计文档 | Markdown / Confluence页面 |
| 输出 | 错误码映射表 | CSV / TOML / 自动化映射规则 |
| 输出 | 示例代码段（生成器） | Python脚本 |
责任边界
- 架构师 / 技术负责人：审批错误码结构、编码规则和层级划分。
- 模块开发团队：按规范生成模块内错误码并完成注册。
- SRE / 监控运维：维护错误码映射表与Crash监控告警规则。
- QA团队：验证错误码符合规范，检查日志输出是否携带正确错误码。
- 文档管理员：归档变更记录，更新错误码在线查询页。
记录材料
| 材料名称 | 内容要求 | 保存位置 |
|---|---|---|
| 错误码设计规范 | 结构、编码规则、层级关系、命名规范全文 | 公司内Wiki / 代码仓库docs/ |
| 错误码注册表 | 每笔错误码的编码、模块、系统、类型、序号、中文描述、英文常量名、注册日期、负责人 | 数据库 / YAML仓库 |
| 变更日志 | 每次新增、废弃、修改错误码的时间、原因、审批人 | CHANGELOG.md |
异常处理
常见异常及处理方案
- 错误码冲突：两位模块编码用完时（如0-99），启用扩展位或重新规划模块粒度；运行时冲突通过监控告警触发人工合并。
- 命名不规范：使用自动化Lint工具检查常量命名，CI门禁拒绝非规范提交。
- 层级混乱：定期（每季度）review错误码层级树，使用脚本生成报告标记孤儿节点。
- 缺失文档：将错误码登记纳入开发流程Checklist，上线前必须完成注册。
验收标准
| 编号 | 验收项 | 判定方法 |
|---|---|---|
| AC-04-01 | 所有错误码均符合8位十进制结构 | 扫描所有常量定义，正则匹配^\d{8}$ |
| AC-04-02 | 每个错误码对应唯一英文常量名，无重复 | 执行脚本检查命名空间唯一性 |
| AC-04-03 | 错误码层级关系文档与实际代码一致 | 自动生成层级树并与设计文档对比 |
| AC-04-04 | 错误码映射表覆盖所有生产环境Crash类型 | 映射表与Crash监控标签做全量diff |
| AC-04-05 | 异常处理预案已集成到CI/CD门禁 | 模拟冲突提交，验证是否被阻断 |
错误码结构示意图
关键设计决策：每组两位（00-99）共支持 100×100×100×100 = 1亿个错误码，实际按模块分配后远大于一般需求。若某模块错误码超过100个，可为其单独分配多个AB编码。