Go errors.Unwrap 为什么不支持多错误返回值

调用 errors.Unwrap(errors.Join(errA, errB)) 得到 nil，通常不是错误丢失，也不是 errors.Join 失效。原因是 errors.Unwrap 的函数签名只处理实现了 Unwrap() error 的单错误包装，而 errors.Join 返回的值实现的是 Unwrap() []error。

多错误不是一条可以不断“取下一个”的链，而是一棵可能有多个子节点的树。要判断其中是否存在某个错误，优先用 errors.Is 或 errors.As；只有确实要枚举全部子错误时，才显式断言 interface{ Unwrap() []error }。

官方文档：https://pkg.go.dev/errors

先确认是不是多错误节点

线上批处理把多个任务错误合并后，监控代码仍沿用单链写法，这是最常见的触发场景。先看错误值支持哪一种方法签名：

type singleUnwrapper interface {
    Unwrap() error // 单错误包装：只有一个直接子错误
}

type multiUnwrapper interface {
    Unwrap() []error // 多错误包装：可能包含多个直接子错误
}

Go 官方 errors 文档把两者都定义为“包装错误”，并说明连续展开后形成错误树。errors.Join 会忽略 nil 参数；只要结果非 nil，它就实现 Unwrap() []error。因此，日志里能看到两条错误信息，并不代表 errors.Unwrap 能返回其中任意一条。

为什么 errors.Unwrap 会返回 nil

errors.Unwrap 的官方定义非常具体：如果参数的类型含有返回 error 的 Unwrap 方法，就调用它，否则返回 nil；文档还特别指出，它不会展开 errors.Join 返回的错误。

errA := errors.New("读取配置失败")
errB := errors.New("连接服务失败")
joined := errors.Join(errA, errB)

next := errors.Unwrap(joined) // 结果为 nil：joined 没有 Unwrap() error
fmt.Println(next)

从 API 形状也能看出边界：errors.Unwrap 只能返回一个 error，而多错误节点有多个平级子节点。若函数擅自选择第一个，就会隐藏其他分支；若把多个错误再次合并后返回，又不能完成“取一个直接子节点”的语义。因此标准库把树遍历交给 Is 和 As，把显式枚举留给调用方。

匹配目标错误优先用 Is 和 As

大多数排障代码真正关心的是“树里是否包含目标错误”或“是否存在某种错误类型”，而不是手工逐层拆开。官方文档说明，Is 与 As 会按深度优先顺序检查错误树，支持 Unwrap() error 和 Unwrap() []error 两种节点。

var ErrRetryable = errors.New("可重试")

func classify(err error) string {
    if errors.Is(err, ErrRetryable) { // 自动搜索单链和多错误树
        return "retry"
    }

    var pathErr *fs.PathError
    if errors.As(err, &pathErr) { // 取得树中首个匹配的具体错误
        return "filesystem"
    }
    return "other"
}

这条处理路径有两个好处：调用方不依赖错误树的内部层级，包装层新增上下文后判断仍然有效；同时不会因为只检查第一个子错误而漏报另一个分支。

确实需要枚举时显式取子节点

告警汇总、批量任务详情或审计日志可能需要列出每个叶子错误。此时可显式识别两类 Unwrap 方法，并递归访问全部节点。要注意：自定义 Unwrap() []error 不应返回包含 nil 的切片。

func walk(err error, visit func(error)) {
    if err == nil {
        return // 空错误不进入遍历
    }
    visit(err)

    switch e := err.(type) {
    case interface{ Unwrap() []error }:
        for _, child := range e.Unwrap() {
            walk(child, visit) // 多错误节点遍历所有直接子节点
        }
    case interface{ Unwrap() error }:
        walk(e.Unwrap(), visit) // 单错误节点继续唯一分支
    }
}

不要在这个遍历里再次调用 errors.Unwrap 处理多错误分支，因为它仍只识别单错误签名。若只是匹配哨兵值或类型，也不要自写遍历，直接使用标准库的 Is、As 更稳妥。

排查时不要把 nil 当成“没有错误”

遇到 errors.Unwrap(joined) == nil，可以按下面顺序快速判断：

• 先记录根错误本身，确认它是否非 nil；
• 断言是否实现 Unwrap() []error，不要只查 Unwrap() error；
• 匹配已知哨兵错误时改用 errors.Is；
• 提取具体类型时改用 errors.As；
• 只有展示所有分支时才枚举子节点，并为日志保留父节点上下文。

如果监控规则曾把 errors.Unwrap 的 nil 解释为“根因不存在”，回滚方式不是放弃 errors.Join，而是先恢复对根错误的完整记录，再把匹配逻辑切换到 Is/As。复盘时检查测试是否同时覆盖单链、多分支、嵌套 Join 和全 nil 输入。

常见追问

errors.Join 里只有一个非 nil 错误时，能用 errors.Unwrap 吗？不能据此假设可以。非 nil 的 Join 结果实现的是 Unwrap() []error，方法签名没有因为元素数量变成单错误版本。

可以直接取切片第一个元素吗？只有业务明确把第一个错误定义为主错误时才适合；通用错误判断应使用 Is 或 As，避免遗漏其他分支。

fmt.Errorf 多个 %w 呢？它同样可能形成多子节点错误，应按错误树处理，而不是假设 errors.Unwrap 会逐个返回。