Go errors.Is 为什么匹配不了包装错误：Join、Unwrap 与哨兵错误

线上接口把底层错误包了一层，日志里明明出现了 ErrNotFound，但调用方的 errors.Is 却返回了 false。这类问题通常不是哨兵错误失效，而是错误链在包装时被截断，或者多个错误被组合后没有按错误树来理解。

errors.Is 能否匹配成功，取决于目标错误是否仍位于 Unwrap 展开的链或树中；单个错误用 %w，多个并列错误用 errors.Join，普通的 %v 只会留下文字。

日志里有 ErrNotFound，为什么判断仍然失败

先看一个很容易混入项目的写法。存储层返回哨兵错误，服务层为了补充上下文重新格式化：

var ErrNotFound = errors.New("record not found")

func loadUser() error {
    return ErrNotFound
}

func service() error {
    err := loadUser()
    if err != nil {
        return fmt.Errorf("load user failed: %v", err) // 这里只复制了文字
    }
    return nil
}

func main() {
    err := service()
    fmt.Println(err)
    fmt.Println(errors.Is(err, ErrNotFound)) // false
}

输出看起来很合理，但 %v 没有把原错误挂到包装关系里。此时 err.Error() 中虽然含有 record not found，errors.Is 却没有可遍历的节点。

先做一个最小验证：%w 是否真的保留了错误链

把格式化动词改成 %w，再用同一个哨兵错误验证：

func service() error {
    err := loadUser()
    if err != nil {
        return fmt.Errorf("load user failed: %w", err)
    }
    return nil
}

err := service()
fmt.Println(errors.Is(err, ErrNotFound)) // true
fmt.Println(errors.Unwrap(err) == ErrNotFound) // true

这里的可见成功状态有两个：errors.Is 输出 true，并且 errors.Unwrap 取到的正是 ErrNotFound。如果第一项为 false，不要先改调用方的判断，沿返回路径逐层查找第一个使用 %v 的包装。

errors.Join 不是把错误拼成一段字符串

批量校验时，服务可能同时得到权限错误和字段错误。errors.Join 会保留多个子错误，而不是只选一个作为“主错误”：

var (
    ErrPermission = errors.New("permission denied")
    ErrInvalid    = errors.New("invalid input")
)

err := errors.Join(
    fmt.Errorf("role check: %w", ErrPermission),
    fmt.Errorf("email check: %w", ErrInvalid),
)

fmt.Println(errors.Is(err, ErrPermission)) // true
fmt.Println(errors.Is(err, ErrInvalid))    // true
fmt.Println(err.Error())                   // 两段文本，不能反推遍历结构

检查逻辑应当把 Join 结果看成一棵树：errors.Is 会沿每个分支寻找目标。不能用一次 errors.Unwrap 就假设拿到所有子错误；对多错误结构，直接用 errors.Is 或按约定实现的 Unwrap() []error 处理。

自定义错误类型最容易在哪一层断链

如果项目有自己的错误类型，关键不是字段名，而是它是否把原因暴露给标准库。下面这个类型可以携带操作名，同时继续支持 errors.Is：

type OperationError struct {
    Op  string
    Err error
}

func (e *OperationError) Error() string {
    return e.Op + ": " + e.Err.Error()
}

func (e *OperationError) Unwrap() error {
    return e.Err
}

err := &OperationError{Op: "load user", Err: ErrNotFound}
fmt.Println(errors.Is(err, ErrNotFound)) // true

常见断点有三处：Error 方法直接返回拼好的字符串、Unwrap 忘了实现，以及包装时把原错误放进了普通字段却没有返回它。类型断言和 errors.As 也遵循同一条原则：先保证错误链没有被文字化。

一张排查清单能快速定位匹配边界

实际项目里可以给每个服务层包装补一个小测试：构造目标错误，经过本层函数，再断言 errors.Is 或 errors.As。这个测试比比较整段日志更能锁住错误契约。

常见问题

用 errors.Is 比较两个内容相同的 errors.New 可以吗？

不行。每次调用 errors.New 都会得到不同的错误值，应在需要稳定匹配时定义并复用哨兵错误。

fmt.Errorf 可以同时包装多个错误吗？

现代 Go 代码应根据项目支持的版本确认格式化规则；单个原因使用一个 %w 最清楚，多条并列原因优先使用 errors.Join，并为兼容范围补测试。

为什么不建议 strings.Contains(err.Error(), "not found")？

错误文本会随着上下文、语言和包装层变化。稳定的业务分支应匹配哨兵错误或错误类型，文本只适合日志和人工阅读。

把错误链当成接口的一部分

这次问题的修复点并不在 errors.Is，而在每一层是否承诺保留原因。用 %w 表达单链，用 errors.Join 表达并列分支，自定义错误实现 Unwrap，再用最小测试验证目标错误仍可达，调用方就能稳定地区分“未找到”“无权限”和“参数错误”。