4、错误包装（Error Wrapping）：构建可追溯的错误链

在业务层处理错误时，仅仅返回一个静态的错误信息往往是不够的。当错误从底层（如数据库、RPC 调用）向上层（业务逻辑、API 层）传播时，每一层都可能为错误添加有价值的上下文信息。Go 1.13 引入的 错误包装（Error Wrapping） 机制，正是为了解决这一问题——它允许我们在保留原始错误根因的同时，逐层附加描述性信息，形成一条完整的“错误链”。

4.1 fmt.Errorf + %w：标准包装方式

fmt.Errorf 配合 %w 动词是 Go 中最推荐的错误包装手段。它创建一个新的错误，该错误内部持有一个指向原始错误的引用，从而形成链式结构。

package main

import (
    "fmt"
    "os"
)

// 模拟一个读取配置文件的底层函数
func readConfig(path string) error {
    _, err := os.Open(path)
    if err != nil {
        // 使用 %w 包装原始错误，附加上下文
        return fmt.Errorf("读取配置文件 %s 失败: %w", path, err)
    }
    return nil
}

func main() {
    err := readConfig("/etc/app/config.yaml")
    if err != nil {
        fmt.Println(err)
        // 输出: 读取配置文件 /etc/app/config.yaml 失败: open /etc/app/config.yaml: no such file or directory
    }
}

4.2 errors.Unwrap()：解包与链式遍历

errors.Unwrap() 是错误链的“拆解器”。它接收一个错误，如果该错误是通过 %w 包装的，则返回其内部的原始错误；否则返回 nil。通过反复调用 Unwrap，我们可以手动遍历整条错误链。

import (
    "errors"
    "fmt"
)

// 模拟多层包装
func level1() error {
    return fmt.Errorf("level1: %w", level2())
}

func level2() error {
    return fmt.Errorf("level2: %w", level3())
}

func level3() error {
    return errors.New("root cause: disk full")
}

func main() {
    err := level1()
    fmt.Println("完整错误:", err)

    // 手动解包遍历
    current := err
    for current != nil {
        fmt.Println("当前层:", current)
        current = errors.Unwrap(current)
    }
    // 输出:
    // 完整错误: level1: level2: root cause: disk full
    // 当前层: level1: level2: root cause: disk full
    // 当前层: level2: root cause: disk full
    // 当前层: root cause: disk full
}

4.3 errors.Is()：沿错误链判断特定错误

errors.Is(err, target) 会沿着 err 的错误链，逐层检查是否有任何一个错误与 target 相等（通过 == 比较或目标错误实现了 Is(error) bool 方法）。这是替代 if err == io.EOF 这种脆弱比较的标准做法。

import (
    "errors"
    "fmt"
    "os"
)

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

func queryDatabase(id int) error {
    // 模拟数据库查询
    return fmt.Errorf("查询用户 %d 失败: %w", id, ErrNotFound)
}

func main() {
    err := queryDatabase(42)

    // 使用 errors.Is 判断错误链中是否包含 ErrNotFound
    if errors.Is(err, ErrNotFound) {
        fmt.Println("错误原因: 记录未找到，请检查用户ID")
    }

    // 也可以判断标准库错误
    _, openErr := os.Open("/nonexistent")
    if errors.Is(openErr, os.ErrNotExist) {
        fmt.Println("文件不存在")
    }
}

4.4 errors.As()：沿错误链进行类型断言

当我们需要获取错误链中某个特定类型的错误实例，并访问其携带的额外字段或方法时，errors.As(err, target) 就派上了用场。它会沿着错误链查找第一个可以赋值给 target 的错误，并将该错误赋值给 target（target 必须是一个指向错误接口的非空指针）。

import (
    "errors"
    "fmt"
)

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

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

func callAPI() error {
    // 返回自定义错误
    return fmt.Errorf("API调用失败: %w", &HTTPError{Code: 503, Message: "Service Unavailable"})
}

func main() {
    err := callAPI()

    var httpErr *HTTPError
    // 使用 errors.As 提取错误链中的 *HTTPError 实例
    if errors.As(err, &httpErr) {
        fmt.Printf("捕获到 HTTP 错误: 状态码=%d, 详情=%s\n", httpErr.Code, httpErr.Message)
        // 输出: 捕获到 HTTP 错误: 状态码=503, 详情=Service Unavailable
    }
}

4.5 错误链全景图

下面的 SVG 图展示了从底层到业务层的完整错误包装与解包流程，以及 Is 和 As 在链上的工作方式。

4.6 业务层错误包装规范

在业务层统一错误处理时，建议遵循以下包装规范，以确保错误链的一致性和可维护性：

1. 每一层只包装一次：在接收到下层错误时，立即包装并附加当前层的上下文，不要跨层传递未包装的错误。
2. 上下文信息要具体：包装信息应包含“在做什么”和“操作对象”，例如 fmt.Errorf("创建订单 %s 失败: %w", orderID, err)。
3. 避免重复包装：不要对同一个错误进行多次 %w 包装，这会导致链中出现重复节点，增加判断开销。
4. 区分内部错误与外部错误：内部错误（如数据库连接失败）应包装后记录日志；外部错误（如用户输入无效）可直接返回，无需过度包装。