Go errors.Join 组合错误后如何让 errors.Is 继续匹配

可以继续匹配，关键不是把 errors.Join 的返回值拆成字符串，而是让调用方使用 errors.Is(err, target)。Join 会忽略传入的 nil，并让非 nil 结果实现 Unwrap() []error；errors.Is 会沿着这棵多子错误树检查每个成员。因此，数据库错误和网络错误可以一起返回，调用方仍能准确判断其中是否包含某个可恢复错误。

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

先分清 errors.Join 的匹配对象

errors.Join 解决的是“一个操作有多个独立失败原因”的表达问题。例如批量关闭资源时，多个关闭动作都失败，直接返回第一个错误会丢掉其余信息，而只拼接文本又会让程序无法可靠判断错误类别。Join 同时保留错误值和展示文本：Error() 默认用换行连接各成员的文本，匹配则通过多值 Unwrap 保留。

它的输入顺序只影响展示文本和错误树的子节点顺序，不改变某个成员是否可被 errors.Is 找到。Go 1.20 的发行说明也明确把多错误包装、errors.Is/errors.As 的遍历和 errors.Join 放在同一项标准库变化中。

用 errors.Is 检查每个成员错误

把可被调用方识别的错误定义成包级哨兵值，再把它们传给 errors.Join：

package main

import (
	"errors"
	"fmt"
)

var (
	errQuota = errors.New("quota exceeded")
	errRetry = errors.New("temporary dependency failure")
)

func validateAndCall() error {
	// 两个独立检查都需要保留，nil 成员会由 Join 自动忽略。
	return errors.Join(errQuota, errRetry)
}

func main() {
	err := validateAndCall()
	// 用错误值匹配业务类别，不依赖 Error() 的展示文本。
	fmt.Println(errors.Is(err, errQuota)) // true
	fmt.Println(errors.Is(err, errRetry)) // true
}

errors.Is 先检查当前错误，再按深度优先顺序检查子错误；所以目标是第一个成员还是第二个成员，不需要调用方知道。若成员被 fmt.Errorf("...: %w", err) 再包一层，匹配仍会继续向下。

用 fmt.Errorf 保留外层业务上下文

组合错误通常还需要说明请求、批次或资源范围。可以在 Join 外面增加一层单错误包装：

func finishBatch(batchID string, checks []error) error {
	joined := errors.Join(checks...)
	if joined == nil {
		// 所有检查都没有错误时返回 nil，避免制造假的失败。
		return nil
	}
	// %w 保留 joined 这棵多子错误树，前缀只负责补充业务上下文。
	return fmt.Errorf("batch %s failed: %w", batchID, joined)
}

func canRetry(err error) bool {
	// 调用方只关心是否包含可重试原因，不必解析整段文本。
	return errors.Is(err, errRetry)
}

这里不要把 joined.Error() 塞进 fmt.Errorf 的 %s 占位符，否则外层只得到一段文本，错误树关系会丢失。应让 %w 接收 Join 返回值。

如果一个函数要同时包装多个独立错误，也可以在 Go 1.20 及更高版本使用多个 %w；但对“先收集、后统一返回”的场景，errors.Join 更直接。

处理 nil、重复和自定义匹配边界

实际代码最容易踩的是边界而不是 API 本身：

重复传入同一个错误不会让 errors.Is 变成“匹配两次”的计数器，它只回答是否存在匹配。若业务需要统计每个失败项，应在收集阶段保留带资源标识的记录，再把结构化信息转换成错误，而不是从最终文本反向解析。

还要留意版本边界：errors.Join 是 Go 1.20 加入的 API。若项目的最低 Go 版本低于 1.20，就不能仅靠改写调用方式解决编译问题，应先调整工具链约束，或在兼容层明确实现多错误接口。

相关问题

errors.Join(nil, err) 会返回什么？

会返回包含 err 的非 nil 错误；如果所有参数都是 nil，返回 nil。

为什么 errors.Unwrap(errors.Join(a, b)) 是 nil？

标准库的 errors.Unwrap 只调用返回单个 error 的 Unwrap 方法。Join 返回的是 Unwrap() []error，所以应使用 errors.Is/errors.As，或按需断言多值接口。

把错误文本拼起来还能用 errors.Is 吗？

不能。文本只适合展示和日志；要保留匹配能力，必须保留原始错误值并通过 %w 或 errors.Join 建立包装关系。