Go errors.Is 为什么匹配不到：%w 包装、errors.Join 与自定义错误判定

线上接口把“库存不足”和“库存服务暂时不可用”都返回成了 500，排查时最容易踩的坑，是拿 err.Error() 的字符串去判断错误。Go 里更稳妥的写法是先定义可以长期复用的错误契约，再用 errors.Is 做判定：单层上下文场景用 fmt.Errorf("...: %w", err)，多个校验结果一起返回用 errors.Join，业务类型需要按字段匹配时再实现自定义 Is。

errors.Is 匹配不到，绝大多数情况是你用了普通%v拼接错误丢了底层哨兵、对errors.Join返回的多错误树手动调用Unwrap，或是自定义错误没写对Is/As匹配规则。

先看最小写法：%w 让错误保留可判定性

假设库存服务只有一个需要向上暴露的哨兵错误：

var ErrOutOfStock = errors.New("out of stock")

func reserve(sku string) error {
    if sku == "book-17" {
        return fmt.Errorf("sku %s: %w", sku, ErrOutOfStock)
    }
    return nil
}

err := reserve("book-17")
if errors.Is(err, ErrOutOfStock) {
    // 转成可预期的业务响应，例如 409
}

这里返回文本可以包含 SKU 和上下文信息，但上层不需要去猜字符串内容。errors.Is 会先检查当前错误，再沿着 Unwrap() error 继续向下查找；所以中间再包一层日志上下文，也不会丢掉 ErrOutOfStock。

三个候选方案怎么选：字符串、== 和 errors.Is

三种写法看起来都能完成“判断错误”的需求，但契约强度完全不同：

所以展示文案和程序判断逻辑要分开。日志可以打印 err 的完整上下文，业务分支只依赖明确的哨兵错误或类型。

errors.Join 为什么要用 Is，而不是一路 Unwrap

批量校验时，接口可能同时发现“SKU 不存在”和“数量必须大于 0”两个问题。Go 1.20 提供的 errors.Join 会把多个非空错误组成一棵错误树：

var (
    ErrUnknownSKU = errors.New("unknown sku")
    ErrBadQuantity = errors.New("quantity must be positive")
)

func validate(sku string, quantity int) error {
    var errs []error
    if sku == "" { errs = append(errs, ErrUnknownSKU) }
    if quantity 

这里有个很隐蔽的区别：errors.Unwrap(err) 只处理返回单个 error 的 Unwrap 方法，不会替你展开 Unwrap() []error。所以想检查 Join 后的集合里有没有对应错误分支，直接用 errors.Is；想取出具体类型，则使用 errors.As。

自定义错误：什么时候值得实现 Is 方法

哨兵错误适合固定类别，但有些错误还带有可比较的字段，比如资源类型。这时可以让自定义错误自己决定“目标是否匹配”，而不是把所有字段拼进字符串里做比对：

type PermissionError struct {
    Resource string
    Action   string
}

func (e *PermissionError) Error() string {
    return "permission denied: " + e.Action + " " + e.Resource
}

func (e *PermissionError) Is(target error) bool {
    t, ok := target.(*PermissionError)
    return ok && (t.Resource == "" || t.Resource == e.Resource) &&
        (t.Action == "" || t.Action == e.Action)
}

err := fmt.Errorf("load profile: %w", &PermissionError{Resource: "profile", Action: "read"})
if errors.Is(err, &PermissionError{Resource: "profile"}) {
    // 只关心资源，不要求调用方知道具体动作
}

自定义 Is 的规则要保持简单、稳定、可解释。不要让它做网络请求、读数据库操作，也不要把“近似相等”的业务逻辑塞进来；匹配函数越复杂，调用方越难预判结果。

不适用的情况：别把所有失败都 Join 到一起

errors.Join 适合一次操作确实需要汇总多个独立结果的场景，比如批量字段校验、批量关闭资源。请求一旦遇到鉴权失败，后续数据库错误通常没有继续收集的价值，直接返回带 %w 的上下文会更清晰。

同样，错误类型也不是越多越好。对外只需要稳定区分“可重试、可提示用户、需要告警”的边界时，几个哨兵错误加少量类型就足够。底层驱动的原始错误可以保留在链路中，但不要让上层业务绑定驱动包的每个细节。

用表驱动测试把错误契约锁住

这类问题最怕“代码看着对，换一层包装就失效”。至少要覆盖直接返回、%w 包装、Join 多分支和非匹配目标这几类场景：

func TestErrorContract(t *testing.T) {
    wrapped := fmt.Errorf("reserve: %w", ErrOutOfStock)
    joined := errors.Join(ErrOutOfStock, ErrBadQuantity)
    cases := []struct {
        name string
        got  error
        want error
        ok   bool
    }{
        {"wrapped", wrapped, ErrOutOfStock, true},
        {"joined", joined, ErrBadQuantity, true},
        {"different", wrapped, ErrBadQuantity, false},
    }
    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            if got := errors.Is(tc.got, tc.want); got != tc.ok {
                t.Fatalf("errors.Is() = %v, want %v", got, tc.ok)
            }
        })
    }
}

如果项目仍需兼容 Go 1.19，不能直接依赖 errors.Join；可以先保留单错误包装，或使用项目已有的聚合错误实现，但要确认它是否实现了 Unwrap() []error。升级到 Go 1.20 以后，再把多错误路径纳入兼容矩阵。

相关问题

errors.Is 能比较两个内容相同的 errors.New 吗？

默认不能。每次 errors.New 都生成不同的错误值，应该把哨兵错误保存成包级变量，或使用自定义 Is 明确匹配字段。

errors.As 和 errors.Is 应该怎么分工？

Is 用来判断类别或哨兵错误是否存在，As 用来取出错误树中某个具体类型并读取对应字段。

为什么不建议只比较错误字符串？

字符串是给人看的展示层，可能随着上下文、翻译和日志格式变化；错误契约应该通过包装关系、类型或自定义匹配规则表达。

最后的决策表

• 一个固定类别：定义包级哨兵错误，向上包装时使用 %w。
• 多个独立校验结果：用 errors.Join 聚合，用 errors.Is/errors.As 查询。
• 需要按资源、动作等字段匹配：定义自定义类型和小而稳定的 Is 方法。
• 需要兼容 Go 1.19：先确认工具链版本，再决定是否引入多错误树。

错误信息负责说明发生了什么，错误链负责回答“它属于哪一类”。把这两层分开，接口状态码、重试策略和日志内容才能各自稳定演进。