Go errors.Join 之后 errors.Is 怎么匹配多个原因

errors.Join 返回的是一个包装多个子错误的错误树。对 Join 结果调用 errors.Is(joined, target) 时，Go 会先检查 joined 本身，再按深度优先顺序遍历每个 Unwrap() []error 子树；只要任意节点匹配 target，就返回 true。因此多个原因要分别调用一次 errors.Is。

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

故障现场：日志里有两个原因，判断却一个都没命中

一个批处理任务结束时，需要同时清理缓存和释放分布式锁。两个动作都可能失败，因此代码用 errors.Join 合并错误。日志能看到两条原因，但旧代码仍用直接等号判断，结果告警分类全部落入“未知错误”。

package cleanup

import "errors"

var (
	ErrCache = errors.New("cache cleanup failed")
	ErrLock  = errors.New("lock release failed")
)

func finish(cacheErr, lockErr error) error {
	// Join 会忽略 nil，因此调用方可以直接汇总两个独立清理结果。
	return errors.Join(cacheErr, lockErr)
}

触发条件是两个清理动作同时失败。此时返回值既不等于 ErrCache，也不等于 ErrLock，因为最外层值是新的 joined error。问题不在 Join 丢了原因，而在调用方仍把错误当成单一值比较。

Join 把错误链扩展成错误树

Go 1.20 开始支持一个错误包装多个错误：类型只要实现 Unwrap() []error，就能构成多分支错误树。errors.Join 的非 nil 结果正是这种结构。每个子错误还可以继续通过 Unwrap() error 或 Unwrap() []error 包装下一层。

errors.Is 的查找顺序是先检查当前错误，再对多子节点做深度优先遍历。匹配条件不只是相等：如果某个错误实现了 Is(error) bool，也可以声明与目标错误等价。

修复方式：对每个业务原因分别调用 errors.Is

如果缓存失败和锁释放失败会触发不同处理，就分别匹配两个哨兵错误。两个判断可以同时为 true，不要写成互斥的 if ... else if，除非业务明确只处理一个最高优先级原因。

package cleanup

import (
	"errors"
	"fmt"
)

func classify(err error) []string {
	var reasons []string

	// 每个目标独立匹配，因为同一个 Join 结果可能同时包含多个原因。
	if errors.Is(err, ErrCache) {
		reasons = append(reasons, "cache")
	}
	if errors.Is(err, ErrLock) {
		reasons = append(reasons, "lock")
	}

	// 保留未知错误线索，避免没有命中哨兵错误时静默丢失。
	if len(reasons) == 0 && err != nil {
		reasons = append(reasons, fmt.Sprintf("unknown: %v", err))
	}
	return reasons
}

若 cacheErr 是 fmt.Errorf("remove key: %w", ErrCache)，Is 仍会沿该分支继续解包并命中 ErrCache。因此上层可以增加上下文，而不必牺牲机器可判断的错误身份。

根因之一：errors.Unwrap 不会展开 Join

另一个常见修复尝试，是循环调用 errors.Unwrap 枚举原因。这个方法对 Join 不生效。标准库文档说明，errors.Unwrap 只调用 Unwrap() error，不会调用 Join 使用的 Unwrap() []error。

package cleanup

import "errors"

func directChildren(err error) []error {
	// 多错误包装需要显式识别 Unwrap() []error 接口。
	multi, ok := err.(interface{ Unwrap() []error })
	if !ok {
		return nil
	}

	// 返回的是直接子节点；业务匹配通常仍应优先使用 errors.Is 或 errors.As。
	return multi.Unwrap()
}

大多数业务并不需要手工遍历错误树。判断“是否包含某个原因”用 errors.Is，提取“是否包含某种错误类型”用 errors.As。只有需要展示全部直接子错误、结构化记录每个原因时，才考虑识别 Unwrap() []error。

类型错误用 errors.As 获取第一个匹配

如果某个原因携带字段，不应只匹配哨兵错误。errors.As 会按同样的错误树顺序找到第一个可赋值给目标类型的错误，并把它写入 target。

package cleanup

import (
	"errors"
	"fmt"
)

type RetryError struct {
	AfterSeconds int
}

func (e *RetryError) Error() string {
	return fmt.Sprintf("retry after %d seconds", e.AfterSeconds)
}

func retryDelay(err error) (int, bool) {
	var target *RetryError
	// As 在多分支错误树中返回第一个匹配的 RetryError。
	if !errors.As(err, &target) {
		return 0, false
	}
	return target.AfterSeconds, true
}

“第一个匹配”取决于错误树的前序深度优先顺序。如果 Join 中可能出现多个同类型错误，而业务需要全部提取，就要明确遍历策略；不要误以为一次 As 会返回所有匹配项。

防复发测试要覆盖多命中和 nil

package cleanup

import (
	"errors"
	"fmt"
	"testing"
)

func TestJoinedReasons(t *testing.T) {
	joined := errors.Join(
		fmt.Errorf("clear session: %w", ErrCache),
		fmt.Errorf("unlock job: %w", ErrLock),
		nil, // nil 会被 Join 忽略，不形成额外分支。
	)

	// 同一个结果应当同时匹配两个哨兵错误。
	if !errors.Is(joined, ErrCache) || !errors.Is(joined, ErrLock) {
		t.Fatalf("joined error lost a cause: %v", joined)
	}

	// errors.Unwrap 不展开 Unwrap() []error，这是标准库的既定行为。
	if errors.Unwrap(joined) != nil {
		t.Fatal("errors.Unwrap unexpectedly expanded joined error")
	}

	// 全部参数为 nil 时，Join 必须返回 nil。
	if errors.Join(nil, nil) != nil {
		t.Fatal("all-nil join should be nil")
	}
}

这组测试固定了本次故障的关键约束：多个原因可以同时命中，嵌套上下文不会破坏哨兵身份，nil 不会制造伪错误，手工单链 Unwrap 不能替代错误树匹配。

防复发清单

• 合并独立失败时用 errors.Join，不要只拼字符串。
• 业务分支用 errors.Is 或 errors.As，不要对 wrapped 或 joined error 直接使用 ==。
• 多个原因可以同时成立时使用多个独立 if。
• 保留每个子错误的上下文，但继续用 %w 包装。
• 需要枚举结构时区分 Unwrap() error 与 Unwrap() []error。

相关问题

errors.Is 会只检查 errors.Join 的第一个错误吗？

不会。它会检查 Join 的所有子树，只要任意节点匹配 target 就返回 true。

errors.Join 的错误顺序会影响 errors.Is 吗？

对布尔匹配结果通常不影响；对 errors.As 的“第一个匹配”会有影响，因为遍历按子错误顺序做前序深度优先搜索。

fmt.Errorf 可以一次包装多个错误吗？

从 Go 1.20 起，一个格式字符串可出现多个 %w，返回值同样会包装多个错误，Is 和 As 会检查这些分支。

Join 会把嵌套的 Join 自动拍平成一层吗？

不应依赖扁平化假设。把结果视为错误树，并通过 Is、As 或明确的树遍历处理，能正确覆盖嵌套结构。