fmt.Errorf 多层 %w 包装怎样保留错误链

每一层都用 fmt.Errorf("上下文: %w", err) 保留原错误，并在成功时直接返回 nil；调用方用 errors.Is 判断指定错误、用 errors.As 提取具体错误类型。中间任何一层改成 %v、err.Error() 或重新 errors.New，即使文字相同，也可能切断底层关系。单次调用里有多个 %w 则是另一种结构：Go 1.20 起支持把多个错误包装为分支。

官方文档：https://pkg.go.dev/fmt#Errorf；错误匹配文档：https://pkg.go.dev/errors。下面使用模拟的文件读取错误说明现象，不依赖真实文件是否存在，也不把示例当作已执行日志。

问题现场：日志包含原因，判断却不命中

设想读取配置失败后，读取层添加“读取配置”，服务层再添加“初始化服务”。日志仍包含“文件不存在”，但上层的 errors.Is 却返回 false。这时应先检查各层如何返回 error，而不是依赖错误字符串中是否有某个词。

// 错误示例：这里只留下文本，没有保留原错误对象。
func loseCause(err error) error {
    if err == nil {
        return nil
    }
    return fmt.Errorf("初始化服务: %v", err)
}

这段函数只是问题片段，需要放入已导入 fmt 的 Go 源文件。外层若继续使用 %w，只能包装这个已经失去原因的错误，不能从文本中恢复最初的对象关系。排查顺序应从创建底层错误的位置开始，逐一检查返回边界。

初步判断：错误文本与包装关系分开看

可把多层包装理解成若干持有原错误的对象。PathError 本身还保存操作、路径与原因；读取包装和服务包装各增加本层上下文。errors.Is 与 errors.As 能沿这些关系检查底层对象。图中“业务上下文”是调用方收到的错误对象，“匹配入口”表示检查它的方式。

相同文字不等于相同错误。两次 errors.New 即使字符串一样，也创建不同错误值。包装之后直接用 == 判断通常也无法命中原来的哨兵错误。应针对稳定的错误契约判断，而不是解析增加了上下文的日志文本。

动手验证：用完整示例观察多层包装

下面给出独立程序。读取函数构造 PathError，模拟读取失败；服务函数只在有错误时添加上下文。调用方既能判断 fs.ErrNotExist，也能提取 PathError 字段。path 仅为示例，不会访问该文件。

package main

import (
    "errors"
    "fmt"
    "io/fs"
)

func readSettings() error {
    // 构造可重复说明的读取错误，不执行实际文件访问。
    cause := &fs.PathError{
        Op: "open", Path: "settings.toml", Err: fs.ErrNotExist,
    }
    return fmt.Errorf("读取配置: %w", cause)
}

func startService() error {
    if err := readSettings(); err != nil {
        // 每层只添加本层信息，并保留可匹配的原错误。
        return fmt.Errorf("初始化服务: %w", err)
    }
    return nil
}

func main() {
    err := startService()
    if err == nil {
        return
    }

    // 判断原因使用 Is，不依赖日志文本或外层对象的相等性。
    fmt.Println("原因匹配:", errors.Is(err, fs.ErrNotExist))

    // target 是具体指针类型变量，传入其地址供 As 写入。
    var pathErr *fs.PathError
    if errors.As(err, &pathErr) {
        fmt.Println("操作:", pathErr.Op, "路径:", pathErr.Path)
    }
    fmt.Println("上下文:", err)
}

按该程序的结构推导，原因匹配应为 true；类型匹配成功时应得到操作 open 和路径 settings.toml。这些是读者运行时可对照的预期，不是本地测试记录。将读取包装中的 %w 换成 %v 后，底层原因与类型都不能再通过这条包装关系抵达。

定位原因：多个 %w 形成分支

“连续调用多次 Errorf，每次一个 %w”与“一次 Errorf 放多个 %w”需要区分。前者可形成单子节点的包装层；后者从 Go 1.20 起可同时保留多个 error 操作数，返回对象提供 Unwrap() []error。版本依据：https://go.dev/doc/go1.20#errors。

// 此片段需要 Go 1.20+，并导入 errors、fmt、io/fs。
readErr := fmt.Errorf("读取配置: %w", fs.ErrNotExist)
closeErr := errors.New("关闭输入失败")
// 两个原因均被保留；这是分支，而不是第二个原因替换第一个。
combined := fmt.Errorf("配置任务: %w; 清理任务: %w", readErr, closeErr)
outer := fmt.Errorf("启动失败: %w", combined)
fmt.Println(errors.Is(outer, fs.ErrNotExist))
fmt.Println(errors.Is(outer, closeErr))

这里两个判断按构造都应为 true。聚合错误是外层上下文所包装的对象，同时持有读取错误与关闭错误。不要把多个 %w 解释成按文字顺序层层嵌套，也不要把第一个匹配结果当作业务优先级设计。

另一个常见误判是用 errors.Unwrap 循环遍历所有错误。这个函数只调用 Unwrap() error，不处理 Unwrap() []error，因此它对 combined 返回 nil，并不能说明 combined 没有原因。外层 outer 可以先解出 combined，继续用同一个单链循环仍会停住。业务匹配直接使用 errors.Is 或 errors.As 更合适。官方规则：https://pkg.go.dev/errors#Unwrap。

修复方案：保留原因，同时控制暴露的契约

把必须允许调用方识别的错误边界统一改为 %w；只在 err 非 nil 时包装，并让正常分支返回 nil。%w 的参数必须实现 error，不能把字符串当作原因传入。fmt.Errorf 本身创建错误，不会因为传入 nil 就自动成为成功结果。

// 修复后的边界片段：保留原因，成功时保持 nil。
func addServiceContext(err error) error {
    if err == nil {
        return nil
    }
    return fmt.Errorf("初始化服务: %w", err)
}

不要把所有内部实现都无条件暴露。比如服务对外只承诺“配置缺失”，而不承诺特定存储驱动类型，就应在接口边界明确转换为领域错误，并记录内部原因。这个选择会有意改变可匹配关系，需要在接口文档中说明；不应把它与意外使用 %v 导致断链混淆。

上下文也不宜层层重复完整句子。读取层记录本层任务，服务层记录业务动作，最终处理层统一输出日志，通常更容易看出职责。包装保留的是错误关系，并不会自动记录调用堆栈；需要堆栈信息时应另用项目约定的观测方案。

验证结果：按关系判断，而不是按文本猜测

修改实际项目后，可以把这些关系断言放入已有测试用例，覆盖关键返回边界。这里的表格提供预期判断标准，并未运行项目测试，也没有编造输出截图。

总结与相关问题

多层包装是否保留错误链，关键在于每个需要透传原因的边界是否持有原错误。%w 负责建立关系，Is 与 As 负责匹配关系；多个 %w 需要按错误树理解，不能照搬只处理单链的展开方式。

外层换成 %w，能补回内层丢失的错误吗？

不能。内层已经转换为纯文本时，外层只能保留这个新错误。需要修复真正断开的返回位置。

多个 %w 时，errors.Unwrap 返回 nil 是不是异常？

不是。它只调用返回单个 error 的 Unwrap 方法。对多错误包装应使用 Is、As；需要自定义遍历时才分别处理两种 Unwrap 签名。

包装错误会自动带上堆栈吗？

不会。fmt.Errorf 添加文本和包装关系，堆栈采集属于独立能力，不能仅根据错误文字推断调用栈。