Go errors.Join保留多个失败原因并支持errors.Is判断

当一个函数同时做多个清理动作时，直接把后一次错误赋给 err，很容易丢掉前一次失败原因。更稳妥的做法是把每个非 nil 错误先收集起来，最后用 errors.Join 合并；调用方仍然可以用 errors.Is 判断其中是否包含目标错误，而不是解析拼接后的字符串。

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

errors.Join 的核心价值是“展示上合并，判断上分叉”：返回值可以作为一个 error 传递，但内部保留多个子错误。所有输入都是 nil 时它返回 nil，因此成功路径不需要额外清理聚合结果。

先把会被覆盖的清理错误拆开

以批量写入后的收尾为例，提交动作和关闭动作都可能失败。若只保留最后一次赋值，调用方无法知道提交成功后是否又在关闭阶段失败。先用切片保存错误，顺序也会跟着操作顺序保留下来。

package task

import "errors"

var (
	ErrCommit = errors.New("commit failed")
	ErrClose  = errors.New("close failed")
)

func finish(commit func() error, closeFn func() error) error {
	var errs []error
	// 每一步独立记录，避免后一个清理错误覆盖前一个错误。
	if err := commit(); err != nil {
		errs = append(errs, err)
	}
	// 关闭动作即使在提交失败后也要执行，保证资源有机会释放。
	if err := closeFn(); err != nil {
		errs = append(errs, err)
	}
	// Join 会过滤 nil；切片为空时返回 nil，保持成功语义。
	return errors.Join(errs...)
}

这里没有把 ErrCommit 和 ErrClose 转成文本再拼接。错误值本身被保留，后续可以按语义分类处理。

errors.Join 的 nil 规则决定返回值是否干净

errors.Join(errs...) 会忽略传入的 nil。如果切片里没有任何非 nil 错误，结果就是 nil；这使得“多个可选收尾动作”可以直接返回聚合结果，不必再写一层 if len(errs) == 0。但要注意，空切片和全 nil 切片都代表没有失败，不应把它们当成一个可打印的空错误。

另一个容易忽略的点是错误文本会按子错误的 Error() 结果用换行连接。这适合日志或人工查看，不适合作为业务判断条件。日志顺序可以帮助定位先后，但不能替代错误类型。

用 errors.Is 判断聚合结果中的具体原因

多错误结果会通过 Unwrap() []error 暴露错误树，errors.Is 会沿树检查每个子错误。因此无论提交失败、关闭失败，还是两者同时失败，调用方都可以保留稳定的分支。

func classify(err error) string {
	// Is 判断错误语义，不依赖 Join 生成的换行文本。
	commitFailed := errors.Is(err, ErrCommit)
	closeFailed := errors.Is(err, ErrClose)

	switch {
	case commitFailed && closeFailed:
		return "提交与关闭都失败"
	case commitFailed:
		return "提交失败，需要重试业务操作"
	case closeFailed:
		return "关闭失败，需要检查资源回收"
	default:
		return "没有匹配到已知原因"
	}
}

如果某个底层错误需要带字段，例如文件名、分片编号或远端状态码，应定义结构化错误并用 errors.As 提取。不要先调用 err.Error()，再用字符串包含关系猜测类型。

上下文放在外层，机器判断留在内层

聚合前可以为每个子错误补充动作上下文，例如“关闭临时文件：%w”。这样日志能说明失败发生在哪一步，而 errors.Is 仍然可以穿透包装。聚合之后也可以再包一层总上下文，但不要改变哨兵错误的身份。

package task

import (
	"errors"
	"fmt"
)

func finishWithContext(commit func() error, closeFn func() error) error {
	var errs []error
	// %w 保留底层身份，调用方仍可用 errors.Is 判断。
	if err := commit(); err != nil {
		errs = append(errs, fmt.Errorf("提交批次：%w", err))
	}
	if err := closeFn(); err != nil {
		errs = append(errs, fmt.Errorf("关闭资源：%w", err))
	}
	// 空切片直接返回 nil，避免把成功路径包装成非 nil 错误。
	if len(errs) == 0 {
		return nil
	}
	// 外层上下文说明整体阶段，内层错误负责精确分类。
	return fmt.Errorf("收尾阶段：%w", errors.Join(errs...))
}

上面的示例需要额外导入 fmt。生产代码里应确认 errors.Join 本身不是 nil 后再包裹；否则空错误会被包装成非 nil，破坏成功路径。

版本与接口边界要先定清楚

errors.Join 从 Go 1.20 开始提供，errors.Is 和 errors.As 则会识别单错误和多错误的解包树。若项目还要编译到 Go 1.19 或更早版本，不能只在源码里替换函数名；需要选择自有聚合错误实现、兼容库，或把最低 Go 版本一起提升。

兼容判断还包括日志契约：Join 的文本包含换行，监控系统若把完整字符串当作一个标签，可能造成高基数或规则失效。建议日志记录错误分类和关键字段，完整错误文本只作为消息。

常见问题

errors.Join 会不会把 nil 变成错误？

不会。nil 输入会被丢弃，所有输入都是 nil 时返回 nil。

能用字符串判断 Join 后的错误吗？

不建议。文本只是多个 Error 字符串的换行拼接，应使用 errors.Is 或 errors.As 判断语义。

errors.Is 能判断 Join 里的多个错误吗？

可以。它会遍历多错误解包树，命中任意匹配的子错误就返回 true。

什么时候不该使用 errors.Join？

如果后一个错误明确覆盖前一个错误，或调用方只需要一个主因，就应保留单一错误并把其他信息作为上下文；不要为了“信息更多”无条件聚合。