4、定义错误码常量：使用 iota 定义错误码、错误码命名规范、错误码与错误消息映射

在 Go 语言中，错误码常量的定义是构建可维护、可搜索错误体系的第一步。本章将系统讲解如何利用 iota 枚举器高效定义错误码、遵循行业命名规范，并建立错误码与错误消息的清晰映射关系。

4.1 使用 iota 定义错误码

Go 语言没有内置的枚举类型，但通过 iota 配合常量块可以优雅地实现自增错误码。这种方式不仅减少手动赋值错误，还能在新增错误码时自动保持连续性。

package errcode

// ErrorCode 定义错误码类型
type ErrorCode uint32

const (
    // 通用错误码：0 表示成功
    Success ErrorCode = 0

    // 系统级错误码：1-99
    ErrUnknown      ErrorCode = iota + 1  // 1
    ErrInternal                            // 2
    ErrDatabase                            // 3
    ErrNetwork                             // 4
    ErrTimeout                             // 5

    // 参数校验错误码：100-199
    ErrInvalidParam   ErrorCode = iota + 100 // 100
    ErrMissingParam                          // 101
    ErrParamFormat                           // 102
    ErrParamOutOfRange                       // 103

    // 业务逻辑错误码：200-299
    ErrNotFound       ErrorCode = iota + 200 // 200
    ErrAlreadyExists                         // 201
    ErrPermissionDenied                      // 202
    ErrResourceExhausted                     // 203
    ErrStateConflict                         // 204
)

4.2 错误码命名规范

良好的命名规范能显著提升代码可读性和团队协作效率。推荐遵循以下 Go 社区通用规范：

• 前缀统一：所有错误码常量以 Err 开头，如 ErrNotFound、ErrInvalidParam。
• 驼峰命名：使用 PascalCase（大驼峰）风格，每个单词首字母大写。
• 语义清晰：名称应准确描述错误原因，避免模糊词汇如 ErrError、ErrFail。
• 分类分组：同一类别的错误码在常量块中连续排列，并用空行分隔不同分类。
• 避免缩写：除非是广泛接受的缩写（如 Param、Config），否则使用完整单词。

4.3 错误码与错误消息映射

错误码是机器可读的标识，而错误消息是面向开发者的可读描述。建立稳定的映射关系是错误码断言的核心基础。

4.3.1 映射表结构

// codeMessageMap 存储错误码到错误消息的映射
var codeMessageMap = map[ErrorCode]string{
    Success:             "success",
    ErrUnknown:          "unknown error",
    ErrInternal:         "internal server error",
    ErrDatabase:         "database operation failed",
    ErrNetwork:          "network communication error",
    ErrTimeout:          "request timeout",
    ErrInvalidParam:     "invalid parameter",
    ErrMissingParam:     "missing required parameter",
    ErrParamFormat:      "parameter format error",
    ErrParamOutOfRange:  "parameter out of range",
    ErrNotFound:         "resource not found",
    ErrAlreadyExists:    "resource already exists",
    ErrPermissionDenied: "permission denied",
    ErrResourceExhausted:"resource exhausted",
    ErrStateConflict:    "state conflict",
}

// Message 根据错误码返回对应的错误消息
func (e ErrorCode) Message() string {
    if msg, ok := codeMessageMap[e]; ok {
        return msg
    }
    return "unknown error code"
}

4.3.2 映射设计原则

4.4 错误码体系结构总览

下图展示了错误码从定义到映射的完整体系结构，帮助理解各组件之间的关系：

4.5 完整示例：集成定义与映射

以下代码展示了如何将错误码定义、命名规范与消息映射整合到一个包中，形成可复用的错误码模块：

package errcode

import "fmt"

// ErrorCode 错误码类型
type ErrorCode uint32

// 预定义错误码
const (
    Success ErrorCode = 0

    // 系统错误 (1-99)
    ErrSystem     ErrorCode = iota + 1
    ErrConfig
    ErrIO

    // 参数错误 (100-199)
    ErrParam      ErrorCode = iota + 100
    ErrParamType
    ErrParamRange

    // 业务错误 (200-299)
    ErrBiz        ErrorCode = iota + 200
    ErrBizState
    ErrBizLimit
)

// messageMap 错误码消息映射
var messageMap = map[ErrorCode]string{
    Success:      "success",
    ErrSystem:    "system error",
    ErrConfig:    "configuration error",
    ErrIO:        "I/O operation error",
    ErrParam:     "parameter error",
    ErrParamType: "parameter type mismatch",
    ErrParamRange:"parameter out of valid range",
    ErrBiz:       "business logic error",
    ErrBizState:  "invalid business state",
    ErrBizLimit:  "business limit exceeded",
}

// Message 返回错误码对应的消息
func (e ErrorCode) Message() string {
    if msg, ok := messageMap[e]; ok {
        return msg
    }
    return fmt.Sprintf("unknown error code: %d", e)
}

// String 实现 Stringer 接口
func (e ErrorCode) String() string {
    return fmt.Sprintf("[%d] %s", e, e.Message())
}

通过以上设计，错误码体系具备了良好的可扩展性、可读性和可测试性，为后续的“搜索错误码断言”奠定了坚实基础。