4、错误码常量定义：使用 iota 定义错误码、错误码分组、错误码与错误消息绑定

在 Go 语言中，错误码的常量定义是构建健壮错误处理体系的基石。使用 iota 枚举器可以高效、可维护地定义一组递增的错误码常量，同时通过分组和消息绑定，将错误码从单纯的数字提升为携带语义的契约。

4.1 使用 iota 定义基础错误码

iota 是 Go 中用于常量生成器的预定义标识符，在 const 声明块中每行自动递增。这是定义错误码最简洁的方式。

package errcode

// 基础错误码：使用 iota 从 1000 开始递增
const (
    ErrSuccess       = 1000 + iota // 1000: 成功
    ErrInvalidParam                // 1001: 无效参数
    ErrNotFound                    // 1002: 资源未找到
    ErrUnauthorized                // 1003: 未授权
    ErrForbidden                   // 1004: 禁止访问
    ErrInternal                    // 1005: 内部错误
    ErrTimeout                     // 1006: 请求超时
    ErrConflict                    // 1007: 资源冲突
    ErrRateLimit                   // 1008: 频率限制
    ErrServiceUnavailable          // 1009: 服务不可用
)

4.2 错误码分组：按模块划分命名空间

在大型项目中，单一的错误码列表会变得难以管理。通过分组，可以为不同模块分配独立的错误码区间，避免冲突并提升可读性。

package errcode

// 用户模块错误码 (2000-2999)
const (
    ErrUserNotFound      = 2000 + iota // 2000: 用户不存在
    ErrUserPassword                     // 2001: 密码错误
    ErrUserDisabled                     // 2002: 用户已禁用
    ErrUserDuplicate                    // 2003: 用户已存在
    ErrUserTokenExpired                 // 2004: Token 过期
)

// 订单模块错误码 (3000-3999)
const (
    ErrOrderNotFound      = 3000 + iota // 3000: 订单不存在
    ErrOrderStatus                      // 3001: 订单状态异常
    ErrOrderAmount                      // 3002: 订单金额错误
    ErrOrderTimeout                     // 3003: 订单超时
    ErrOrderDuplicate                   // 3004: 重复订单
)

4.3 错误码与错误消息绑定

错误码本身是数字，需要与人类可读的消息绑定才能形成完整的错误信息。推荐使用 map 或 switch 实现双向映射。

package errcode

// CodeMsgMap 错误码到消息的映射
var CodeMsgMap = map[int]string{
    // 通用
    ErrSuccess:             "success",
    ErrInvalidParam:        "invalid parameter",
    ErrNotFound:            "resource not found",
    ErrUnauthorized:        "unauthorized access",
    ErrForbidden:           "forbidden",
    ErrInternal:            "internal server error",
    ErrTimeout:             "request timeout",
    ErrConflict:            "resource conflict",
    ErrRateLimit:           "rate limit exceeded",
    ErrServiceUnavailable:  "service unavailable",

    // 用户模块
    ErrUserNotFound:        "user not found",
    ErrUserPassword:        "incorrect password",
    ErrUserDisabled:        "user account disabled",
    ErrUserDuplicate:       "user already exists",
    ErrUserTokenExpired:    "token expired",

    // 订单模块
    ErrOrderNotFound:       "order not found",
    ErrOrderStatus:         "invalid order status",
    ErrOrderAmount:         "invalid order amount",
    ErrOrderTimeout:        "order timeout",
    ErrOrderDuplicate:      "duplicate order",
}

// Msg 根据错误码获取消息
func Msg(code int) string {
    if msg, ok := CodeMsgMap[code]; ok {
        return msg
    }
    return "unknown error code"
}

4.4 错误码常量定义与消息绑定的整体架构

下面的 SVG 图展示了从 iota 常量定义到分组、再到消息绑定的完整数据流，以及错误码在接口契约中的角色。

4.5 最佳实践与常见陷阱

• 始终从非零值开始：使用 1000 + iota 而非直接 iota，避免与 Go 的零值混淆，同时为扩展预留空间。
• 分组区间留有余量：每个模块分配 1000 个码位，即使当前只用到 10 个，也为未来扩展预留了空间。
• 消息国际化：如果项目需要多语言，可以将 CodeMsgMap 扩展为 map[int]map[string]string，第一层 key 为语言代码。
• 避免硬编码：在业务代码中始终使用常量名（如 errcode.ErrInvalidParam），不要直接写数字 1001。
• 错误码不可变：一旦发布，错误码的数字值不应修改或删除，只能废弃（deprecated）。否则会导致客户端旧版本解析错误。