Go errors.Unwrap 为什么不能直接展开 errors.Join

errors.Unwrap 不能直接展开 errors.Join，不是 Join 丢失了子错误，而是两个 API 使用了不同的方法签名。errors.Unwrap 只调用 Unwrap() error；Join 返回的非 nil 错误实现的是 Unwrap() []error。因此对 Join 结果调用 errors.Unwrap 会得到 nil。

官方地址：https://pkg.go.dev/errors

先明确目标：你想“匹配”还是“枚举”

很多代码把 errors.Unwrap 当成通用的“取出内部错误”函数，但它最初解决的是单链包装。Join 表达的是一棵可能有多个分支的错误树，一个返回值无法代表所有下一层节点，所以标准库没有让 errors.Unwrap 随意挑选其中一个。

这一步很重要：大多数业务判断只需要 Is 或 As，不需要把整棵树摊平。只有日志聚合、批量展示、结构化上报等场景，才值得显式枚举。

两种 Unwrap 签名代表两种结构

单链包装类型通常实现 Unwrap() error。例如 fmt.Errorf("read config: %w", err) 的外层错误只有一个直接原因，沿着 Unwrap 一次只会走到一个下一节点。

errors.Join 则可能同时包装多个非 nil 错误，所以它实现 Unwrap() []error。标准库文档明确说明：Join 会丢弃 nil；所有输入都是 nil 时返回 nil；非 nil 结果可以由 Is 和 As 检查。

errors.Unwrap 的实现只做一次接口断言：目标是否实现 Unwrap() error。Join 没有这个方法，因此断言失败并返回 nil。这种行为避免了含糊选择：如果 Join 有三个子错误，Unwrap 不应该擅自返回第一个、最后一个或重新合成一个结果。

用最小代码确认返回 nil 的含义

package main

import (
	"errors"
	"fmt"
)

func main() {
	errRead := errors.New("read failed")
	errClose := errors.New("close failed")
	joined := errors.Join(errRead, errClose)

	// Unwrap 只识别 Unwrap() error，因此这里返回 nil。
	fmt.Println(errors.Unwrap(joined) == nil)

	// Is 能遍历 Unwrap() []error，所以两个原因都可以分别命中。
	fmt.Println(errors.Is(joined, errRead))
	fmt.Println(errors.Is(joined, errClose))
}

第一行判断为 true，不代表 joined 内部为空。它只说明 joined 不符合 errors.Unwrap 接受的单子节点接口。后两次 Is 会把错误视为树，检查根节点并深度优先访问子树。

推荐流程：业务判断优先使用 Is 和 As

如果调用方只是要决定是否重试、是否返回特定状态码或是否记录某类告警，就不要手动拆 Join。让标准库处理单链和多分支两种结构，代码更短，也能兼容子错误继续被 fmt.Errorf 包装的情况。

package cleanup

import (
	"errors"
	"fmt"
)

var ErrTemporary = errors.New("temporary cleanup failure")

type PathError struct {
	Path string
	Err  error
}

func (e *PathError) Error() string { return e.Path + ": " + e.Err.Error() }
func (e *PathError) Unwrap() error { return e.Err }

func classify(err error) (retry bool, path string) {
	// Is 负责在整棵错误树中匹配哨兵错误。
	retry = errors.Is(err, ErrTemporary)

	var target *PathError
	// As 返回深度优先遍历中第一个匹配的 PathError。
	if errors.As(err, &target) {
		path = target.Path
	}
	return retry, path
}

func example() error {
	pathErr := &PathError{Path: "cache.db", Err: ErrTemporary}
	// Join 可以把带上下文的路径错误与另一个独立错误一起返回。
	return errors.Join(pathErr, fmt.Errorf("release lock: %w", errors.New("timeout")))
}

As 只返回第一个匹配类型。如果业务需要取得树中所有同类型错误，就进入“枚举”场景，不能连续调用 As 期待它自动给出下一项。

确实要枚举时，先读取直接子错误

只想展示 Join 的直接原因时，可以断言多子节点接口。这比写递归更符合“只看第一层”的目标，也不会把嵌套包装中的上下文意外打散。

package errtree

func DirectChildren(err error) []error {
	if err == nil {
		return nil
	}

	// 多错误包装通过 Unwrap() []error 暴露直接子节点。
	multi, ok := err.(interface{ Unwrap() []error })
	if !ok {
		return nil
	}

	// 复制切片，避免调用方修改包装类型持有的内部切片。
	children := multi.Unwrap()
	return append([]error(nil), children...)
}

这个函数不会把 fmt.Errorf 的单个子错误混入结果，也不会递归展开嵌套 Join。它回答的是“这个多错误节点直接包装了谁”。如果传入的是普通单链错误，返回 nil 是正常边界，不表示没有更深层原因。

需要访问整棵树时，同时处理两种接口

日志聚合器或调试工具可能确实需要访问全部节点。遍历器要同时识别 Unwrap() error 和 Unwrap() []error，并明确访问顺序。下面采用前序深度优先：先访问当前节点，再访问子节点。

package errtree

func Walk(err error, visit func(error) bool) bool {
	if err == nil {
		return true
	}

	// 回调返回 false 时立即停止，便于调用方短路查找。
	if !visit(err) {
		return false
	}

	switch current := err.(type) {
	case interface{ Unwrap() []error }:
		// 多分支节点按切片顺序深度优先访问。
		for _, child := range current.Unwrap() {
			if child != nil && !Walk(child, visit) {
				return false
			}
		}
	case interface{ Unwrap() error }:
		// 单链节点只有一个下一层原因。
		return Walk(current.Unwrap(), visit)
	}
	return true
}

标准错误包装应形成有限、无环的树。若遍历器还要接受不受信任的自定义 error 实现，应额外设计深度上限或循环防护；不要假设任意第三方类型都遵守良好结构。

检查点：用测试固定四个关键边界

package errtree_test

import (
	"errors"
	"fmt"
	"testing"
)

func TestJoinAndUnwrapBoundaries(t *testing.T) {
	errA := errors.New("A")
	errB := errors.New("B")
	joined := errors.Join(fmt.Errorf("wrapped: %w", errA), errB, nil)

	// errors.Unwrap 不展开实现 Unwrap() []error 的 Join 结果。
	if errors.Unwrap(joined) != nil {
		t.Fatal("errors.Unwrap should not choose one Join child")
	}

	// Is 必须能穿过单链包装并访问 Join 的两个分支。
	if !errors.Is(joined, errA) || !errors.Is(joined, errB) {
		t.Fatal("errors.Is did not inspect the complete error tree")
	}

	// Join 丢弃 nil，但保留两个非 nil 直接子项。
	children := joined.(interface{ Unwrap() []error }).Unwrap()
	if len(children) != 2 {
		t.Fatalf("unexpected direct child count: %d", len(children))
	}

	// 输入全部为 nil 时，Join 本身返回 nil。
	if errors.Join(nil, nil) != nil {
		t.Fatal("all-nil Join should return nil")
	}
}

测试关注的是 API 合同，不依赖错误字符串的换行格式做业务判断。错误文本适合展示，人机可读内容不应该替代 Is、As 或明确的结构访问。

常见误区

• 把 nil 当作“没有子错误”：errors.Unwrap(joined) 返回 nil 只表示方法签名不匹配。
• 只取第一个直接子项：这会静默丢失其他原因，也会让代码依赖 Join 参数顺序。
• 用字符串切行还原子错误：Join 的 Error 文本用于展示，不是稳定的结构化协议。
• 业务判断先摊平错误树：若只是匹配原因或类型，Is 和 As 已经提供正确遍历语义。
• 假定 Join 自动拍平嵌套树：把结构当作树处理，不依赖是否扁平化的猜测。

速查表

相关问题

errors.Unwrap(errors.Join(err)) 为什么仍然是 nil？

即使 Join 只有一个非 nil 参数，其返回类型仍实现 Unwrap() []error，而不是 Unwrap() error。

怎样拿到 errors.Join 的直接子错误？

断言 interface{ Unwrap() []error } 后调用其 Unwrap 方法。若还要展开嵌套包装，再显式递归。

errors.Is 会检查 Join 的所有分支吗？

会。它先检查根节点，再按深度优先顺序检查多子节点错误树，任一节点匹配目标就返回 true。

可以依赖 Join 错误文本中的换行拆分吗？

不建议。文本是展示结果，无法可靠保留具体类型、嵌套层级和 Is/As 语义；结构化处理应使用错误接口。