4. 错误码分类设计：HTTP状态码映射、业务错误码范围划分、预留区间策略

错误码分类是错误码断言体系的基础骨架。一个设计良好的分类方案，能让开发者在看到错误码的瞬间就判断出：错误发生在哪一层、严重程度如何、应该由谁处理。本章从三个维度展开：HTTP 状态码映射（对外协议对齐）、业务错误码范围划分（内部领域隔离）、预留区间策略（未来扩展保障）。

4.1 三层错误码模型

在 Go 微服务架构中，错误码通常分为三层，每层承担不同的职责：

4.2 HTTP 状态码映射策略

HTTP 状态码是错误码体系对外的“第一张脸”。映射策略需要平衡语义准确性和客户端兼容性：

• 4xx 系列：客户端错误。包括参数校验失败（400）、认证失败（401）、权限不足（403）、资源不存在（404）、请求冲突（409）、频率限制（429）。
• 5xx 系列：服务端错误。包括内部错误（500）、服务不可用（503）、网关超时（504）。
• 2xx 系列：成功。业务层即使有逻辑错误（如余额不足），只要请求本身合法，仍返回 200，错误信息放在业务错误码中。

推荐映射表（Go 项目通用版）：

4.3 业务错误码范围划分

业务错误码是 L2 层的核心，通常使用 6 位或 8 位数字，按模块、功能、错误类型分段。以下是一个经过多个生产项目验证的划分方案：

4.4 预留区间策略

预留区间是错误码体系长期可维护性的关键。很多项目在初期只定义了当前用到的错误码，半年后新模块加入时发现码段已乱，不得不重构。以下是三种经过验证的预留策略：

• 模块级预留：每个模块分配一个连续区间（如 100000-199999），即使当前只用了前 10 个码，剩余空间也不允许其他模块占用。
• 版本级预留：在错误码中嵌入版本位（如 1 位版本号 + 5 位业务码），支持未来版本扩展而不破坏现有映射。
• 断言级预留：专门划出一个区间（如 800000-899999）给内部断言使用，这些错误码不会出现在生产环境的对外接口中，仅用于单元测试和集成测试的断言验证。

4.5 错误码分类架构图

下图展示了三层错误码模型与 HTTP 状态码映射、业务范围划分、预留区间之间的整体关系：

4.6 错误码断言中的分类实践

在 Go 代码中，错误码分类直接影响断言函数的实现。以下是一个基于分类的断言示例：

// 定义错误码分类常量
const (
    // 模块区间
    ErrCodeUserNotFound     = 100001
    ErrCodeUserPasswordWrong = 100002
    ErrCodeOrderCreateFailed = 200001
    ErrCodeOrderNotPaid      = 200002

    // 预留区间（内部断言专用）
    ErrCodeAssertTestOnly    = 800001
)

// 断言函数：根据错误码分类执行不同逻辑
func AssertErrorCode(err error, expectedCode int) bool {
    if err == nil {
        return false
    }

    // 提取业务错误码
    bizCode := ExtractBizCode(err)

    // 分类判断
    switch {
    case bizCode >= 100000 && bizCode < 200000:
        // 用户模块错误：记录审计日志
        log.Printf("[UserModule] assertion failed: code=%d", bizCode)
    case bizCode >= 200000 && bizCode < 300000:
        // 订单模块错误：触发订单补偿流程
        triggerOrderCompensation(bizCode)
    case bizCode >= 800000 && bizCode < 900000:
        // 内部断言错误：仅测试环境生效
        if !isTestEnv() {
            return false
        }
    }

    return bizCode == expectedCode
}

4.7 分类设计的常见反模式

以下是实际项目中容易出现的错误码分类问题，以及对应的改进方案：

4.8 分类设计的演进路线

错误码分类不是一次性设计，而是随着项目规模增长持续演进。推荐以下路线：

• 阶段一（MVP）：只划分 3-5 个模块区间，每个区间预留 1000 个码位，不做版本位。
• 阶段二（增长期）：模块超过 10 个时，引入区间跳跃分配法，每个模块至少预留 10000 个码位。
• 阶段三（成熟期）：引入版本位或服务 ID 位，支持多版本共存和灰度发布。
• 阶段四（平台期）：建立自动化错误码注册中心，CI 阶段自动检测冲突和重复。