3. 自定义错误类型：实现 Error 接口、携带错误码与上下文信息的结构体错误、错误链的构建

在 Go 语言中，error 是一个内置接口，只要求实现一个 Error() string 方法。标准库的 errors.New 和 fmt.Errorf 只能传递简单的字符串消息，无法携带错误码、结构化上下文或构建错误链。在生产级权限验证与错误码断言场景中，必须自定义错误类型来满足以下需求：

• 携带业务错误码：让调用方能够通过错误码做断言，而不是解析字符串。
• 携带上下文信息：附加请求 ID、用户 ID、资源路径等结构化字段，便于日志聚合与链路追踪。
• 构建错误链：保留原始错误的堆栈与类型，支持 errors.Is 和 errors.As 进行断言。

3.1 实现 Error 接口的结构体错误

自定义错误类型本质上是一个结构体，实现了 Error() string 方法。以下是一个携带错误码和上下文信息的基础实现：

// ErrCode 定义业务错误码类型
type ErrCode int

const (
    ErrCodeUnknown      ErrCode = 0
    ErrCodeUnauthorized ErrCode = 1001
    ErrCodeForbidden    ErrCode = 1003
    ErrCodeNotFound     ErrCode = 1004
)

// AppError 自定义应用错误
type AppError struct {
    Code    ErrCode              // 业务错误码
    Message string               // 人类可读消息
    Context map[string]interface{} // 上下文信息
    Err     error                // 包装的原始错误（用于错误链）
}

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

// Unwrap 返回被包装的错误，支持 errors.Is/As 遍历
func (e *AppError) Unwrap() error {
    return e.Err
}

3.2 错误码断言与上下文提取

自定义错误类型的核心优势在于：调用方可以通过类型断言或 errors.As 直接获取错误码和上下文，无需解析字符串。

// 模拟一个返回 AppError 的函数
func verifyPermission(userID string, resource string) error {
    if userID == "" {
        return &AppError{
            Code:    ErrCodeUnauthorized,
            Message: "用户未认证",
            Context: map[string]interface{}{
                "resource": resource,
                "reason":   "missing_user_id",
            },
        }
    }
    // 其他逻辑...
    return nil
}

// 调用方进行错误码断言
err := verifyPermission("", "/api/v1/orders")
var appErr *AppError
if errors.As(err, &appErr) {
    switch appErr.Code {
    case ErrCodeUnauthorized:
        fmt.Printf("未授权访问，资源: %v\n", appErr.Context["resource"])
        // 返回 HTTP 401
    case ErrCodeForbidden:
        fmt.Printf("权限不足，原因: %v\n", appErr.Context["reason"])
        // 返回 HTTP 403
    }
}

3.3 错误链的构建与遍历

错误链允许一个错误包装另一个错误，保留完整的错误历史。Go 1.13 引入的 errors.Is 和 errors.As 可以递归遍历错误链。以下展示如何构建多层错误链：

// 底层错误：数据库查询失败
dbErr := &AppError{
    Code:    ErrCodeNotFound,
    Message: "用户记录不存在",
    Context: map[string]interface{}{"user_id": 123},
}

// 中层错误：业务逻辑层包装
bizErr := &AppError{
    Code:    ErrCodeForbidden,
    Message: "无权访问该用户资料",
    Context: map[string]interface{}{"operator": "admin"},
    Err:     dbErr,  // 包装底层错误
}

// 顶层错误：API 层再次包装
apiErr := &AppError{
    Code:    ErrCodeUnauthorized,
    Message: "请求被拒绝",
    Context: map[string]interface{}{"request_id": "req-abc"},
    Err:     bizErr,
}

// 使用 errors.Is 检查链中是否包含特定错误码
targetErr := &AppError{Code: ErrCodeNotFound}
if errors.Is(apiErr, targetErr) {
    fmt.Println("错误链中包含 ErrCodeNotFound")
}

// 使用 errors.As 提取链中任意层级的 AppError
var found *AppError
if errors.As(apiErr, &found) {
    fmt.Printf("提取到错误码: %d, 上下文: %v\n", found.Code, found.Context)
}

3.4 自定义错误类型对比表

3.5 错误链构建与断言流程

3.6 完整示例：权限验证中的错误链实战

以下代码展示了一个完整的权限验证场景，使用自定义错误类型构建错误链并进行断言：

// 定义错误码
const (
    ErrTokenInvalid   ErrCode = 2001
    ErrTokenExpired   ErrCode = 2002
    ErrRoleInsufficient ErrCode = 2003
)

// TokenValidate 验证令牌
func TokenValidate(token string) error {
    if token == "" {
        return &AppError{
            Code:    ErrTokenInvalid,
            Message: "令牌为空",
            Context: map[string]interface{}{"token": token},
        }
    }
    // 模拟令牌过期
    return &AppError{
        Code:    ErrTokenExpired,
        Message: "令牌已过期",
        Context: map[string]interface{}{"expired_at": "2025-01-01"},
    }
}

// RoleCheck 检查角色权限
func RoleCheck(userID string, requiredRole string) error {
    // 先验证令牌
    tokenErr := TokenValidate("expired_token")
    if tokenErr != nil {
        return &AppError{
            Code:    ErrRoleInsufficient,
            Message: "角色检查失败",
            Context: map[string]interface{}{"user_id": userID, "required_role": requiredRole},
            Err:     tokenErr,  // 包装令牌错误
        }
    }
    return nil
}

// APIHandler 模拟 API 处理函数
func APIHandler(userID string) error {
    err := RoleCheck(userID, "admin")
    if err != nil {
        // 断言：检查是否是令牌过期导致的权限不足
        var tokenExpired *AppError
        if errors.As(err, &tokenExpired) && tokenExpired.Code == ErrTokenExpired {
            return &AppError{
                Code:    ErrTokenExpired,
                Message: "请重新登录",
                Context: map[string]interface{}{"action": "refresh_token"},
                Err:     err,
            }
        }
        return err
    }
    return nil
}

// 使用示例
func main() {
    err := APIHandler("user_001")
    var appErr *AppError
    if errors.As(err, &appErr) {
        fmt.Printf("最终错误码: %d\n", appErr.Code)
        fmt.Printf("上下文: %v\n", appErr.Context)
        // 输出: 最终错误码: 2002
        // 输出: 上下文: map[action:refresh_token]
    }
}

3.7 自定义错误类型结构总览

3.8 避坑指南

• 不要用字符串拼接代替错误码：字符串解析脆弱且性能差，始终使用强类型错误码。
• 避免在 Context 中放入敏感信息：如密码、密钥等，Context 可能被日志系统输出。
• Unwrap 返回 nil 时：表示当前错误是链的末端，errors.Is 和 errors.As 会停止遍历。
• 实现 Is 方法时：确保按错误码比较，而不是按指针比较，否则包装后的错误无法匹配。
• 不要忽略 Unwrap 方法：没有 Unwrap，错误链无法被标准库遍历，断言会失效。