4. 错误包装与解包：errors.Wrap、errors.Unwrap、errors.Is 与 errors.As 深度解析

在 Go 业务系统中，错误不仅仅是“发生了故障”，更是携带上下文信息的信号。原始错误经过多层调用后，如果直接返回，会丢失调用栈和业务语义。Go 1.13 引入的 errors 包增强机制，以及 github.com/pkg/errors 提供的 Wrap 系列函数，共同构成了现代 Go 错误处理的基石。本章将深入剖析包装、解包、判等与类型断言的核心 API。

4.1 错误包装的核心动机

业务代码中，一个底层错误（如数据库连接失败）经过 Service → Controller → Middleware 层层传递，每一层都可能附加新的上下文。包装（Wrap）解决了三个关键问题：

  • 保留原始错误：不丢失根因（Root Cause）。
  • 附加调用栈：快速定位错误发生的代码位置。
  • 增加业务语义：将底层错误转化为领域内可理解的错误消息。
最佳实践：在业务边界层（如 Repository → Service）使用 errors.Wrap，在顶层（如 HTTP Handler）使用 errors.WithMessage 避免重复包装栈信息。

4.2 核心 API 速览

函数 来源 作用 典型场景
errors.Wrap(err, msg) github.com/pkg/errors 包装错误并附加调用栈 跨层调用时保留原始错误与栈帧
errors.Wrapf(err, fmt, args...) github.com/pkg/errors 格式化消息后包装 需要动态拼接上下文信息
errors.Unwrap(err) 标准库 errors 返回被包装的下一层错误 手动遍历错误链
errors.Is(err, target) 标准库 errors 判断错误链中是否包含目标哨兵错误 检查特定错误类型（如 io.EOF）
errors.As(err, target) 标准库 errors 在错误链中查找第一个匹配类型的错误并赋值 提取自定义错误结构体中的字段

4.3 错误链的构建与遍历

每次调用 errors.Wrap 都会在错误外层包裹一个新节点，形成单向链表结构。下图展示了典型的错误链：

错误链结构（单向链表） 原始错误 "record not found" Repository 包装 "db query failed" Service 包装 "get user failed" 遍历方向： errors.Is / errors.As 从最外层向最内层逐层 Unwrap errors.Unwrap 每次只剥离最外层，返回下一层 当 Unwrap 返回 nil 时，表示已到达根错误

4.4 errors.Is：哨兵错误匹配

errors.Is 沿着错误链逐层调用 Unwrap，并与目标哨兵错误进行 == 比较。它适用于检查“是否发生了某种特定错误”，例如数据库未找到记录、文件不存在等。

var ErrNotFound = errors.New("record not found")

func GetUser(id int) error {
    // 模拟底层错误
    return errors.Wrap(ErrNotFound, "repository: query user")
}

func main() {
    err := GetUser(42)
    if errors.Is(err, ErrNotFound) {
        fmt.Println("用户不存在，返回 404")
    }
}
关键行为：errors.Is 会遍历整个错误链，只要链中任意一个错误与目标相等，即返回 true。即使错误被多层包装，也能正确匹配。

4.5 errors.As：提取自定义错误类型

当错误携带结构化数据（如状态码、错误码、重试建议）时，需要使用 errors.As 将错误链中的某个节点转换为具体类型，并提取字段。

type BizError struct {
    Code    int
    Message string
}

func (e *BizError) Error() string {
    return fmt.Sprintf("code=%d: %s", e.Code, e.Message)
}

func ProcessOrder() error {
    return errors.Wrap(&BizError{Code: 1001, Message: "库存不足"}, "order service")
}

func main() {
    err := ProcessOrder()
    var bizErr *BizError
    if errors.As(err, &bizErr) {
        fmt.Printf("业务错误码: %d, 详情: %s\n", bizErr.Code, bizErr.Message)
    }
}
对比维度 errors.Is errors.As
比较方式 值相等（==） 类型断言（interface conversion）
目标参数 哨兵错误值 目标类型的指针
典型用途 检查特定错误标识 提取错误中的结构化数据
遍历行为 找到第一个相等即停止 找到第一个类型匹配即停止

4.6 自定义 Unwrap 方法

标准库 errors.Is 和 errors.As 依赖 Unwrap() error 接口。如果你的自定义错误类型需要参与错误链，必须实现该方法：

type WrappedError struct {
    Err  error
    Msg  string
}

func (w *WrappedError) Error() string {
    return fmt.Sprintf("%s: %v", w.Msg, w.Err)
}

func (w *WrappedError) Unwrap() error {
    return w.Err
}

// 现在 WrappedError 可以被 errors.Is / errors.As 正确遍历
func main() {
    base := errors.New("root cause")
    wrapped := &WrappedError{Err: base, Msg: "wrapped"}
    fmt.Println(errors.Is(wrapped, base)) // true
}

4.7 常见陷阱与避坑指南

  • 不要对 nil 错误调用 Wrap：errors.Wrap(nil, "msg") 返回 nil，不会产生包装效果。
  • 避免重复包装：在顶层 Handler 中只使用 errors.WithMessage 或直接返回，防止栈信息冗余。
  • 哨兵错误使用 errors.New 定义：不要使用 fmt.Errorf 创建哨兵，因为每次调用会生成不同地址。
  • As 的目标必须是非 nil 指针：errors.As(err, &target) 中 target 必须是指向具体类型的指针，且不能为 nil。
  • 不要用 errors.Is 检查动态错误：如果错误包含动态字段（如时间戳），应使用 errors.As 提取后手动判断。
性能注意：errors.Wrap 会捕获调用栈，在高频调用路径上（如每秒数万次）可能产生显著开销。建议在性能敏感路径使用 fmt.Errorf("%w", err) 替代，它只包装不捕获栈。

4.8 实战：三层架构中的错误传递

以下代码展示了一个典型的 Web 服务中，错误从 Repository 到 Handler 的完整传递过程：

// repository/user.go
var ErrUserNotFound = errors.New("user not found")

func (r *Repo) FindByID(ctx context.Context, id int) (*User, error) {
    row := r.db.QueryRow("SELECT ...", id)
    if errors.Is(row.Err(), sql.ErrNoRows) {
        return nil, errors.Wrap(ErrUserNotFound, "repo")
    }
    // ...
}

// service/user.go
func (s *Service) GetUser(ctx context.Context, id int) (*User, error) {
    user, err := s.repo.FindByID(ctx, id)
    if err != nil {
        return nil, errors.Wrap(err, "service: get user")
    }
    return user, nil
}

// handler/user.go
func (h *Handler) GetUser(w http.ResponseWriter, r *http.Request) {
    user, err := h.svc.GetUser(r.Context(), id)
    if err != nil {
        if errors.Is(err, ErrUserNotFound) {
            http.Error(w, "用户不存在", http.StatusNotFound)
            return
        }
        http.Error(w, "内部错误", http.StatusInternalServerError)
        return
    }
    json.NewEncoder(w).Encode(user)
}

通过 errors.Wrap 和 errors.Is 的组合，Handler 层无需关心底层是 SQL 错误还是缓存错误，只需检查业务哨兵错误即可做出正确响应。

← 上一章 📖 返回目录 下一章 →