📚 课程目录第4章定义错误码常量

4. 定义错误码常量：使用 iota 定义错误码、错误码命名规范、错误码注释

在 Go 语言中，错误码常量的定义是错误码断言体系的基础。使用 iota 枚举器可以高效、可维护地生成一组递增的错误码值，同时配合清晰的命名规范和注释，能够显著提升代码的可读性和团队协作效率。本节将系统讲解这三部分内容。

4.1 使用 iota 定义错误码

iota 是 Go 语言中用于常量生成器的预定义标识符，它在 const 声明块中每行自动递增，初始值为 0。利用 iota 定义错误码，可以避免手动编号带来的重复、遗漏或冲突问题。

基本用法示例：

package errcode

// 定义错误码类型，增强类型安全
type ErrCode int

// 错误码常量块
const (
    ErrSuccess       ErrCode = iota // 0 - 成功
    ErrInvalidParam                 // 1 - 无效参数
    ErrNotFound                     // 2 - 未找到
    ErrUnauthorized                 // 3 - 未授权
    ErrForbidden                    // 4 - 禁止访问
    ErrInternal                     // 5 - 内部错误
)

最佳实践：始终为错误码定义独立的类型（如 type ErrCode int），而不是直接使用 int。这可以防止错误码与其他整型值混用，在编译期提供类型安全检查。

当需要跳过某些值或使用自定义起始值时，可以结合空白标识符 _ 和算术表达式：

const (
    ErrCodeStart ErrCode = iota + 1000 // 从 1000 开始
    ErrUserNotFound                    // 1001
    ErrUserExists                      // 1002
    _
    ErrPasswordWrong                   // 1004（跳过了 1003）
    ErrTokenExpired                    // 1005
)

4.2 错误码命名规范

良好的命名规范能让错误码自文档化，降低理解成本。以下是推荐的命名规则：

规范维度	推荐做法	示例	反例
前缀	统一使用 `Err` 前缀，表示这是一个错误码	`ErrNotFound`	`NotFound`、`ErrorNotFound`
语义	使用名词或形容词短语，清晰描述错误场景	`ErrUserNotFound`	`ErrBad`、`ErrFail`
大小写	驼峰命名（PascalCase），首字母大写	`ErrInvalidParam`	`err_invalid_param`、`Err_invalidParam`
层级	模块前缀 + 具体错误，用驼峰分隔	`ErrDBConnectionTimeout`	`ErrTimeout`（过于模糊）
长度	适中，通常 2~4 个单词，避免过长	`ErrRateLimitExceeded`	`ErrTheRateLimitForThisAPIHasBeenExceeded`

注意：避免使用数字后缀（如 Err1、Err2）或过于通用的名称（如 ErrError、ErrUnknown）。错误码名称应当让读者一眼就能理解发生了什么问题。

4.3 错误码注释规范

Go 语言中，常量注释遵循与函数、类型相同的文档注释规则。每个错误码常量上方应包含一行或多行注释，说明其含义、触发条件以及可能的处理建议。

注释格式要求：

单行注释：以常量名开头，后跟描述。
多行注释：第一行概述，后续行补充细节。
包含数值：在注释中标注错误码的整数值，方便查阅。

// ErrSuccess 表示操作成功完成，错误码为 0。
// 该错误码通常用于断言检查通过时的返回值。
ErrSuccess ErrCode = iota

// ErrInvalidParam 表示请求参数校验失败，错误码为 1。
// 触发条件：参数缺失、格式错误或超出范围。
// 处理建议：客户端应检查参数后重试。
ErrInvalidParam

// ErrNotFound 表示请求的资源不存在，错误码为 2。
// 触发条件：数据库查询无结果或路径不存在。
ErrNotFound

  团队约定：建议在注释中统一包含三要素——含义（What）、触发条件（When）、处理建议（How）。这能让错误码成为可执行的文档，减少排查问题时的沟通成本。

4.4 错误码定义流程与结构

下图展示了从需求分析到最终定义错误码常量的完整流程：

4.5 完整示例：业务模块错误码定义

以下是一个用户服务模块的错误码定义示例，综合运用了 iota、命名规范和注释规范：

package user

// ErrCode 用户模块错误码类型
type ErrCode int

const (
    // ErrSuccess 操作成功完成（0）
    ErrSuccess ErrCode = iota

    // ErrUserNotFound 用户不存在（1）
    // 触发条件：根据用户 ID 或邮箱查询时无结果
    ErrUserNotFound

    // ErrUserAlreadyExists 用户已存在（2）
    // 触发条件：注册时邮箱或用户名已被占用
    ErrUserAlreadyExists

    // ErrPasswordIncorrect 密码错误（3）
    // 触发条件：登录时密码校验失败
    ErrPasswordIncorrect

    // ErrAccountLocked 账户已被锁定（4）
    // 触发条件：连续多次密码错误后账户被临时锁定
    ErrAccountLocked

    // ErrTokenExpired 令牌已过期（5）
    // 处理建议：客户端应刷新令牌后重试
    ErrTokenExpired
)

扩展建议：当项目包含多个模块时，可以为每个模块定义独立的错误码常量文件（如 user/errcode.go、order/errcode.go），并在模块内部使用不同的起始偏移量（如用户模块从 1000 开始，订单模块从 2000 开始），避免跨模块错误码冲突。

4.6 错误码命名与注释对比

下表总结了优秀与不良的错误码定义风格对比：

维度	优秀示例	不良示例	改进方向
命名	`ErrDBConnectionTimeout`	`ErrTime`	增加模块前缀和具体场景
注释	`// ErrDBConnectionTimeout 数据库连接超时，错误码 1003。触发条件：数据库响应超过 5 秒。`	`// 超时错误`	补充触发条件和错误码值
类型	`type ErrCode int`	直接使用 `int`	定义独立类型增强类型安全
分组	按模块分文件定义	所有错误码放在一个文件	按业务模块拆分，降低耦合

通过本节的学习，你已经掌握了使用 iota 定义错误码、遵循命名规范以及编写高质量注释的方法。这些基础工作将为后续实现错误码断言函数和断言链打下坚实的地基。