Go errors.Join生成的错误链如何保留单项匹配能力

当一次操作同时失败于配额校验和下游超时，直接返回其中一个错误会丢失诊断信息；把错误文本拼在一起又无法让调用方可靠判断原因。Go 的 errors.Join 可以把多个 error 组合成一棵错误树，再用 errors.Is 找到某个稳定原因，用 errors.As 取出某个具体类型。关键是匹配错误值或类型，不要比较最终字符串。

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

先用哨兵错误定义可比较的匹配目标

errors.New 每调用一次都会产生独立的错误值，所以不能在返回处临时创建同样文本的错误，再拿它和目标比较。需要跨函数判断的原因，应在包级定义并复用，例如配额不足和超时各有一个固定目标。

package service

import "errors"

// 这些值是稳定的匹配目标；调用方不依赖错误文案。
var (
	ErrQuota   = errors.New("quota exceeded")
	ErrTimeout = errors.New("upstream timeout")
)

// validateAndFetch 同时保留多个独立失败原因。
func validateAndFetch() error {
	var failures []error
	// 这里用 %w 保留可继续匹配的原始错误。
	failures = append(failures, ErrQuota)
	failures = append(failures, ErrTimeout)
	return errors.Join(failures...)
}

这样返回值即使经过多层封装，调用方仍可以写 errors.Is(err, ErrQuota)。判断语义时不要写 err.Error() == "quota exceeded"，因为文案可能会加入上下文，甚至被本地化。

理解 errors.Join 的多子节点结构

errors.Join 接收多个错误，自动丢弃 nil；当所有输入都是 nil 时返回 nil。只要结果非 nil，它就实现 Unwrap() []error，因此组合错误不是一条只能向下走一个节点的链，而是可以包含多个子节点的树。

这也是“保留单项匹配能力”的核心：组合只改变承载方式，没有把子错误变成普通字符串。需要注意，errors.Unwrap(err) 只处理返回单个 error 的方法，不会替你展开 errors.Join 的多错误结果；日常判断应直接使用 errors.Is 或 errors.As。

用 errors.Is 和 errors.As 分别读取原因与类型

errors.Is 适合判断一个语义目标是否出现在错误树中；errors.As 适合找到匹配的具体类型并读取字段。两者都能沿着单错误包装和 errors.Join 的多子节点进行遍历。

type ValidationError struct {
	Reason string
}

func (e *ValidationError) Error() string {
	return e.Reason
}

func inspect(err error) {
	// Is 判断组合结果里是否包含固定业务原因。
	if errors.Is(err, ErrQuota) {
		println("需要提示配额")
	}

	var detail *ValidationError
	// As 找到类型后，detail 才能安全读取结构化字段。
	if errors.As(err, &detail) {
		println(detail.Reason)
	}
}

如果目标是“是否包含某种原因”，优先 Is；如果还需要错误码、字段或上下文，使用 As。一个 Join 结果可以同时满足两种判断，互不冲突。

把 nil、重复目标和 Unwrap 边界纳入排查

还要避免把同一个错误包装成多个看似不同的文本版本。对外返回上下文时使用 fmt.Errorf("fetch user: %w", err) 保留原始关系；需要组合时再统一调用 errors.Join，让上层仍能按原因和类型处理。

相关问题

errors.Join 能不能只匹配第一个错误？

不应依赖位置。errors.Is 和 errors.As 面向的是错误树中的匹配结果，调用方应判断语义或类型，而不是假定某个子项永远排在第一位。

errors.Is 能替代错误字符串比较吗？

对于稳定原因可以替代，而且更能兼容包装和 Join；只有展示给用户时才读取错误文本。

什么时候只返回一个 error 更合适？

如果多个失败项之间没有独立处理价值，或者上层只需要一个明确状态，返回单个带上下文的错误更简单；Join 适合确实需要保留多项诊断的场景。