4. 错误码常量定义：使用 iota 枚举错误码、分组管理、避免重复

在 Go 语言项目中，错误码的常量定义是权限验证与错误断言的基础。使用 iota 枚举器可以自动递增生成错误码，结合分组管理能有效避免重复，提升代码的可维护性与可读性。本节将深入讲解如何利用 iota 定义结构清晰的错误码体系。

4.1 为什么需要 iota 枚举错误码

手动定义错误码常量容易导致以下问题：

• 重复值：多人协作时，不同模块可能定义相同的错误码，造成断言混乱。
• 维护困难：新增错误码需要手动调整后续所有编号，容易遗漏。
• 可读性差：散落的常量缺乏分组，难以快速定位所属模块。

iota 是 Go 语言内置的常量生成器，在 const 块中每行自动递增，从 0 开始。通过合理设计，可以构建出既唯一又分层的错误码体系。

4.2 基础 iota 错误码定义

最简单的用法是在一个 const 块中定义一组连续的错误码：

package errcode

const (
    ErrSuccess       = 0
    ErrUnknown       = 1
    ErrInvalidParams = 2
    ErrNotFound      = 3
    ErrTimeout       = 4
)

但这种方式在项目规模扩大后，不同模块的错误码容易冲突。因此，需要引入分组管理。

4.3 分组管理：模块化错误码

通过为每个模块分配独立的 iota 起始值，可以实现错误码的分组隔离。常见做法是使用位运算或基数偏移。

模块	基数偏移	错误码范围	示例
通用	0	0 – 99	ErrSuccess = 0
用户模块	1000	1000 – 1099	ErrUserNotFound = 1001
权限模块	2000	2000 – 2099	ErrPermissionDenied = 2001
数据库模块	3000	3000 – 3099	ErrDBConnection = 3001

以下代码展示了如何使用 iota 结合基数偏移实现分组：

package errcode

// 通用错误码
const (
    ErrSuccess = 0 + iota
    ErrUnknown
    ErrInvalidParams
    ErrNotFound
    ErrTimeout
)

// 用户模块错误码
const (
    ErrUserBase = 1000 + iota
    ErrUserNotFound
    ErrUserAlreadyExists
    ErrUserPasswordIncorrect
)

// 权限模块错误码
const (
    ErrPermissionBase = 2000 + iota
    ErrPermissionDenied
    ErrPermissionExpired
    ErrPermissionInsufficient
)

4.4 避免重复：iota 的自动递增机制

iota 在同一个 const 块内自动递增，从根本上杜绝了同一分组内的重复值。但跨分组时，需要人工确保基数偏移不重叠。建议在项目初期制定错误码分配表，并写入项目文档。

以下是一个错误码冲突的示例与修正：

场景	错误定义	结果
冲突	ErrNotFound = 3 与 ErrUserNotFound = 3	断言时无法区分是通用未找到还是用户未找到
修正后	ErrNotFound = 3 与 ErrUserNotFound = 1001	通过基数偏移实现全局唯一

4.5 错误码分组结构图

下图展示了基于基数偏移的错误码分组架构：

4.6 进阶：使用位运算实现多级分组

对于大型项目，可以使用位运算将模块标识与错误序号编码到同一个整数中。例如，高 8 位表示模块 ID，低 8 位表示错误序号：

package errcode

const (
    ModuleMask = 0xFF00
    ErrorMask  = 0x00FF
)

// 模块 ID
const (
    ModuleCommon     = 0 << 8
    ModuleUser       = 1 << 8
    ModulePermission = 2 << 8
    ModuleDatabase   = 3 << 8
)

// 通用错误码
const (
    ErrSuccess = ModuleCommon + iota
    ErrUnknown
    ErrInvalidParams
)

// 用户模块错误码
const (
    ErrUserNotFound       = ModuleUser + iota
    ErrUserAlreadyExists
    ErrUserPasswordIncorrect
)

// 权限模块错误码
const (
    ErrPermissionDenied      = ModulePermission + iota
    ErrPermissionExpired
    ErrPermissionInsufficient
)

这种方式可以通过位运算快速提取模块 ID 和错误序号，适合需要按模块批量处理错误码的场景。

4.7 错误码定义避坑清单

• 不要使用 0 作为有效错误码：0 通常保留给 ErrSuccess，避免与零值混淆。
• 不要跨 const 块依赖 iota 顺序：每个 const 块的 iota 独立重置，不要假设跨块连续。
• 不要手动修改 iota 生成的编号：如需跳过某些值，使用 _ 占位符。
• 不要忽略错误码文档：每个错误码应附带注释说明触发条件和处理建议。

4.8 错误码定义流程

下图总结了从需求到实现的完整流程：

go generate 自动生成错误码文档和校验报告。

4.9 小结