Go errors.Is 为什么匹配不到自定义包装错误

很多人看到 errors.Is(err, target) 返回 false，第一反应是“自定义错误没有实现对”。更常见的根因其实有三个：包装时用了 %v，自定义类型没有把 Is(target error) 放在实际返回的动态类型上，或者比较的目标根本不是该方法认可的类型。errors.Is 不按错误字符串匹配，它检查错误树中的节点、Unwrap 关系和自定义匹配规则。

排查时先确认包装链，再确认动态类型和方法集，最后看 Is 是否只比较了它承诺支持的目标。只要其中一层断开，外层错误再像，errors.Is 也不会命中。

先把 errors.Is 的匹配树拆开

先看一个最小现场。下面两个返回值打印出来可能很像，但只有第一个仍然携带底层错误：

package main

import (
    "errors"
    "fmt"
)

var errQuota = errors.New("quota exceeded")

func main() {
    wrapped := fmt.Errorf("save report: %w", errQuota)
    textOnly := fmt.Errorf("save report: %v", errQuota) // 只保留文本，不建立 Unwrap 关系

    fmt.Println(errors.Is(wrapped, errQuota))  // true：%w 让目标位于错误树中
    fmt.Println(errors.Is(textOnly, errQuota)) // false：%v 没有底层节点
}

errors.Is 会先看当前错误，再沿 Unwrap() error 或 Unwrap() []error 形成的树继续检查。对目标的默认判断是可比较值相等；如果当前节点实现了 Is(error) bool，它也可以声明自己与某个目标等价。

所以遇到“包装后匹配不到”，先不要修改 Is。沿着返回路径找一次：是否把 %w 写成了 %v，自定义包装类型是否实现了正确签名的 Unwrap() error，最终传给 errors.Is 的目标是否就是你想暴露的哨兵错误。

自定义 Is 方法最容易失效的地方

自定义 Is 不是“比较两个错误字符串”的钩子，而是错误类型对目标集合的明确承诺。下面的实现把业务码作为匹配依据，并统一使用指针返回：

package quota

import (
    "errors"
    "fmt"
)

var ErrQuota = errors.New("quota exceeded")

type QuotaError struct {
    Code string
    Err  error
}

func (e *QuotaError) Error() string { return fmt.Sprintf("%s: %v", e.Code, e.Err) }

func (e *QuotaError) Unwrap() error { return e.Err } // 保留底层错误，支持继续遍历

func (e *QuotaError) Is(target error) bool {
    // 只声明业务等价关系，不递归调用 errors.Is，避免把职责混在一起
    return target == ErrQuota && e.Code == "quota"
}

func Load() error {
    // 返回的动态类型是 *QuotaError，与 Is 的指针接收者一致
    return &QuotaError{Code: "quota", Err: ErrQuota}
}

这里既可以匹配 ErrQuota，也可以沿 Unwrap 找到它。真正容易出错的是方法集和目标类型：

例如 Is 写成指针接收者，而函数却返回 MyError{...} 这个值，那么该值可能只满足 Error()，不满足带指针方法的自定义匹配。反过来，若 Error 只写成指针接收者，直接返回值甚至不能通过 error 接口赋值。不要靠改一颗星号试错，先列出“构造表达式的动态类型”和“方法接收者”再对照。

用小测试把三类失败一次分开

修复后建议保留一组短测试，不要只测试 Error() 的打印结果。尤其要把 %v 的“看起来正确”案例固定下来：

func TestLoadError(t *testing.T) {
    cases := []struct {
        name string
        err  error
        want bool
    }{
        {"direct", ErrQuota, true},
        {"wrapped", fmt.Errorf("load: %w", Load()), true},
        {"text only", fmt.Errorf("load: %v", ErrQuota), false}, // 文本相同也不代表可解包
    }

    for _, tc := range cases {
        t.Run(tc.name, func(t *testing.T) {
            if got := errors.Is(tc.err, ErrQuota); got != tc.want {
                t.Fatalf("errors.Is() = %v, want %v", got, tc.want)
            }
        })
    }
}

这组断言分别验证直接节点、保留关系的包装和只有文本的错误。若项目中的目标是错误模板，则把第三个参数换成实现了 Is 规则的目标值，并单独覆盖值/指针构造，避免测试只是在复现当前实现。

相关问题

errors.Is 会比较 Error() 返回的字符串吗？

不会。字符串只是展示文本；默认匹配看错误值是否相等，或者看错误节点的 Is(target error) 是否返回 true。

自定义包装类型一定要实现 Unwrap 吗？

不一定。若只想通过自定义 Is 暴露一个稳定哨兵，可以不解包；若还要让调用方发现底层错误，就应实现 Unwrap 或使用 %w。

为什么改成 fmt.Errorf("%w") 仍然匹配不到？

继续看动态类型和目标：外层可能包的不是你传入的那个错误，或者自定义 Is 没在返回值的方法集里。用上面的三组测试先把包装链和方法集拆开。

总结

errors.Is 匹配不到自定义包装错误时，按“关系、方法集、目标”三层排查：%w 或 Unwrap 是否保留错误树；返回的值/指针是否真的拥有 Is；Is 是否认可当前目标。最后用直接错误、%w 和 %v 三个对照测试把结论锁住。