3、错误码类型定义：定义业务错误码类型、错误码的常量与 iota 枚举、错误码的层级结构

在 Go 安全错误码断言接口契约体系中，错误码的类型定义是构建整个契约体系的基石。一个设计良好的错误码类型，不仅需要承载业务语义，还必须具备可枚举、可组合、可层级推导的特性。本节将深入讲解如何通过 Go 语言的类型系统、iota 枚举机制以及层级结构设计，构建一套既安全又易于维护的错误码体系。

3.1 业务错误码类型定义

错误码不应仅仅是 int 或 string 的简单别名，而应是一个具备自描述能力的强类型。我们推荐使用 type 关键字定义基础错误码类型，并为其附加方法，使其成为契约的一部分。

// ErrCode 是全局业务错误码的基础类型
type ErrCode int

// String 实现 fmt.Stringer 接口，便于日志输出
func (e ErrCode) String() string {
    if name, ok := errCodeNames[e]; ok {
        return name
    }
    return "UNKNOWN_ERRCODE"
}

// HTTPStatus 返回该错误码对应的 HTTP 状态码
func (e ErrCode) HTTPStatus() int {
    if status, ok := errCodeHTTPStatus[e]; ok {
        return status
    }
    return 500 // 默认服务端错误
}

3.2 错误码常量与 iota 枚举

使用 iota 枚举是 Go 语言中定义连续常量的标准做法。在错误码体系中，我们利用 iota 为不同层级的错误码分配唯一且可排序的数值，同时结合位运算或分组偏移量，实现错误码的层级归属。

const (
    // 通用系统级错误码（0-999）
    ErrSuccess       ErrCode = 0
    ErrUnknown       ErrCode = 1
    ErrInternal      ErrCode = 2
    ErrTimeout       ErrCode = 3
    ErrRateLimit     ErrCode = 4

    // 业务模块 A 错误码（1000-1999）
    ErrAModuleBase   ErrCode = 1000 + iota
    ErrAInvalidParam          // 1001
    ErrANotFound              // 1002
    ErrADuplicate             // 1003
    ErrAAuthFailed            // 1004

    // 业务模块 B 错误码（2000-2999）
    ErrBModuleBase   ErrCode = 2000 + iota
    ErrBInvalidParam          // 2001
    ErrBNotFound              // 2002
    ErrBPermissionDenied      // 2003
)

3.3 错误码的层级结构

错误码的层级结构是安全断言接口契约的核心。通过将错误码划分为系统级、模块级、子模块级和具体错误级，可以实现错误码的快速定位与聚合分析。层级结构通常通过数值区间或位掩码来实现。

// 层级掩码定义
const (
    LevelSystem   ErrCode = 0x0000 // 系统级
    LevelModule   ErrCode = 0x1000 // 模块级
    LevelSubModule ErrCode = 0x2000 // 子模块级
    LevelDetail   ErrCode = 0x3000 // 具体错误级
)

// 层级提取函数
func (e ErrCode) Level() ErrCode {
    return e & 0xF000 // 取高 4 位作为层级标识
}

func (e ErrCode) ModuleID() ErrCode {
    return e & 0x0FF0 // 取中间 8 位作为模块标识
}

func (e ErrCode) ErrorID() ErrCode {
    return e & 0x000F // 取低 4 位作为具体错误标识
}

3.4 层级结构在断言接口契约中的应用

在安全断言接口契约中，错误码的层级结构使得断言逻辑可以按层级进行匹配。例如，一个接口契约可以声明“只接受模块 A 的错误码”，或者“拒绝所有系统级错误码”。这种基于层级的断言能力，极大地增强了接口的安全性和可测试性。

// 断言接口契约示例：只允许模块 A 的错误码
func AssertModuleAError(errCode ErrCode) bool {
    return errCode.Level() == LevelModule && errCode.ModuleID() == 0x001
}

// 断言接口契约示例：拒绝所有系统级错误码
func RejectSystemError(errCode ErrCode) bool {
    return errCode.Level() != LevelSystem
}

3.5 错误码注册与命名规范

为了维护错误码的可读性和可维护性，建议遵循以下命名规范：

• 前缀统一： 所有错误码常量以 Err 开头，如 ErrInvalidParam。
• 模块标识： 在常量名中嵌入模块缩写，如 ErrUserNotFound、ErrOrderExpired。
• 层级可见： 通过注释或分组明确每个常量所属的层级，避免数值重叠。
• 注册中心： 维护一个全局的错误码注册表，用于冲突检测和文档生成。