3、错误码设计原则：错误码分类（系统级/业务级）、错误码命名规范、错误码与HTTP状态码映射

错误码是分布式系统与API契约中最基础的故障信号载体。一个设计良好的错误码体系，能让调用方在毫秒级内判断故障性质、定位问题模块、决定重试策略或触发降级。本章从分类、命名、映射三个维度，建立错误码设计的工程规范。

3.1 错误码分类：系统级 vs 业务级

错误码按影响范围与修复责任，划分为系统级与业务级两大类。二者在定义、处理方式与生命周期上存在本质差异：

3.2 错误码命名规范

错误码采用分层数字编码结构，每段数字携带明确的语义信息。推荐格式：

AB CD EFG

A  : 错误级别（1=系统级，2=业务级，3=安全级）
B  : 模块标识（0=通用，1=用户，2=订单，3=支付，4=搜索，5=存储）
CD : 错误类别（01=参数校验，02=状态冲突，03=资源缺失，04=超时，05=限流）
EFG: 具体错误序号（001-999，按模块递增分配）

命名示例：

• 101001 — 系统级 · 通用模块 · 参数校验 · 请求体格式错误
• 202001 — 业务级 · 订单模块 · 状态冲突 · 订单已支付不可取消
• 303001 — 业务级 · 支付模块 · 资源缺失 · 账户余额不足
• 104001 — 系统级 · 通用模块 · 超时 · 上游服务响应超时

3.3 错误码与HTTP状态码映射

Go服务通常通过HTTP/HTTPS暴露API，错误码需要与HTTP状态码建立一对多的映射关系。同一HTTP状态码可对应多个业务错误码，但一个错误码只能映射到一个HTTP状态码。

标准映射规则：

3.4 错误码分类与映射关系图

下图展示了系统级与业务级错误码的划分边界，以及它们与HTTP状态码的映射关系：

3.5 Go代码中的错误码断言实践

在Go接口契约中，错误码通常以整型常量或自定义类型的形式定义，并通过接口返回。调用方通过断言错误码来判断故障类型：

// 定义错误码类型
type ErrCode int

const (
    ErrCodeSuccess          ErrCode = 0
    ErrCodeInvalidParam     ErrCode = 101001
    ErrCodeOrderStateConflict ErrCode = 202001
    ErrCodeInsufficientBalance ErrCode = 303001
    ErrCodeUpstreamTimeout  ErrCode = 104001
)

// 错误码与HTTP状态码映射
var errCodeToHTTP = map[ErrCode]int{
    ErrCodeInvalidParam:       400,
    ErrCodeOrderStateConflict: 409,
    ErrCodeInsufficientBalance: 403,
    ErrCodeUpstreamTimeout:    504,
}

// 断言示例
func handleError(err error) {
    if err == nil {
        return
    }
    // 通过类型断言获取错误码
    if e, ok := err.(interface{ Code() ErrCode }); ok {
        code := e.Code()
        httpStatus := errCodeToHTTP[code]
        // 根据httpStatus决定响应状态码
        _ = httpStatus
    }
}