错误包装

是什么，为什么存在

错误包装（error wrapping） 是把一个错误放入另一个错误中，同时为当前操作添加上下文。 格式化后的消息可以说明哪项操作失败，而被包装的值仍保留自己的身份、类型和字段。

如果每一层只原样返回错误，最终日志可能只剩下 permission denied 或 record not found，无法指出失败发生在哪次业务操作中。 如果每一层都创建全新的文本错误，消息虽然变长，程序却无法再可靠地判断原始原因。 包装把这两个需求放在同一条路径上：文本供人阅读，结构供程序检查。

Go 代码在文件访问、数据库适配器、HTTP 客户端、解析器和服务边界中经常包装错误。 当一层知道当前操作，下一层知道更具体的失败原因时，就适合增加一层上下文。 没有新信息可补充时，直接返回错误通常更清楚。

错误结构也是 API 契约。 公开函数用 %w 包装某个值后，调用方就可能通过 errors.Is 或 errors.As 依赖它。 因此，选择 %w 不是单纯的格式化决定；它决定了哪些原因会穿过包边界。

工作原理

error 接口只有 Error() string 方法，但包装协议还约定了 Unwrap() error 和 Unwrap() []error 两种方法。 实现前者的值包装一个子错误，实现后者的值包装零个或多个子错误。 连续展开后得到的结构称为 错误链（error chain） ；存在多子节点时，它实际上是一棵树。

fmt.Errorf("load profile: %w", err) 会返回一个错误，其 Error 消息包含 err，其 Unwrap 方法则返回 err。 如果格式字符串含有多个 %w，结果会通过 Unwrap() []error 按参数出现顺序公开所有操作数。 %w 在可见文本上的格式与 %v 相同，差别只存在于可遍历结构中。

errors.Is(err, target) 会以前序深度优先方式检查错误树。 它先检查当前错误是否等于目标，或当前错误的 Is(error) bool 方法是否报告浅层匹配，然后再访问子错误。 经过多层 %w 包装后，稳定的哨兵错误仍然可以被找到。

errors.As(err, &target) 使用同样的遍历顺序寻找可赋给目标类型的错误。 调用方先声明目标槽位，再把该槽位的指针传给 As；匹配成功时，As 会写入找到的错误。 它适合读取自定义错误公开的结构化字段，而不是解析 Error() 返回的字符串。

errors.Join 会丢弃 nil 输入，并把剩余错误放在同一父节点下。 所有输入都是 nil 时，它返回 nil。 errors.Is 和 errors.As 会访问每个非 nil 子错误，但 errors.Unwrap 只识别 Unwrap() error，不会替你枚举合并节点。

一次典型的传播过程是：

1. 底层操作返回具体错误或哨兵错误。
2. 中间层用 %w 添加只有这一层知道的操作上下文。
3. 边界层用 errors.Is 或 errors.As 分类失败。
4. 拥有处理结果的边界记录一次日志、返回状态或决定重试。

这套机制不会自动定义错误契约。 包作者仍要决定保留底层原因、转换为领域错误，还是把原因隐藏在包内部。 调用方只能依赖文档与测试明确承诺的匹配行为。

示例

包装并匹配哨兵错误

第一层说明查找了哪个订单，第二层说明当时正在加载收据。 两层消息都保留下来，调用方仍能识别稳定的 ErrOrderMissing 类别。

直接比较看到的是最外层包装器，所以结果为 false。 errors.Is 会继续访问两个包装层，最终找到哨兵错误。 这正是调用方想问的语义问题，而不是两个接口值是否相等。

错误消息从外到内读起来像一条操作路径。 每一层只添加自己能说明的信息，避免出现「failed to handle error」这类没有诊断价值的填充文本。

用 errors.As 读取字段

类别判断不够用时，自定义错误可以携带字段。 它实现 Unwrap 后，具体类型与更宽泛的哨兵类别可以同时存在于一棵错误树中。

package main

import (
	"errors"
	"fmt"
	"strings"
)

var ErrInvalidField = errors.New("invalid field")

type FieldError struct {
	Field string
	Value string
	Err   error
}

func (e *FieldError) Error() string {
	return fmt.Sprintf("%s=%q: %v", e.Field, e.Value, e.Err)
}

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

func validateEmail(email string) error {
	if !strings.Contains(email, "@") {
		return &FieldError{"email", email, ErrInvalidField}
	}
	return nil
}

func main() {
	err := fmt.Errorf("create account: %w", validateEmail("alex.example.com"))
	var fieldErr *FieldError

	fmt.Println("invalid:", errors.Is(err, ErrInvalidField))
	if errors.As(err, &fieldErr) {
		fmt.Printf("field=%s value=%s\n", fieldErr.Field, fieldErr.Value)
	}
}

invalid: true
field=email value=alex.example.com

errors.Is 负责回答「是否属于无效字段」，errors.As 则取得 *FieldError 的字段。 两种检查关注不同的契约，因此可以在同一个调用位置组合使用。

这里的 Error 方法用 %v 格式化自身保存的原因是正确的。 建立包装关系的是 Unwrap 方法；在 Error() 内再次使用 %w 没有意义，因为 %w 只对 fmt.Errorf 的返回值建立结构。

定义浅层的自定义匹配

有些包希望用稳定代码分类错误，同时让每个实例保留不同的操作和原因。 自定义 Is 方法可以把模板错误映射到这种类别，但它只应比较当前接收者和目标。

package main

import (
	"errors"
	"fmt"
)

var ErrRowAbsent = errors.New("row absent")

type CodeError struct {
	Code string
	Op   string
	Err  error
}

func (e *CodeError) Error() string {
	return fmt.Sprintf("%s [%s]: %v", e.Op, e.Code, e.Err)
}

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

func (e *CodeError) Is(target error) bool {
	want, ok := target.(*CodeError)
	return ok && e.Code == want.Code
}

var ErrNotFound = &CodeError{Code: "NOT_FOUND"}

func main() {
	err := &CodeError{
		Code: "NOT_FOUND",
		Op:   `find user "U-9"`,
		Err:  ErrRowAbsent,
	}

	fmt.Println(err)
	fmt.Println("category:", errors.Is(err, ErrNotFound))
	fmt.Println("cause:", errors.Is(err, ErrRowAbsent))
}

find user "U-9" [NOT_FOUND]: row absent
category: true
cause: true

第一次匹配由 CodeError.Is 根据代码完成。 第二次匹配不需要 Is 方法递归搜索；标准库在检查当前节点后会调用 Unwrap，再找到 ErrRowAbsent。

这种模板匹配会扩大公开契约。 一旦调用方依赖 NOT_FOUND 的匹配语义，修改代码值或 Is 规则就可能成为破坏性变更。

合并多个错误分支

验证器可以一次返回多个独立失败。 errors.Join 保留每个分支的包装上下文，调用方无需解析换行后的消息。

package main

import (
	"errors"
	"fmt"
	"strings"
)

var (
	ErrNameRequired = errors.New("name required")
	ErrEmailInvalid = errors.New("email invalid")
)

func validateProfile(name, email string) error {
	var failures []error
	if strings.TrimSpace(name) == "" {
		failures = append(failures,
			fmt.Errorf("name: %w", ErrNameRequired))
	}
	if !strings.Contains(email, "@") {
		failures = append(failures,
			fmt.Errorf("email %q: %w", email, ErrEmailInvalid))
	}
	return errors.Join(failures...)
}

func main() {
	err := validateProfile("", "alex.example.com")
	if err == nil {
		fmt.Println("valid")
		return
	}

	fmt.Println(err)
	fmt.Println("name:", errors.Is(err, ErrNameRequired))
	fmt.Println("email:", errors.Is(err, ErrEmailInvalid))
	fmt.Println("single unwrap is nil:", errors.Unwrap(err) == nil)
}

name: name required
email "alex.example.com": email invalid
name: true
email: true
single unwrap is nil: true

合并值的文本把两个子错误放在不同行，但格式不是分类 API。 两个 errors.Is 调用分别沿对应分支找到目标。

最后一行展示了一个容易误判的细节：errors.Unwrap 不处理 Unwrap() []error。 需要分类时直接使用 Is 或 As；需要枚举整棵树时，诊断代码必须明确处理两种 Unwrap 签名。

陷阱

用 %v 截断错误树

修复方法： 如果底层原因属于公开契约，就改用 %w，并添加经过至少一层包装的测试。 如果原因属于实现细节，则有意转换为领域错误，不要让 %v 假装成仍可遍历的包装。

只检查最外层值

修复方法： 对稳定值使用 errors.Is，对结构化类型使用 errors.As。 只有明确需要判断最外层身份时才直接比较，而且测试应说明这种限制。

包装 nil 错误

修复方法： 在包装前写出 if err != nil 分支，成功路径直接返回 nil。 特别检查短函数末尾的 return fmt.Errorf("operation: %w", err)：缺少前置判断时，操作成功也会返回非 nil 错误。

给 errors.As 错误的目标

修复方法： 先声明 var target *PathError，再调用 errors.As(err, &target)。 运行 go vet，并用包含该类型和不包含该类型的错误树覆盖这条分支。

无意公开依赖错误

修复方法： 在包边界决定调用方是否应该依赖该原因。 如果不应该，就转换为自己的哨兵错误或类型；如果应该，就写入文档，并用包边界测试固定行为。

把错误链当作线性列表

修复方法： 分类时让 errors.Is 和 errors.As 完成标准遍历。 只有诊断工具确实需要访问所有节点时才自行遍历，并分别处理单子节点和多子节点接口。

延伸阅读

• Go errors 包
• Go fmt.Errorf 文档
• Go 博客：Working with Errors in Go 1.13
• Go 1.20 发布说明：多错误
• Go 1.27 发布说明