4. 自定义错误类型：结构体实现 error 接口、携带额外上下文信息、错误码与错误消息分离

Go 语言内置的 error 接口只要求实现一个 Error() string 方法。对于业务系统而言，仅靠一个字符串远远不够——我们需要区分“错误是什么”（错误码）和“错误的描述是什么”（错误消息），还需要携带请求 ID、用户 ID、堆栈等上下文信息。本章将用结构体实现自定义错误类型，完成错误码与错误消息的彻底分离。

4.1 为什么需要自定义错误类型？

内置 errors.New 和 fmt.Errorf 只能返回一个字符串，无法满足以下业务需求：

4.2 结构体实现 error 接口

任何类型只要实现了 Error() string 方法，就满足了 error 接口。我们定义一个 BizError 结构体，包含错误码和错误消息两个核心字段：

// BizError 业务错误类型
type BizError struct {
    Code    int    // 错误码，例如 1001、1002
    Message string // 错误消息，例如 "用户不存在"
}

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

使用方式：

func GetUser(id int) (*User, error) {
    if id <= 0 {
        return nil, &BizError{
            Code:    1001,
            Message: "用户ID不合法",
        }
    }
    // ... 正常逻辑
    return &User{ID: id, Name: "Alice"}, nil
}

调用方可以通过类型断言获取错误码：

user, err := GetUser(-1)
if err != nil {
    var bizErr *BizError
    if errors.As(err, &bizErr) {
        fmt.Printf("错误码: %d\n", bizErr.Code)   // 输出: 错误码: 1001
        fmt.Printf("错误消息: %s\n", bizErr.Message) // 输出: 错误消息: 用户ID不合法
    }
}

4.3 携带额外上下文信息

实际业务中，我们往往需要更多上下文来定位问题。在 BizError 中增加可选字段：

// BizError 增强版：携带上下文信息
type BizError struct {
    Code       int
    Message    string
    RequestID  string            // 请求追踪ID
    UserID     int64             // 触发错误的用户ID
    Details    map[string]string // 额外键值对，用于调试
    Timestamp  time.Time         // 错误发生时间
    StackTrace string            // 堆栈信息（可选）
}

func (e *BizError) Error() string {
    return fmt.Sprintf("code=%d, message=%s, request_id=%s, user_id=%d",
        e.Code, e.Message, e.RequestID, e.UserID)
}

// WithDetail 链式添加额外信息
func (e *BizError) WithDetail(key, value string) *BizError {
    if e.Details == nil {
        e.Details = make(map[string]string)
    }
    e.Details[key] = value
    return e
}

4.4 错误码与错误消息分离的设计模式

将错误码定义为中心常量，错误消息可以动态生成或从配置读取：

// 错误码常量定义
const (
    ErrCodeSuccess       = 0
    ErrCodeUserNotFound  = 1001
    ErrCodeUserDisabled  = 1002
    ErrCodeInvalidParams = 2001
    ErrCodeInternalError = 5000
)

// 错误消息映射（可替换为国际化版本）
var defaultMessages = map[int]string{
    ErrCodeUserNotFound:  "用户不存在",
    ErrCodeUserDisabled:  "用户已被禁用",
    ErrCodeInvalidParams: "请求参数无效",
    ErrCodeInternalError: "服务器内部错误",
}

// NewBizError 根据错误码创建错误，自动填充消息
func NewBizError(code int) *BizError {
    msg, ok := defaultMessages[code]
    if !ok {
        msg = "未知错误"
    }
    return &BizError{
        Code:      code,
        Message:   msg,
        Timestamp: time.Now(),
    }
}

// NewBizErrorWithMsg 允许覆盖默认消息
func NewBizErrorWithMsg(code int, message string) *BizError {
    return &BizError{
        Code:      code,
        Message:   message,
        Timestamp: time.Now(),
    }
}

使用示例：

// 使用预定义错误码
return nil, NewBizError(ErrCodeUserNotFound)

// 覆盖默认消息（例如携带动态参数）
return nil, NewBizErrorWithMsg(ErrCodeUserNotFound,
    fmt.Sprintf("用户 %d 不存在", userID))

4.5 结构体错误类型的关系图

下图展示了自定义错误类型的核心结构及其与 error 接口、调用方的关系：

4.6 错误码与错误消息分离的流程

下图展示了从错误发生到错误码/消息分离处理的完整流程：

4.7 常见陷阱与最佳实践

• 陷阱1：在 Error() 方法中拼接大量上下文。 这会导致日志行过长，且无法结构化解析。Error() 只输出关键标识，完整上下文通过结构体字段暴露。
• 陷阱2：错误码使用字符串而非整数。 字符串比较性能差，且容易拼写错误。推荐使用整数常量，配合 iota 或显式赋值。
• 陷阱3：错误消息硬编码在业务逻辑中。 应该统一管理错误消息，支持国际化替换。
• 最佳实践： 为 BizError 实现 Unwrap() 方法，使其兼容 Go 1.13+ 的错误链机制。

// Unwrap 支持错误链
func (e *BizError) Unwrap() error {
    return nil // 如果没有包装其他错误，返回 nil
}

// 如果需要包装底层错误，可以增加 Err 字段
type BizError struct {
    Code    int
    Message string
    Err     error // 原始错误
}

func (e *BizError) Unwrap() error {
    return e.Err
}

4.8 本章小结

通过结构体实现 error 接口，我们完成了从“字符串错误”到“结构化错误”的升级：