📚 课程目录第3章异常码设计原则

三、异常码设计原则：语义化、可读性、可扩展性与兼容性

端侧推理异常码是连接运行时错误、用户感知与研发排障的“通用语言”。一套设计糟糕的异常码体系，往往表现为：错误码含义模糊、不同模块重复编号、版本升级后旧码失效、日志中大量“unknown error”无法定位。本章围绕异常码设计的四大核心原则——语义化、可读性、可扩展性、兼容性，以及异常码冲突的避免方法，建立一套可落地、可评审、可演进的设计规范。

3.1 语义化：让异常码“见码知意”

核心原理：语义化要求异常码本身携带足够的信息，使开发人员、运维人员甚至支持人员在不查阅文档的情况下，也能大致判断错误类别和发生位置。一个语义化的异常码通常由“模块标识 + 错误类别 + 具体原因”三段式构成。例如 NPU_LOAD_MODEL_TIMEOUT 比 E1003 更能直接传达“NPU 加载模型超时”这一信息。

判断方法：检查异常码是否满足以下三个问题——① 看到码的第一眼能否判断属于哪个模块？② 能否判断是资源类、参数类、状态类还是外部依赖类错误？③ 能否在日志中通过关键字快速检索到相关代码位置？如果任一答案为否，则语义化不足。

语义化等级	示例	可读性	适用场景
纯数字码	1003	差，需查表	早期原型验证
模块+数字	NPU_1003	中，可判断模块	模块内部使用
模块+类别+数字	NPU_LOAD_1003	良，可判断操作	跨模块调用
模块+类别+语义短语	NPU_LOAD_MODEL_TIMEOUT	优，自解释	对外API、日志规范

经验提醒：端侧推理场景中，日志空间有限，建议在日志中同时输出“短码（如 NPU_E_1003）”和“语义短语（如 model load timeout）”，兼顾检索效率与可读性。

3.2 可读性：日志友好与检索效率

核心原理：可读性关注异常码在日志、监控面板、上报数据中的呈现效果。端侧设备日志往往被截断、聚合或加密传输，异常码需要具备“即使只有码也能定位问题”的能力。可读性设计包括：固定长度或固定前缀、大小写规范、分隔符统一、避免易混淆字符（如 0/O、1/l）。

操作流程：① 定义异常码统一格式，例如 MODULE_CATEGORY_OPERATION_REASON；② 规定日志输出模板，必须包含异常码、错误描述、上下文参数（如模型名、输入尺寸）；③ 建立日志检索规范，确保异常码在日志中独立成段，不被其他字符串拼接破坏。

// 推荐日志格式
[ERROR] [NPU] NPU_LOAD_MODEL_TIMEOUT | model=face_det_v3.onnx | size=12MB | timeout_ms=5000 | device=0

// 不推荐日志格式
[ERROR] NPU error 1003 happened during loading, please check model file and retry later.

风险说明：不要将异常码嵌入到长句中间，否则日志采集系统无法按码提取字段。建议使用 key=value 结构，便于结构化日志解析。

3.3 可扩展性：预留空间与分层设计

核心原理：可扩展性要求异常码体系能够容纳未来新增的模块、错误类型和硬件平台，而不需要推翻重来。设计时应采用分层编码结构：第一层为模块标识（如 NPU、CPU、GPU、DSP、MEM），第二层为错误类别（如 LOAD、RUN、ALLOC、SYNC），第三层为具体原因序号。每层预留足够的编码空间。

案例拆解：某端侧 AI 推理框架初始设计时，NPU 模块仅分配了 0-99 的序号空间。随着新硬件 NPU 版本迭代，新增了“权重压缩解压失败”“算子融合失败”等错误，原空间迅速耗尽。重构后采用 NPU_LOAD_MODEL_TIMEOUT 三段式，每段独立扩展，不再受数字范围限制。

层级	字段	示例值	扩展策略
L1 模块	NPU / CPU / MEM / SYS	NPU	新增硬件平台时增加新前缀
L2 类别	LOAD / RUN / ALLOC / SYNC / CONFIG	LOAD	新增错误类型时增加类别词
L3 原因	TIMEOUT / INVALID_PARAM / OOM / UNSUPPORTED	TIMEOUT	具体原因自由扩展，不设上限

设计建议：在异常码定义文件中，为每个模块预留 20% 的“保留段”，用于未来扩展。同时建立异常码字典表，每新增一个码必须更新字典并注明引入版本。

3.4 兼容性：版本演进不破坏既有契约

核心原理：兼容性指异常码在软件版本升级过程中，旧版本中已定义的异常码不能被删除、修改含义或改变数值。端侧设备通常存在多版本固件并存的情况，若新版本改变了异常码含义，会导致旧版日志分析工具失效、监控告警误报。

判断方法：在发布新版本前，执行异常码兼容性检查——① 对比新旧版本异常码字典，确认无删除、无数值变更、无含义变更；② 若确需修改，必须新增码替代旧码，并在文档中标注 deprecated；③ 对于已对外暴露的 API 异常码，至少保留 3 个版本的兼容期。

常见误区：有些团队为了“整洁”而删除废弃异常码，导致旧设备上报的码无法解析。正确做法是保留定义但标记废弃，并让日志系统能够识别废弃码并给出提示。

3.5 避免异常码冲突：注册表与命名空间

核心原理：异常码冲突指两个不同模块或不同开发者定义了相同的码值，导致日志解析时无法区分错误来源。冲突的根源在于缺乏统一的分配机制。解决思路是引入“全局注册表 + 模块命名空间 + 自动化校验”三重机制。

操作流程：

建立全局注册表：在代码仓库中维护 error_codes.yaml 或 error_codes.h，所有异常码必须在此登记，包含模块名、码值、语义描述、引入版本、责任人。
模块命名空间隔离：每个模块分配唯一前缀（如 NPU_、CPU_），码值仅需在模块内唯一，跨模块天然隔离。
CI 自动化校验：在持续集成流水线中加入脚本，扫描代码中所有异常码定义，与注册表比对，发现重复或未登记即构建失败。
Code Review 人工把关：在代码评审中增加异常码变更检查项，确保新码遵循规范。

# error_codes.yaml 示例片段
version: "3.2.0"
modules:
  NPU:
    prefix: "NPU_"
    codes:
      - { code: "NPU_LOAD_MODEL_TIMEOUT", value: 0x1001, desc: "模型加载超时", since: "2.0.0", status: "active" }
      - { code: "NPU_LOAD_MODEL_OOM", value: 0x1002, desc: "模型加载内存不足", since: "2.1.0", status: "active" }
      - { code: "NPU_RUN_INVALID_INPUT", value: 0x2001, desc: "推理输入参数非法", since: "2.0.0", status: "active" }
  CPU:
    prefix: "CPU_"
    codes:
      - { code: "CPU_RUN_UNSUPPORTED_OP", value: 0x3001, desc: "不支持的算子", since: "2.0.0", status: "active" }

案例拆解：某团队在开发端侧推理引擎时，NPU 模块和 CPU 模块各自独立定义错误码，均使用了 1001 表示“加载失败”。当异构执行时，日志中出现 1001 无法判断是 NPU 还是 CPU 出错。引入注册表后，NPU 使用 0x1001，CPU 使用 0x3001，并通过 CI 脚本扫描所有 #define 和枚举定义，确保无重复。此后新加入的 DSP 模块也遵循同一机制，未再发生冲突。

复盘经验：异常码冲突的根因往往不是技术问题，而是流程缺失。只要坚持“先登记、后使用”的原则，配合自动化检查，冲突问题可以完全避免。建议在项目启动初期就建立注册表，不要等到代码量大了再补。

3.6 总结与设计自检清单

异常码设计不是一次性的工作，而是伴随项目演进的持续治理过程。以下自检清单可作为评审依据：

每个异常码是否包含模块前缀？
异常码是否在全局注册表中登记？
日志中是否同时输出异常码和语义描述？
新版本是否删除了旧异常码？若删除，是否标记 deprecated？
CI 中是否有异常码查重脚本？
异常码字典是否随版本发布自动更新？

遵循语义化、可读性、可扩展性、兼容性四大原则，并落实注册表与自动化校验机制，端侧推理异常码体系才能真正成为研发与运维之间的高效桥梁，而非新的沟通障碍。