17370845950

errors.Unwrap 是 Go 1

.13 引入的函数，用于一次性获取错误的直接下一层包装错误，仅对实现 Unwrap() error 方法的错误有效，nil 输入返回 nil，不 panic。

errors.Unwrap 是什么，什么时候该用它

errors.Unwrap 是 Go 1.13 引入的函数，用于获取一个错误的「下一层」错误（即被包装的原始错误）。它只对实现了 Unwrap() error 方法的错误类型有效，比如 fmt.Errorf("...: %w", err) 包装出的错误，或手动实现该方法的自定义错误。

它不是用来“展开所有错误”的递归工具，而是一次性取一层。常见误用是把它当 errors.Cause（旧第三方库概念）用，结果只解了一层就停了。

• 适合场景：检查某错误是否直接包装了特定底层错误（如判断是不是 os.PathError）
• 不适合场景：想一口气拿到最底层原因（得自己循环调用 errors.Unwrap 或用 errors.Is/errors.As）
• 注意：nil 输入会返回 nil，不 panic；但对没实现 Unwrap 的错误（如裸 errors.New），返回 nil

如何安全地逐层展开错误链

Go 标准库不提供内置的「全链展开」函数，必须手动循环。关键是每次调用 errors.Unwrap 后判空，避免无限循环或 panic。

func getAllErrors(err error) []error {
	var errs []error
	for err != nil {
		errs = append(errs, err)
		err = errors.Unwrap(err)
	}
	return errs
}

这个函数返回从外到内的完整错误链（索引 0 是最外层包装，最后一个是底层错误）。实际使用中更推荐用 errors.Is 或 errors.As 直接匹配目标错误，而不是手动展开——除非你需要日志里显示全部中间层。

立即学习“go语言免费学习笔记（深入）”；

• 别用 for err != nil 无条件循环 + errors.Unwrap，某些自定义错误可能返回自身导致死循环
• 展开深度建议设上限（比如 10 层），防止恶意构造的环状错误
• errors.Is 内部就是循环调用 Unwrap，所以优先用它做类型/值判断

为什么 errors.Is 比手写 Unwrap 循环更可靠

errors.Is 不仅处理 Unwrap 链，还兼容实现了 Is(error) bool 方法的错误（例如某些数据库驱动错误会重载此方法做语义等价判断）。这意味着它比纯靠 Unwrap 更健壮。

if errors.Is(err, os.ErrNotExist) {
    // 即使 err 是 fmt.Errorf("read config: %w", os.ErrNotExist)，也能命中
}

• errors.Is(err, target) 会先比较 err == target，再逐层 Unwrap 比较，最后调用 target.Is(err)（如果 target 实现了）
• errors.As(err, &target) 同理，支持 As(interface{}) bool 方法，比手动 errors.Unwrap + 类型断言更安全
• 手写 Unwrap 循环容易漏掉 Is 和 As 提供的额外语义逻辑

自定义错误类型时如何正确支持 Unwrap

如果你写一个包装错误（比如带 traceID 的错误），必须显式实现 Unwrap() error 方法，否则 errors.Unwrap 对它返回 nil，链就断了。

type WrappedError struct {
    msg  string
    err  error
    traceID string
}

func (e *WrappedError) Error() string {
    return e.msg
}

func (e *WrappedError) Unwrap() error {
    return e.err // 必须返回被包装的 error
}

• 返回 nil 表示没有下一层，不是「没实现」；不实现 Unwrap 方法才是「不支持」
• 不要在 Unwrap() 里做日志、网络请求等副作用——它可能被频繁调用
• 如果错误包含多个子错误（如 slice of errors），Unwrap 应只返回第一个或主错误，Go 官方约定不支持多分支展开

错误链真正的复杂点不在 Unwrap 本身，而在你是否清楚每一层是谁包的、为什么包、以及调用方到底需要哪一层的信息。滥用 Unwrap 手动展开，往往说明错误分类或传播方式本身有问题。