📚 课程目录第3章 Go错误码枚举实现

3. Go 错误码枚举实现：iota 常量定义、错误码结构体、错误码与 error 接口绑定

在分布式系统的错误传播与断言回滚场景中，错误码是核心的契约载体。Go 语言通过 iota 枚举常量、结构化错误码类型以及 error 接口绑定，提供了一套类型安全、可序列化且可断言的设计范式。本节将逐步拆解这一实现路径。

3.1 基于 iota 的错误码常量定义

iota 是 Go 预定义的常量计数器，在 const 块中每新增一行自动递增 1。使用 iota 定义错误码可以避免硬编码数字，保证枚举值的唯一性与可维护性。

  设计原则： 错误码应分为通用系统级（如 1000-1999）与业务级（如 2000-2999），通过 iota 偏移量隔离。

package errcode

// 系统级错误码：1000-1999
const (
    ErrSuccess       uint32 = 1000 + iota // 1000
    ErrUnknown                            // 1001
    ErrInvalidParams                      // 1002
    ErrUnauthorized                       // 1003
    ErrNotFound                           // 1004
    ErrTimeout                            // 1005
    ErrInternal                           // 1006
)

// 业务级错误码：2000-2999
const (
    ErrOrderNotExist    uint32 = 2000 + iota // 2000
    ErrOrderAlreadyPaid                      // 2001
    ErrInsufficientStock                     // 2002
    ErrPaymentFailed                         // 2003
    ErrRollbackConflict                      // 2004
)

常量名	数值	分类	说明
`ErrSuccess`	1000	系统级	成功，无错误
`ErrInvalidParams`	1002	系统级	请求参数校验失败
`ErrOrderNotExist`	2000	业务级	订单不存在
`ErrRollbackConflict`	2004	业务级	回滚版本冲突

iota 避坑： 若在 const 块中插入非 iota 表达式（如 _ = iota），计数器仍会递增，务必保持行号与数值的对应关系。

3.2 错误码结构体设计

仅靠 uint32 无法携带上下文信息。定义一个 ErrorCode 结构体，将数值、消息、HTTP 状态码和可选的扩展字段封装在一起，便于序列化与日志追踪。

// ErrorCode 结构化错误码
type ErrorCode struct {
    Code    uint32 `json:"code"`              // 错误码数值
    Message string `json:"message"`           // 人类可读消息
    HTTP    int    `json:"http,omitempty"`    // 建议的 HTTP 状态码
    Ext     string `json:"ext,omitempty"`     // 扩展追踪信息
}

// 预定义错误码实例
var (
    Success       = &ErrorCode{Code: ErrSuccess, Message: "success", HTTP: 200}
    InvalidParams = &ErrorCode{Code: ErrInvalidParams, Message: "invalid parameters", HTTP: 400}
    NotFound      = &ErrorCode{Code: ErrNotFound, Message: "resource not found", HTTP: 404}
    Internal      = &ErrorCode{Code: ErrInternal, Message: "internal server error", HTTP: 500}
)

字段	类型	用途
`Code`	uint32	唯一错误码，用于断言与比较
`Message`	string	面向开发者的错误描述
`HTTP`	int	映射到 HTTP 响应状态码
`Ext`	string	可选的追踪 ID 或调试上下文

3.3 错误码与 error 接口绑定

Go 标准库的 error 接口只要求实现 Error() string 方法。让 ErrorCode 实现该接口，即可将结构化错误码无缝融入 Go 的错误处理链，同时保留断言能力。

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

// 使用示例
func ProcessOrder(orderID string) error {
    if orderID == "" {
        return InvalidParams
    }
    // 模拟业务错误
    return &ErrorCode{
        Code:    ErrOrderNotExist,
        Message: "order not found",
        HTTP:    404,
        Ext:     "trace-abc-123",
    }
}

// 调用方断言
err := ProcessOrder("")
if ec, ok := err.(*ErrorCode); ok {
    switch ec.Code {
    case ErrInvalidParams:
        // 参数错误处理
    case ErrOrderNotExist:
        // 订单不存在处理
    }
}

断言陷阱： 使用类型断言 err.(*ErrorCode) 时，若 error 被多层包装（如 fmt.Errorf("wrap: %w", err)），断言会失败。此时应使用 errors.As 进行递归解包。

3.4 错误码体系架构图

下图展示了从 iota 常量定义到 error 接口绑定的完整链路，以及断言回滚场景中的调用关系。

3.5 完整实现与断言示例

将上述三个步骤整合为一个可复用的错误码包，并展示在发布回滚场景中的断言用法。

package errcode

import "fmt"

// 1. iota 常量
const (
    ErrSuccess       uint32 = 1000 + iota
    ErrUnknown
    ErrInvalidParams
    ErrRollbackConflict = 2004
)

// 2. 结构体
type ErrorCode struct {
    Code    uint32 `json:"code"`
    Message string `json:"message"`
    HTTP    int    `json:"http,omitempty"`
    Ext     string `json:"ext,omitempty"`
}

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

// 预定义实例
var (
    Success         = &ErrorCode{Code: ErrSuccess, Message: "success", HTTP: 200}
    InvalidParams   = &ErrorCode{Code: ErrInvalidParams, Message: "invalid params", HTTP: 400}
    RollbackConflict = &ErrorCode{Code: ErrRollbackConflict, Message: "rollback version conflict", HTTP: 409}
)

// 断言辅助函数
func IsErrorCode(err error, code uint32) bool {
    var ec *ErrorCode
    if errors.As(err, &ec) {
        return ec.Code == code
    }
    return false
}

  实战建议： 在微服务间传递错误码时，将 ErrorCode 序列化为 JSON 放入 gRPC 的 trailing metadata 或 HTTP 响应头，接收方反序列化后使用 errors.As 断言，实现跨服务错误码传播。

3.6 错误码与 error 接口绑定的两种模式对比

模式	实现方式	断言方式	适用场景
直接类型断言	`err.(*ErrorCode)`	仅一层包装时有效	内部函数调用，无额外包装
`errors.As` 递归解包	`errors.As(err, &ec)`	支持多层 `%w` 包装	跨层调用、中间件包装错误

通过 iota 常量、结构化错误码与 error 接口的三层设计，Go 项目可以获得类型安全、可序列化且易于断言的错误码体系，为后续的搜索断言与发布回滚奠定坚实的契约基础。