4. 错误包装与解包：fmt.Errorf 与 %w、errors.Is 与 errors.As、错误链的遍历

在 Go 语言中，错误处理不仅仅是返回一个 error 接口值。当函数调用链变深时，底层错误需要携带上层上下文信息，同时保留原始错误的可识别性。Go 1.13 引入的错误包装（Error Wrapping）机制，通过 fmt.Errorf 配合 %w 动词、errors.Is 与 errors.As 函数，构建了一条可遍历的错误链。本章将深入剖析这一机制的原理与实战用法。

4.1 错误包装：fmt.Errorf 与 %w

传统的 fmt.Errorf 使用 %s 或 %v 只能将错误转为字符串，丢失了原始错误的类型和可比较性。Go 1.13 引入的 %w 动词，可以将一个 error 包装进新的错误中，形成一条错误链。

err := fmt.Errorf("操作失败: %w", originalErr)

包装 vs 非包装对比：

// 示例：包装 vs 非包装
package main

import (
    "errors"
    "fmt"
)

var ErrNotFound = errors.New("资源未找到")

func findResource(id int) error {
    return fmt.Errorf("查询失败: %w", ErrNotFound)
}

func main() {
    err := findResource(42)
    fmt.Println(err) // 输出: 查询失败: 资源未找到

    // 使用 errors.Is 检查
    if errors.Is(err, ErrNotFound) {
        fmt.Println("匹配到 ErrNotFound") // 会执行
    }
}

4.2 错误解包：errors.Unwrap 与错误链结构

errors.Unwrap 是解包的核心函数。如果错误实现了 Unwrap() error 方法，该函数会返回其包装的原始错误；否则返回 nil。Go 标准库中的 fmt.Errorf 使用 %w 时，自动生成一个实现了 Unwrap 方法的包装错误。

错误链的遍历逻辑：

1. 从最外层错误开始。
2. 调用 errors.Unwrap(err) 获取下一层错误。
3. 重复步骤 2，直到返回 nil 或找到目标错误。
4. 整个链条形成一个单向链表结构。

4.3 errors.Is：按值匹配错误链

errors.Is 用于检查错误链中是否包含某个特定的错误值（通常是哨兵错误）。它会沿着错误链逐层调用 Unwrap，并与目标错误进行比较（使用 == 或目标错误实现的 Is 方法）。

// errors.Is 使用示例
var ErrPermission = errors.New("权限不足")

func checkAccess(userID string) error {
    return fmt.Errorf("用户 %s 访问被拒: %w", userID, ErrPermission)
}

func main() {
    err := checkAccess("alice")
    if errors.Is(err, ErrPermission) {
        fmt.Println("确实是权限错误，记录审计日志")
    }
}

errors.Is 的匹配规则：

• 默认使用 == 比较错误值。
• 如果错误类型实现了 Is(target error) bool 方法，则调用该方法进行自定义匹配。
• 遍历过程中，只要有一层匹配成功，立即返回 true。
• 如果错误链中存在多个相同值的错误，返回第一个匹配结果。

4.4 errors.As：按类型匹配并赋值

errors.As 用于在错误链中查找第一个匹配特定类型的错误，并将该错误赋值给目标变量。与 errors.Is 按值匹配不同，errors.As 按类型匹配，适合处理自定义错误结构体。

// errors.As 使用示例
type ValidationError struct {
    Field string
    Msg   string
}

func (e *ValidationError) Error() string {
    return fmt.Sprintf("字段 %s 验证失败: %s", e.Field, e.Msg)
}

func validateInput(input string) error {
    return fmt.Errorf("输入处理异常: %w", &ValidationError{Field: "email", Msg: "格式不正确"})
}

func main() {
    err := validateInput("test")
    var ve *ValidationError
    if errors.As(err, &ve) {
        fmt.Printf("验证错误详情: 字段=%s, 消息=%s\n", ve.Field, ve.Msg)
    }
}

errors.As 的使用要点：

4.5 错误链的遍历：手动解包与自定义遍历

虽然 errors.Is 和 errors.As 覆盖了大部分场景，但有时需要手动遍历整个错误链，例如收集所有层级的错误信息用于日志记录或调试。

// 手动遍历错误链
func collectErrorChain(err error) []string {
    var chain []string
    for err != nil {
        chain = append(chain, err.Error())
        err = errors.Unwrap(err)
    }
    return chain
}

// 使用示例
func main() {
    err1 := errors.New("底层数据库错误")
    err2 := fmt.Errorf("数据层: %w", err1)
    err3 := fmt.Errorf("业务层: %w", err2)

    chain := collectErrorChain(err3)
    for i, msg := range chain {
        fmt.Printf("层级 %d: %s\n", i, msg)
    }
    // 输出:
    // 层级 0: 业务层: 数据层: 底层数据库错误
    // 层级 1: 数据层: 底层数据库错误
    // 层级 2: 底层数据库错误
}

4.6 实战：权限验证中的错误链应用

在权限验证系统中，错误链可以清晰地表达验证失败的完整路径。以下是一个结合业务场景的实战示例：

// 权限验证错误链实战
package auth

import (
    "errors"
    "fmt"
)

// 定义权限错误类型
type AuthError struct {
    UserID string
    Reason string
}

func (e *AuthError) Error() string {
    return fmt.Sprintf("用户 %s 认证失败: %s", e.UserID, e.Reason)
}

var ErrTokenExpired = errors.New("令牌已过期")
var ErrInsufficientRole = errors.New("角色权限不足")

// 验证令牌
func validateToken(token string) error {
    // 模拟令牌过期
    return fmt.Errorf("令牌验证: %w", ErrTokenExpired)
}

// 验证角色
func checkRole(userID string, requiredRole string) error {
    // 模拟角色不足
    return fmt.Errorf("角色检查: %w", ErrInsufficientRole)
}

// 统一权限验证入口
func Authorize(userID, token, requiredRole string) error {
    // 第一层：令牌验证
    if err := validateToken(token); err != nil {
        return fmt.Errorf("授权失败 [用户=%s]: %w", userID, err)
    }
    // 第二层：角色验证
    if err := checkRole(userID, requiredRole); err != nil {
        return fmt.Errorf("授权失败 [用户=%s]: %w", userID, err)
    }
    return nil
}

// 错误分析函数
func AnalyzeAuthError(err error) {
    var authErr *AuthError
    if errors.As(err, &authErr) {
        fmt.Printf("认证错误详情: 用户=%s, 原因=%s\n", authErr.UserID, authErr.Reason)
    }
    if errors.Is(err, ErrTokenExpired) {
        fmt.Println("建议：引导用户重新登录")
    }
    if errors.Is(err, ErrInsufficientRole) {
        fmt.Println("建议：提示用户权限不足，联系管理员")
    }
}