3. 异常与错误码设计：错误码编码规范、错误码分段规则、错误码与HTTP状态码映射

在企业级系统中，错误码是异常信息的“数字指纹”。一套严谨的错误码体系，能让运维人员、客户端、监控系统在毫秒级定位问题根因，避免“查日志猜错误”的低效模式。本章从编码规范、分段规则、HTTP 状态码映射三个维度，构建可落地的错误码骨架。

3.1 错误码编码规范：三段式结构

推荐采用 “系统标识 + 模块编号 + 错误序号” 的三段式结构，总长度固定为 8 位数字，便于机器解析和人工记忆。

完整示例：01001015 表示“交易系统-订单模块-库存不足”。

3.2 错误码分段规则：按严重程度与来源划分

错误码不仅标识“发生了什么”，还要隐含“有多严重”和“谁导致的”。分段规则将错误码划分为三大区间：

3.3 错误码与HTTP状态码映射

错误码是业务层面的标识，HTTP 状态码是传输层面的协议。两者需要建立明确的映射关系，避免客户端收到 500 却不知道具体业务含义，或收到 200 但 body 里藏着错误。

3.4 工程落地：错误码枚举与响应体结构

在 Java 工程中，推荐使用枚举类集中管理错误码，避免散落在各处魔法数字。

public enum ErrorCode {
    // 业务警告 - 订单模块
    ORDER_STOCK_INSUFFICIENT("01001015", "库存不足"),
    ORDER_PRICE_CHANGED("01001016", "价格已变动"),

    // 系统错误 - 订单模块
    ORDER_DB_TIMEOUT("01001101", "订单数据库超时"),
    ORDER_CACHE_UNAVAILABLE("01001102", "订单缓存不可用"),

    // 外部依赖 - 支付模块
    PAY_GATEWAY_TIMEOUT("01002201", "支付网关超时"),
    PAY_THIRD_PARTY_REJECT("01002202", "第三方支付拒绝");

    private final String code;
    private final String message;

    ErrorCode(String code, String message) {
        this.code = code;
        this.message = message;
    }

    public String getCode() { return code; }
    public String getMessage() { return message; }
}

统一响应体结构示例：

{
  "success": false,
  "code": "01001015",
  "message": "库存不足",
  "timestamp": 1712345678000,
  "path": "/api/order/create",
  "traceId": "a1b2c3d4e5f6"
}

3.5 错误码生命周期管理

错误码不是一次性定义就结束的，需要纳入变更管理流程：

• 新增：必须经过架构评审，确认不与其他错误码语义重叠。
• 废弃：标记为 @Deprecated，保留至少两个大版本后再移除。
• 文档化：每个错误码在 Wiki 或 API 文档中记录触发条件、处理建议、示例日志。
• 监控告警：系统错误和外部依赖段的错误码出现时，自动触发 P0/P1 告警。

通过以上规范，错误码从“一串数字”进化为“可编程的异常语义单元”，为后续的监控、告警、自动化运维打下坚实基础。