errwrap：在 Moby 中规范化 Go 错误包装与错误链检索的工程实践

errwrap 是 HashiCorp 开源的一套 Go 错误处理工具包，它把"包装错误后再沿错误链检索底层错误"这一常见诉求收敛为统一的接口与函数族，让调用方无需关心错误到底是被 fmt.Errorf、自定义结构体还是第三方库包装的。本仓库在 vendor/github.com/hashicorp/errwrap 下以第三方依赖形式完整保留了该库，并通过 hashicorp/go-multierror 在 daemon 的配置重载事务中得到实际使用。读完本文，你将掌握 errwrap 的核心 API、Wrapper 接口的扩展机制，以及它如何与 Go 官方 errors 包、多错误聚合库在真实工程（如 Moby daemon）中协作。

errwrap 解决的问题：包装错误后的结构丢失

在 Go 中，一个常见写法是把某个函数返回的 error 包装（wrap）后再向上抛出，例如使用 fmt.Errorf 拼接上下文。README 明确指出这类模式的痛点：一旦做了包装，原始 error 的结构信息就完全丢失了——调用方只知道外层错误的文本消息，无法判断错误链深处是否藏有特定类型（如 *os.PathError）或特定内容的错误。

README 给出的"教科书级"方案是自建一个实现 error 接口的结构体，把原始错误作为字段挂在上面，os.PathError 本身就是这样设计的：

type PathError struct {
	Op   string
	Path string
	Err  error
}

但这条路需要你预先知道整个调用链上所有可能的重新包装方式，而很多时候你只关心其中一个。errwrap 的价值在于把"包装错误、判断是否包含某错误、取出该错误"这三件事形式化为单一接口，从而不绑定任何具体包装手法。这一点在仓库内 errwrap.go 的包注释里也再次强调：所有接收 error 的顶层函数都对任意错误生效（不限于 errwrap 包装过的错误），因此使用它不需要到处做类型断言。

快速入门：Wrapf + Contains/Get 三件套

README 给出了一个非常贴近真实场景的基础示例——某函数假装尝试打开一个不存在的文件并包装错误，调用方随后进行"是否包含"与"按类型提取"两类判断：

// A function that always returns an error, but wraps it, like a real
// function might.
func tryOpen() error {
	_, err := os.Open("/i/dont/exist")
	if err != nil {
		return errwrap.Wrapf("Doesn't exist: {{err}}", err)
	}

	return nil
}

func main() {
	err := tryOpen()

	// We can use the Contains helpers to check if an error contains
	// another error. It is safe to do this with a nil error, or with
	// an error that doesn't even use the errwrap package.
	if errwrap.Contains(err, "does not exist") {
		// Do something
	}
	if errwrap.ContainsType(err, new(os.PathError)) {
		// Do something
	}

	// Or we can use the associated `Get` functions to just extract
	// a specific error. This would return nil if that specific error doesn't
	// exist.
	perr := errwrap.GetType(err, new(os.PathError))
}

这段代码覆盖了 errwrap 最核心的三个能力维度：

• errwrap.Wrapf(format, err)：带格式文本地包装错误，格式串中的 {{err}} 占位符会被替换为原始错误的 Error() 文本。README 与源码注释强调，如果你正用 fmt.Errorf 做错误包装，可以替换为它（见下文的演进说明）。
• errwrap.Contains(err, msg)：判断错误链中是否包含错误消息等于 msg 的错误。对 nil 错误调用是安全的，对根本没有用 errwrap 的错误调用也安全（此时只有当错误本身消息恰好匹配时才返回 true）。其实现即 return len(GetAll(err, msg)) > 0，见 errwrap.go。
• errwrap.ContainsType(err, v) / errwrap.GetType(err, v)：按具体类型而非文本匹配错误；GetType 提取不到时返回 nil，不会 panic。

注意示例中 Contains(err, "does not exist") 匹配的是被包装前的底层消息 "open /i/dont/exist: no such file or directory"（底层 *os.PathError 的消息包含该子串），演示了"外层包装、里层检索"的典型用法；perr := errwrap.GetType(err, new(os.PathError)) 返回的是类型为 *os.PathError 的原始错误对象，便于进一步读取 Op、Path、Err 等结构字段。

自定义包装类型：实现 Wrapper 接口即可获得全部能力

不是所有人都愿意用 Wrapf。README 指出，如果你本来就用自建结构体正确包装错误，那么只要让它实现 errwrap 的 Wrapper 接口——只需一个方法——Contains、Get 等全部函数就会自动生效：

type AppError {
  Code ErrorCode
  Err  error
}

func (e *AppError) WrappedErrors() []error {
  return []error{e.Err}
}

此后：

err := &AppError{Err: fmt.Errorf("an error")}
if errwrap.ContainsType(err, fmt.Errorf("")) {
	// This will work!
}

该接口的定义位于 errwrap.go：

type Wrapper interface {
	WrappedErrors() []error
}

其核心价值在于组合性：errwrap 内部所有检索都建立在 Walk 之上，而 Walk 对 Wrapper 会递归遍历 WrappedErrors() 返回的每一个子错误。因此只要错误链中任何一环实现了 Wrapper，整条链都能被统一检索引擎覆盖，这与"嵌套包装多层 AppError / multierror"的场景天然契合。

源码透视：Walk 遍历、wrappedError 结构与 API 全景

仓库 vendor/github.com/hashicorp/errwrap/errwrap.go 全文件仅 179 行，完整实现了一整套 API，是理解其内部机制的最佳入口。所有函数围绕一个基础构件展开：

• wrappedError（L163-L178）：errwrap 内部的错误包装结构，含 Outer 与 Inner 两个字段。它的 Error() 直接返回 Outer 的消息，不会改动外层文案；同时它自身实现了 Wrapper（WrappedErrors() 返回 []error{w.Outer, w.Inner}）与 Unwrap()（返回 Inner），使它既能被 errwrap 自己的遍历机制识别，也能被 Go 标准库错误链机制识别。
• Wrap(outer, inner error)（L34-L39）：底层包装原语，只建立包装关系、不改动任何错误消息。Wrapf 最终也委托给它（先用 strings.Replace 把 {{err}} 替换为 err.Error() 生成外层消息，再调用 Wrap）。
• Walk(err error, cb WalkFunc)（L138-L159）：检索引擎的心脏，对错误链做类型分派：
  • *wrappedError：先对 Outer 执行回调，再递归 Walk(Inner)；
  • 实现 Wrapper 的类型：对自身执行回调，再对 WrappedErrors() 的每个子错误递归；
  • 实现 interface{ Unwrap() error } 的类型（兼容标准库 fmt.Errorf 的 %w 包装）：对自身执行回调后沿 Unwrap() 继续；
  • 其余普通错误：仅回调一次。
  • err == nil 时直接返回——这是 Contains/Get 系列对 nil 安全的原因。

基于 Walk，errwrap 提供了两类检索函数（各自的顺序约定为"最外层匹配错误排在最前、索引 0，逐层向内"）：

函数	匹配依据	语义
GetAll(err, msg)	错误消息 Error() == msg（精确匹配）	返回全部匹配错误
Get(err, msg)	同上	返回 GetAll 结果中最深一层的匹配错误，无则 nil
GetAllType(err, v)	reflect.TypeOf(err).String() == reflect.TypeOf(v).String()	返回全部同类型错误，按 reflect 类型字符串比对
GetType(err, v)	同上	返回最深一层的同类型错误
Contains(err, msg)	消息精确匹配	len(GetAll(...)) > 0 的布尔封装
ContainsType(err, v)	类型匹配	len(GetAllType(...)) > 0 的布尔封装

类型匹配的实现细节见 errwrap.go：对 v 与每个被遍历错误分别取 reflect.TypeOf(...).String() 再比较，且对 nil 错误做了防御（needle 为空串时不会误命中）。这正是示例中 ContainsType(err, new(os.PathError)) 无需强转即可生效的原因。

在 Moby 仓库中的位置与真实调用链

errwrap 在本仓库中不是孤立存在的演示代码，而是被实际 vendored 进依赖树并参与构建：

• 版本与来源：根 go.mod 中声明 github.com/hashicorp/errwrap v1.1.0 // indirect，代码副本位于 vendor/github.com/hashicorp/errwrap/（含 README、LICENSE 与单文件实现）。
• 上游消费方 go-multierror：errwrap 作为间接依赖，主要服务于同为 HashiCorp 的 github.com/hashicorp/go-multierror v1.1.1。后者在 vendor/github.com/hashicorp/go-multierror/prefix.go 的 Prefix 函数中直接调用 errwrap.Wrapf(format, e)，为单个错误或 multierror.Error 内的每个子错误统一添加前缀。同时 multierror.go 中 (*Error).WrappedErrors() 即是对 errwrap.Wrapper 接口的实现——这恰好是上一节"自定义类型实现 Wrapper 即获全部检索能力"在真实生态中的典型案例：任何聚合多错误的对象只要实现该接口，就能被 errwrap 的检索函数递归穿透。
• Moby 侧的实际落地：daemon 在热加载配置时会将多个回调的错误汇聚处理，相关事务逻辑见 daemon/reload.go。这里对 multierror.Error（历史上即依赖 errwrap 生态）在错误收集中角色的代码注释仍被保留，可帮助你理解此类"多错误聚合 + 统一检索"模式在 Docker 守护进程这类复杂系统中的用武之地。

Wrapf 的弃用与 Go 标准库的演进

值得注意的版本事实：仓库内 errwrap.go 已将 Wrapf 标记为 Deprecated，注释明确建议改用 fmt.Errorf()。原因在于 Go 1.13+ 引入了原生错误包装语法（fmt.Errorf("...: %w", err)）以及配套的 errors.Is / errors.As / Unwrap 接口；errwrap 的 Walk 在类型分派中专门保留了 interface{ Unwrap() error } 分支，正是为了兼容这条官方链路。

因此 errwrap 与现代 Go 代码的合理组合方式是：新代码优先用 %w 构建错误链并用 errors.Is/errors.As 检索；遇到遗留代码、multierror 等"多错误容器"，或希望以统一的 Wrapper 语义描述自建聚合类型时，errwrap 的 Walk/Contains/GetType 仍是简洁且可递归的补充工具。Moby 的 go.sum 中同时保留 errwrap 的 go.mod 与完整模块哈希记录，也印证了这套混合生态在真实构建中的长期共存。

小结

errwrap 的核心设计可用三句话概括：用 Wrapper 接口统一"错误可被展开"的语义；用 Walk 递归遍历任意深度、任意包装手法的错误链；在其上派生出 Contains/Get/GetAll（按消息）与 ContainsType/GetType/GetAllType（按类型）两族检索函数。无论你是想检索 *os.PathError 这类底层系统错误，还是让自定义错误容器获得标准化的可检索能力，都可以在 vendor/github.com/hashicorp/errwrap/ 中找到既定的实现模式，并结合 go-multierror、标准库错误链在 Moby daemon 等工程中安全使用。