Go errors.Join 怎样保留多个失败原因

批量校验用户资料、配置项或多份输入时，最容易踩的坑是循环里反复覆盖 err，最后只剩一个失败原因。Go 的 errors.Join 适合处理“这些检查彼此独立，但调用方希望一次看到全部结果”的场景。

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

结论：用 errors.Join(errs...) 聚合多个非 nil 错误；它返回的错误保留一棵多错误树，使用 errors.Is、errors.As 或 Unwrap() []error 读取，不要指望 errors.Unwrap 展开它。

本文用一个批量检查例子说明这个模式的适用压力、代价和判断边界。

先看问题：为什么最后一个 error 不够

假设一次请求要检查用户名、配额和配置文件。如果每个检查失败都直接给同一个变量赋值，后一次失败会覆盖前一次。调用者只能修复一个问题，再重试请求，反馈回路会变长。

这些检查没有严格的先后依赖，失败原因也应该并列保留，这正是错误聚合模式的适用压力。它和“给单个底层错误补充上下文”不是同一件事：上下文包装强调一条因果链，聚合强调多个并列分支。

典型实现：Join 保留并列失败原因

先把每项检查返回的错误收集起来，再一次性交给 errors.Join。它会忽略 nil；当所有项都是 nil 时，返回值仍然是 nil。

package main

import (
	"errors"
	"fmt"
)

var (
	// 使用哨兵错误，让上层可以按稳定语义判断失败类型。
	ErrName  = errors.New("用户名不合法")
	ErrQuota = errors.New("配额不足")
)

func validate(name string, quota int) error {
	var errs []error
	if name == "" {
		errs = append(errs, ErrName)
	}
	if quota 

结果文本会把各个错误信息用换行拼接，但真正有价值的是错误树：上层不用解析展示文本，就能分别判断 ErrName 和 ErrQuota。

读取方式：多错误树不是一个单链

errors.Join 返回的非空错误实现了 Unwrap() []error。因此可以用类型断言拿到直接子错误；而 errors.Is 和 errors.As 会按错误树继续查找，适合封装在业务判断里。

type multiUnwrapper interface {
	Unwrap() []error
}

func printCauses(err error) {
	if err == nil {
		return
	}
	// Join 使用切片形式的 Unwrap；不要用 errors.Unwrap 代替。
	if grouped, ok := err.(multiUnwrapper); ok {
		for _, cause := range grouped.Unwrap() {
			fmt.Println("cause:", cause)
		}
	}
}

这里的 errors.Unwrap(err) 只支持返回 Unwrap() error 的单链包装，官方文档明确说明它不会展开 Join 产生的多错误。若错误树里混有自定义类型，优先使用 errors.As 取得目标类型，而不是解析字符串。

反例与代价：什么时候不要 Join

如果后一个错误必须建立在前一个错误的结果上，聚合会掩盖因果关系。例如数据库连接失败后再执行查询，查询失败往往只是连接失败的后果，这时应使用 fmt.Errorf("查询用户：%w", err) 形成上下文链。

另一个边界是错误信息展示。Join 会拼接各错误的 Error() 文本，错误数量过多时可能让日志变长；对外响应应先按哨兵错误或自定义类型归类，再决定展示哪些原因，不要把内部错误树原样返回。

实践中可以按三问判断：失败是否彼此独立？调用方是否需要分别判断？错误数量是否有合理上限？三个答案都倾向“是”，再使用 errors.Join；否则优先选择单链包装或在边界处转换错误。

总结：把并列原因交给错误树

errors.Join 解决的是“多个独立操作同时失败，如何不丢信息”的问题。记住三个要点：收集后统一 Join；用 Is、As 或 Unwrap() []error 读取；不要把展示文本当作机器可读协议。这样既能减少无效重试，也能保留错误语义和后续扩展空间。

相关问答

问：errors.Join(nil, nil) 会返回一个空错误吗？
答：不会，所有参数都是 nil 时返回 nil。

问：为什么 errors.Unwrap(err) 取不到 Join 的子错误？
答：它只调用 Unwrap() error 单链方法；Join 使用的是 Unwrap() []error，应使用 errors.Is、errors.As 或类型断言读取。