4、错误包装与链式追踪：fmt.Errorf与%w、errors.Is与errors.As、错误链的构建与解析

在 Web 服务开发中，错误往往不是孤立的。一个数据库查询失败，可能源于连接超时；一个请求被拒绝，可能因为令牌校验出错。Go 1.13 引入的错误链机制，允许开发者像链表一样将底层错误逐层包装，并在上层通过 errors.Is 和 errors.As 进行精准的链式解析。本节将深入讲解错误包装的三种模式、链式追踪的两种查询方式，以及它们在 HTTP 状态码映射中的典型应用。

4.1 错误包装的核心机制：fmt.Errorf 与 %w

fmt.Errorf 配合格式化动词 %w（wrap）是构建错误链的标准入口。与传统的 %v 或 %s 不同，%w 会将原始错误作为新错误的“内层错误”嵌入，形成可遍历的链式结构。

格式化动词 行为 是否保留错误链 适用场景
%v / %s 仅将错误转为字符串拼接 否 日志输出、用户提示（不关心原始错误类型）
%w 包装错误，保留原始错误引用 是 需要上层进行链式判断、错误分类、状态码映射
关键规则： 一个 fmt.Errorf 调用中只能使用 一个 %w。如果需要包装多个错误，必须嵌套调用或使用 errors.Join（Go 1.20+）。 
// 示例：构建三层错误链
package main

import (
    "errors"
    "fmt"
)

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

func queryDB(id string) error {
    // 模拟数据库层错误
    return fmt.Errorf("db query failed: %w", ErrNotFound)
}

func serviceLayer(id string) error {
    if err := queryDB(id); err != nil {
        // 服务层包装，添加上下文
        return fmt.Errorf("service get user %s: %w", id, err)
    }
    return nil
}

func handler(id string) error {
    if err := serviceLayer(id); err != nil {
        // 处理层包装，最终暴露给 HTTP 响应
        return fmt.Errorf("handler: %w", err)
    }
    return nil
}

func main() {
    err := handler("user-42")
    fmt.Println(err)
    // 输出: handler: service get user user-42: db query failed: resource not found
}

4.2 错误链的解析：errors.Is 与 errors.As

Go 标准库提供了两个函数用于遍历错误链：errors.Is 用于检查链中是否存在某个特定错误值（通常为哨兵错误），errors.As 用于将链中某个错误赋值给特定类型的变量。

4.2.1 errors.Is：按值匹配

errors.Is(err, target) 会沿着错误链逐层调用 Unwrap()，直到找到与 target 相等的错误（使用 == 比较），或链遍历完毕。它常用于判断错误是否属于某个已知的哨兵错误。

// 基于 4.1 的代码，判断错误链中是否包含 ErrNotFound
if errors.Is(err, ErrNotFound) {
    // 返回 HTTP 404
    http.Error(w, "User not found", http.StatusNotFound)
} else {
    // 返回 HTTP 500
    http.Error(w, "Internal server error", http.StatusInternalServerError)
}
最佳实践： 在 Web 服务的中间件或错误处理函数中，优先使用 errors.Is 匹配预定义的业务错误（如 ErrNotFound、ErrUnauthorized），然后映射到对应的 HTTP 状态码。这比解析错误字符串更安全、更高效。

4.2.2 errors.As：按类型匹配

errors.As(err, target) 会沿着错误链查找第一个可以赋值给 target 的错误。它要求 target 是一个非空指针，指向实现了 error 接口的类型。常用于提取自定义错误结构体中的附加信息（如状态码、错误码）。

// 自定义错误类型，携带 HTTP 状态码
type HTTPError struct {
    Code    int
    Message string
    Err     error
}

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

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

// 在业务层返回自定义错误
func processRequest() error {
    return &HTTPError{
        Code:    400,
        Message: "invalid input",
        Err:     fmt.Errorf("validation: %w", errors.New("field 'name' is required")),
    }
}

// 在错误处理中间件中解析
var httpErr *HTTPError
if errors.As(err, &httpErr) {
    // 直接使用自定义错误中的状态码
    http.Error(w, httpErr.Message, httpErr.Code)
} else {
    http.Error(w, "Internal server error", http.StatusInternalServerError)
}

4.3 错误链的构建与解析流程

下图展示了从底层错误到 HTTP 响应的完整链式追踪路径：

错误链构建与解析流程 底层错误 errors.New("db timeout") 数据层包装 fmt.Errorf("query: %w", err) 服务层包装 fmt.Errorf("service: %w", err) errors.Is 按值匹配 查找哨兵错误（== 比较） errors.As 按类型匹配 提取自定义错误结构体 HTTP 状态码映射结果 errors.Is(err, ErrNotFound) → 404 Not Found errors.As(err, &httpErr) → 使用 httpErr.Code 返回对应状态码 未匹配任何已知错误 → 500 Internal Server Error

4.4 错误链与 HTTP 状态码映射实战

在 Web 服务中，错误链的典型用法是：底层返回通用错误，中间层包装业务上下文，顶层根据链中错误类型或值决定 HTTP 状态码。

// 定义业务错误码
var (
    ErrUserNotFound   = errors.New("user not found")
    ErrInvalidInput   = errors.New("invalid input")
    ErrForbidden      = errors.New("forbidden")
)

// 自定义错误，携带状态码
type StatusError struct {
    StatusCode int
    Err        error
}

func (e *StatusError) Error() string {
    return e.Err.Error()
}

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

// 错误处理中间件
func errorHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 使用自定义 ResponseWriter 捕获业务错误
        // 实际项目中可结合 context 或 recover 机制
        next.ServeHTTP(w, r)
    })
}

// 状态码映射函数
func mapErrorToStatus(err error) int {
    // 1. 按值匹配哨兵错误
    if errors.Is(err, ErrUserNotFound) {
        return http.StatusNotFound
    }
    if errors.Is(err, ErrInvalidInput) {
        return http.StatusBadRequest
    }
    if errors.Is(err, ErrForbidden) {
        return http.StatusForbidden
    }

    // 2. 按类型匹配自定义错误
    var statusErr *StatusError
    if errors.As(err, &statusErr) {
        return statusErr.StatusCode
    }

    // 3. 默认返回 500
    return http.StatusInternalServerError
}

// 使用示例
func getUserHandler(w http.ResponseWriter, r *http.Request) {
    userID := r.URL.Query().Get("id")
    if userID == "" {
        err := fmt.Errorf("missing user id: %w", ErrInvalidInput)
        http.Error(w, err.Error(), mapErrorToStatus(err))
        return
    }

    // 模拟数据库查询
    if userID == "unknown" {
        err := fmt.Errorf("db query: %w", ErrUserNotFound)
        http.Error(w, "User not found", mapErrorToStatus(err))
        return
    }

    w.WriteHeader(http.StatusOK)
    w.Write([]byte(`{"name":"Alice"}`))
}

4.5 常见陷阱与最佳实践

陷阱 说明 正确做法
使用 %v 代替 %w 错误信息被转为字符串，丢失链式结构 需要链式追踪时始终使用 %w
多次使用 %w 编译错误：fmt.Errorf 只允许一个 %w 嵌套包装或使用 errors.Join
忽略 Unwrap() 方法 自定义错误类型未实现 Unwrap()，链式解析失效 自定义错误必须实现 Unwrap() error
在循环中包装错误 每次包装都生成新错误，可能丢失原始错误引用 只在关键边界层包装，避免过度包装
直接比较错误字符串 脆弱、不可靠，字符串变化导致匹配失败 使用哨兵错误或自定义错误类型
性能注意： errors.Is 和 errors.As 会遍历整个错误链。在性能敏感的 HTTP 路径中，建议将错误链深度控制在 3-5 层以内，并在中间件中尽早完成状态码映射，避免在业务代码中重复解析。

4.6 错误链的三种构建模式对比

除了 fmt.Errorf 的 %w，Go 1.20 引入了 errors.Join，用于合并多个独立错误。下表对比三种构建方式：

构建方式 链式结构 支持多个错误 典型场景
fmt.Errorf("...%w...", err) 单链（线性） 否（仅一个 %w） 逐层添加上下文
errors.Join(err1, err2, ...) 多叉树（并行） 是 验证多个字段、批量操作
自定义 Unwrap() 任意结构 取决于实现 需要携带额外元数据（如状态码） 
// errors.Join 示例：并行验证多个输入
func validateInput(name, email string) error {
    var errs []error
    if name == "" {
        errs = append(errs, fmt.Errorf("name is required: %w", ErrInvalidInput))
    }
    if email == "" {
        errs = append(errs, fmt.Errorf("email is required: %w", ErrInvalidInput))
    }
    if len(errs) > 0 {
        return errors.Join(errs...)
    }
    return nil
}

// 解析时，errors.Is 会遍历所有分支
err := validateInput("", "")
if errors.Is(err, ErrInvalidInput) {
    // 返回 400
}

通过合理运用 fmt.Errorf、errors.Is、errors.As 和 errors.Join，开发者可以构建出既保留完整错误上下文、又支持精准状态码映射的错误处理体系。这是 Go Web 服务从“能跑”到“健壮”的关键一步。

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