4、错误码枚举：使用 iota 定义错误码常量，建立错误码与错误类型的映射关系

在 Go 语言中，错误码的枚举是构建可搜索、可断言错误体系的第一步。使用 iota 定义错误码常量，能够保证枚举值的唯一性与可维护性；而建立错误码与错误类型的映射关系，则是实现“错误码断言”的核心桥梁。本节将深入讲解如何通过 iota 定义结构化的错误码枚举，并构建双向映射表。

4.1 为什么选择 iota 定义错误码

iota 是 Go 语言中用于常量生成器的预定义标识符，在 const 块中每出现一次，其值自动递增 1。使用 iota 定义错误码具有以下优势：

• 自动递增：避免手动编号带来的重复或遗漏风险。
• 类型安全：通过自定义类型（如 type ErrCode int）限制错误码的使用范围。
• 可读性强：常量名称直接表达错误含义，无需查阅文档。
• 易于扩展：在已有枚举中插入新错误码时，只需调整 iota 的起始位置或使用占位符。

4.2 使用 iota 定义错误码枚举

以下示例展示了一个典型的错误码枚举定义，涵盖常见业务场景：

// errcode/errcode.go
package errcode

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

// 预定义错误码常量
const (
    // 通用错误码
    ErrCodeOK          ErrCode = iota // 0: 成功
    ErrCodeUnknown                    // 1: 未知错误
    ErrCodeInternal                   // 2: 内部错误
    ErrCodeBadRequest                 // 3: 请求参数错误
    ErrCodeUnauthorized               // 4: 未授权
    ErrCodeForbidden                  // 5: 禁止访问
    ErrCodeNotFound                   // 6: 资源不存在
    ErrCodeConflict                   // 7: 资源冲突
    ErrCodeTooManyRequests            // 8: 请求过于频繁

    // 业务错误码（从 100 开始）
    ErrCodeUserNotFound   ErrCode = iota + 100 // 100: 用户不存在
    ErrCodeUserDisabled                        // 101: 用户已禁用
    ErrCodeUserAlreadyExists                   // 102: 用户已存在
    ErrCodePasswordIncorrect                   // 103: 密码错误

    // 订单业务错误码（从 200 开始）
    ErrCodeOrderNotFound   ErrCode = iota + 200 // 200: 订单不存在
    ErrCodeOrderExpired                         // 201: 订单已过期
    ErrCodeOrderAlreadyPaid                     // 202: 订单已支付
    ErrCodeOrderStatusInvalid                   // 203: 订单状态无效
)

4.3 建立错误码与错误类型的映射关系

仅有错误码常量还不够，我们需要建立从 ErrCode 到 error 类型的双向映射，以便在断言时能够根据错误码快速定位错误类型，或根据错误类型获取对应的错误码。

4.3.1 定义错误类型结构

// errcode/errcode.go (续)
// Error 定义携带错误码的错误类型
type Error struct {
    Code    ErrCode
    Message string
}

// Error 实现 error 接口
func (e *Error) Error() string {
    return fmt.Sprintf("code=%d, message=%s", e.Code, e.Message)
}

// Code 返回错误码
func (e *Error) Code() ErrCode {
    return e.Code
}

4.3.2 构建映射表

// errcode/mapping.go
package errcode

import "sync"

var (
    // codeToError 存储 ErrCode 到 *Error 的映射
    codeToError = make(map[ErrCode]*Error)
    // errorToCode 存储 error 类型到 ErrCode 的映射（通过类型断言）
    mu          sync.RWMutex
)

// Register 注册错误码与错误类型的映射关系
func Register(code ErrCode, message string) {
    mu.Lock()
    defer mu.Unlock()
    if _, exists := codeToError[code]; exists {
        panic("errcode: duplicate registration for code " + string(rune(code)))
    }
    codeToError[code] = &Error{Code: code, Message: message}
}

// GetError 根据错误码获取对应的 Error 实例
func GetError(code ErrCode) *Error {
    mu.RLock()
    defer mu.RUnlock()
    return codeToError[code]
}

// GetCode 从 error 中提取 ErrCode，若无法提取则返回 ErrCodeUnknown
func GetCode(err error) ErrCode {
    if e, ok := err.(*Error); ok {
        return e.Code
    }
    return ErrCodeUnknown
}

// init 函数自动注册所有预定义错误码
func init() {
    Register(ErrCodeOK, "success")
    Register(ErrCodeUnknown, "unknown error")
    Register(ErrCodeInternal, "internal error")
    Register(ErrCodeBadRequest, "bad request")
    Register(ErrCodeUnauthorized, "unauthorized")
    Register(ErrCodeForbidden, "forbidden")
    Register(ErrCodeNotFound, "not found")
    Register(ErrCodeConflict, "conflict")
    Register(ErrCodeTooManyRequests, "too many requests")
    Register(ErrCodeUserNotFound, "user not found")
    Register(ErrCodeUserDisabled, "user disabled")
    Register(ErrCodeUserAlreadyExists, "user already exists")
    Register(ErrCodePasswordIncorrect, "password incorrect")
    Register(ErrCodeOrderNotFound, "order not found")
    Register(ErrCodeOrderExpired, "order expired")
    Register(ErrCodeOrderAlreadyPaid, "order already paid")
    Register(ErrCodeOrderStatusInvalid, "order status invalid")
}

4.4 错误码与错误类型映射关系图

下图展示了错误码枚举、错误类型结构以及双向映射表的整体架构：

4.5 使用映射表进行错误断言

建立映射关系后，在测试或业务代码中即可通过错误码进行精确断言：

// example_test.go
package errcode_test

import (
    "testing"
    "yourmodule/errcode"
)

func TestErrorCodeAssertion(t *testing.T) {
    // 模拟返回的错误
    err := someBusinessFunction()
    
    // 方式一：通过错误码直接断言
    if errcode.GetCode(err) != errcode.ErrCodeUserNotFound {
        t.Errorf("expected error code %d, got %d", errcode.ErrCodeUserNotFound, errcode.GetCode(err))
    }
    
    // 方式二：通过错误类型断言
    if e, ok := err.(*errcode.Error); ok {
        if e.Code != errcode.ErrCodeUserNotFound {
            t.Errorf("expected code %d, got %d", errcode.ErrCodeUserNotFound, e.Code)
        }
        if e.Message != "user not found" {
            t.Errorf("expected message 'user not found', got '%s'", e.Message)
        }
    } else {
        t.Error("error is not of type *errcode.Error")
    }
}

func someBusinessFunction() error {
    // 模拟返回一个带错误码的错误
    return errcode.GetError(errcode.ErrCodeUserNotFound)
}

4.6 错误码枚举设计原则