4. 错误包装：fmt.Errorf %w 动词、errors.Unwrap、错误链的概念与报表链路追踪

在真实的企业报表系统中，一个错误往往不是孤立产生的。例如：数据库连接超时 → 查询执行失败 → 报表生成中断 → API 返回 500。每一层都会对原始错误进行“包装”，添加上下文信息，同时保留底层错误的根因。Go 1.13 引入的 %w 动词和 errors.Unwrap 函数，正是为这种场景设计的标准方案。

4.1 错误包装的核心机制

fmt.Errorf 配合 %w 动词，可以将一个已有错误“包装”进一个新的错误中，形成一条可追溯的错误链。与 %v 不同，%w 保留了被包装错误的接口信息，使得后续可以通过 errors.Is 和 errors.As 进行断言。

4.2 错误链的构建与遍历

错误链本质上是一个单向链表：每个包装错误内部持有一个 Unwrap() error 方法，返回被包装的下一层错误。链的末端是原始根因错误，没有 Unwrap 方法（返回 nil）。

// 定义底层错误
var ErrDBTimeout = errors.New("数据库连接超时")

// 第1层包装：添加业务上下文
err1 := fmt.Errorf("报表数据源查询失败: %w", ErrDBTimeout)

// 第2层包装：添加模块上下文
err2 := fmt.Errorf("生成月度报表时出错: %w", err1)

// 第3层包装：添加API上下文
err3 := fmt.Errorf("报表API调用异常: %w", err2)

// 错误链结构：err3 → err2 → err1 → ErrDBTimeout

通过 errors.Unwrap 可以手动遍历这条链：

current := err3
for current != nil {
    fmt.Println(current)
    current = errors.Unwrap(current)
}
// 输出：
// 报表API调用异常: 生成月度报表时出错: 报表数据源查询失败: 数据库连接超时
// 生成月度报表时出错: 报表数据源查询失败: 数据库连接超时
// 报表数据源查询失败: 数据库连接超时
// 数据库连接超时

4.3 错误链的视觉化：报表链路追踪

下面这张 SVG 图展示了报表系统中一个典型错误的完整链路，从底层数据库到顶层 API 响应，每一层都通过 %w 包装串联起来。

4.4 errors.Unwrap 与自定义错误类型

除了 fmt.Errorf %w，你也可以在自定义错误类型中实现 Unwrap() error 方法，从而加入错误链。这在报表系统中非常有用，例如定义一个携带额外字段（如报表 ID、时间戳）的错误类型：

type ReportError struct {
    Msg      string
    ReportID string
    Err      error  // 被包装的底层错误
}

func (e *ReportError) Error() string {
    return fmt.Sprintf("[报表 %s] %s: %v", e.ReportID, e.Msg, e.Err)
}

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

// 使用示例
baseErr := errors.New("数据源不可用")
reportErr := &ReportError{
    Msg:      "报表生成失败",
    ReportID: "RPT-2024-001",
    Err:      baseErr,
}

// reportErr 可以被 errors.Is 和 errors.As 遍历
if errors.Is(reportErr, baseErr) {
    fmt.Println("匹配到根因：数据源不可用")
}

4.5 错误链在报表系统中的应用模式

在报表系统中，错误链通常遵循“三层包装”模式，每一层负责不同的职责：

• 数据层（底层）：包装数据库、缓存、外部 API 的原始错误，添加数据源标识和查询参数。
• 业务层（中间层）：包装数据层错误，添加报表 ID、计算规则、时间范围等业务上下文。
• 接口层（顶层）：包装业务层错误，添加请求 ID、用户 ID、接口版本等调用上下文。

这种模式使得运维人员可以快速定位问题：从顶层错误消息中知道“哪个接口、哪个用户、哪个报表”出了问题，再通过 errors.Unwrap 逐层深入，最终找到“数据库连接超时”或“除零错误”等根因。

4.6 常见陷阱与最佳实践