errors.Join 组合错误后如何分别判断原始原因

errors.Join 把多个非 nil 错误组合成一个仍然可检查的错误树。判断组合结果时，不要把它当成一条新的错误字符串去比较：对于固定的哨兵原因，使用 errors.Is；对于需要读取字段的具体错误，使用 errors.As。如果多个分支里存在多个同类型错误，errors.As 只会返回遍历过程中遇到的第一个匹配项，此时才需要通过 Unwrap() []error 继续遍历。

下面用一个“批量处理同时出现超时和字段校验失败”的例子，说明这三种判断方式的分工。示例基于 Go 1.20 引入的多错误包装能力，正文配图是静态结构图，不是运行截图。

先确定 errors.Join 组合后的错误形状

errors.Join(errs ...error) 会忽略其中的 nil。如果所有输入都是 nil，返回值就是 nil；只要存在一个非 nil 错误，返回值就会实现 Unwrap() []error，因此 errors.Is 和 errors.As 都能沿着多个子错误检查。

错误文本只适合展示，不适合作为判断依据。组合错误的文本是各个子错误文本按换行连接的结果，文本顺序和显示内容都不应该替代错误契约。

package main

import (
	"errors"
	"fmt"
)

func main() {
	// nil 输入会被 Join 丢弃，两个真实错误仍保留为两个可检查分支。
	err := errors.Join(nil, errors.New("上游超时"), errors.New("字段校验失败"))
	if err == nil {
		// 所有输入都为 nil 时才会走到这里。
		fmt.Println("没有错误")
		return
	}

	// Error() 适合日志展示，不用它来判断某个原始原因是否存在。
	fmt.Println(err.Error())
}

这里的重点是“组合错误仍保留结构”。接下来的判断函数会检查这棵树，而不是只检查最外层的错误类型。

用 errors.Is 判断固定的原始原因

当调用方只关心“是否包含某一种约定原因”时，定义包级哨兵错误，并用 errors.Is 查询。它适合超时、权限不足、资源不存在等稳定分类；即使该原因被 errors.Join 或其他包装层包住，仍然可以被找到。

package main

import (
	"errors"
	"fmt"
)

var ErrUpstreamTimeout = errors.New("上游超时")

func main() {
	// 两个任务同时失败，调用方需要知道是否包含超时原因。
	err := errors.Join(ErrUpstreamTimeout, errors.New("字段校验失败"))

	// Is 检查错误树中是否存在与哨兵错误匹配的分支。
	if errors.Is(err, ErrUpstreamTimeout) {
		fmt.Println("需要按超时策略处理")
	}

	// 直接用 err == ErrUpstreamTimeout 无法穿过 Join 的组合节点。
	fmt.Println(errors.Is(err, errors.New("上游超时"))) // false：新建的错误值不是同一个契约值
}

最后一行特意使用了一个同文本的新错误值。errors.New 每次返回不同的错误值，所以即使文字相同，也不会因为文本相同而匹配。实际项目应复用同一个哨兵值，或让自定义错误通过 Is 方法声明等价关系。

用 errors.As 提取具体错误类型

如果调用方还需要字段，例如失败字段名、状态码或资源路径，就不能只用 errors.Is。可以声明一个目标类型变量，把它的地址传给 errors.As。函数沿错误树查找第一个可赋值给目标类型的错误，并把原始对象写入目标变量。

package main

import (
	"errors"
	"fmt"
)

type FieldError struct {
	Field string
	Reason string
}

func (e *FieldError) Error() string {
	return e.Field + ": " + e.Reason
}

func main() {
	fieldErr := &FieldError{Field: "email", Reason: "格式不正确"}
	err := errors.Join(errors.New("上游超时"), fieldErr)

	var target *FieldError
	// As 找到匹配类型后把原始指针写入 target，随后可以读取业务字段。
	if errors.As(err, &target) {
		fmt.Printf("字段=%s，原因=%s\n", target.Field, target.Reason)
	}
}

注意目标变量的类型。如果错误实现的是 *FieldError，目标就应声明为 var target *FieldError，再传 &target。不要传一个 nil 的 error 接口指针来“猜类型”，那样既不表达目标类型，也容易触发 errors.As 的参数错误。

Is 和 As 的选择可以拆成两句话

一个实用的判断顺序是：先用 Is 判断是否要走某个策略，再用 As 读取该策略需要的字段。这样调用方不会依赖错误文本，也不会把“分类判断”和“字段提取”混在一起。

多个同类型错误时，为什么 As 只拿到一个

errors.As 的语义是找到错误树中第一个匹配目标的错误，并把它返回。它不是“收集所有同类型错误”的 API。errors.Join 的多个分支可能包含多个 *FieldError，如果业务需要显示全部字段，就要明确遍历多错误包装节点。

package main

import (
	"errors"
	"fmt"
)

type FieldError struct {
	Field string
}

func (e *FieldError) Error() string { return e.Field + " 无效" }

// joinedErrors 只描述标准多错误包装提供的 Unwrap 形状。
type joinedErrors interface {
	Unwrap() []error
}

func collectFieldErrors(err error) []*FieldError {
	var result []*FieldError
	if err == nil {
		// nil 不需要继续展开，避免把空错误当成一个原因。
		return result
	}

	if many, ok := err.(joinedErrors); ok {
		// 递归处理每个分支，兼容嵌套 Join。
		for _, child := range many.Unwrap() {
			result = append(result, collectFieldErrors(child)...)
		}
		return result
	}

	var fieldErr *FieldError
	// 叶子节点使用 As，保留包装错误对自定义 As 的支持。
	if errors.As(err, &fieldErr) {
		result = append(result, fieldErr)
	}
	return result
}

func main() {
	err := errors.Join(
		&FieldError{Field: "email"},
		&FieldError{Field: "phone"},
	)
	for _, fieldErr := range collectFieldErrors(err) {
		fmt.Println(fieldErr.Field)
	}
}

这个递归函数只在业务确实需要“所有字段错误”时使用。对于“是否存在某个原因”仍然优先使用 errors.Is，对于“拿到一个可处理的具体错误”仍然优先使用 errors.As，不要为了统一而把所有错误都手动展开。

最后检查四个容易出错的边界

1. 不要比较组合错误的字符串。 文本是给日志和人看的；业务判断应依赖 Is、As 或明确的自定义错误契约。
2. 不要用新建的同文本错误值调用 Is。 哨兵错误应复用同一个变量，或者由错误类型实现匹配规则。
3. 确认 As 的目标类型和指针层级。 错误是 *FieldError 时，目标应为 *FieldError，调用传入它的地址。
4. 先确认是否真的要收集全部分支。 多错误遍历会让返回结构、去重和展示顺序成为调用方责任；只需一个匹配项时不必增加这层复杂度。

常见问题

errors.Join 里有 nil，会影响 errors.Is 吗？

不会。nil 输入会被丢弃；如果所有输入都是 nil，Join 直接返回 nil。对可能为空的组合结果先做 nil 处理，可以让调用方逻辑更清楚。

errors.As 能不能拿到所有同类型错误？

不能。它返回遍历中第一个匹配项。需要全部对象时，识别 Unwrap() []error 并递归遍历每个分支，再由业务决定是否去重和排序。

errors.Is 能判断自定义错误的字段吗？

它更适合判断错误身份或分类。需要读取字段时使用 errors.As；如果必须定义更复杂的匹配规则，可以在自定义错误上实现 Is(error) bool，但仍应保持调用方契约稳定。

记住一句话即可：errors.Join 负责保留多个原因，errors.Is 负责确认某个原因是否存在，errors.As 负责把某个具体原因取出来；只有需要全部同类原因时，才继续展开 Unwrap() []error。