Go errors.Is 判断包装错误不生效的修复

我第一次遇到 errors.Is 判断不生效，是在服务层给底层错误补充上下文之后：日志里的文字看起来完全一样，判断却从 true 变成了 false。问题通常不在 errors.Is 本身，而在错误链没有建立，或者比较的两个哨兵值根本不是同一个对象。

官方文档：https://pkg.go.dev/errors

这篇只处理三类边界：fmt.Errorf 的 %w 包装、哨兵错误的复用，以及自定义错误的 Is(error) bool。修复思路是保留上下文，但把调用方依赖的稳定语义留在错误链里。

先看包装动词：%w 才会留下错误链

errors.Is(err, target) 会检查当前错误以及通过 Unwrap 连接起来的错误树。用 %v 拼出相同的文字，并不会把原始错误放进这棵树，所以文字相同不能证明判断对象相同。

package main

import (
    "errors"
    "fmt"
)

var errNotReady = errors.New("service is not ready")

func loadConfig(useWrongVerb bool) error {
    if useWrongVerb {
        // %v 只把错误格式化成文字，调用方无法沿 Unwrap 找回哨兵。
        return fmt.Errorf("加载配置失败: %v", errNotReady)
    }
    // %w 把原错误放进包装链，同时保留当前层的上下文。
    return fmt.Errorf("加载配置失败: %w", errNotReady)
}

func handle() {
    err := loadConfig(false)
    // 判断依赖稳定的错误语义，而不是比较展示给人的整段文字。
    if errors.Is(err, errNotReady) {
        fmt.Println("可以进入重试或降级分支")
    }
}

排查时先回到产生上下文的那一层，看最后一个格式化动词是不是 %w。如果底层错误需要被调用方识别，就不要为了“只显示一段文本”改成 %v；展示文本和机器判断是两种需求。

哨兵错误必须复用同一个值

errors.New 每调用一次都会返回一个不同的错误值，即使传入的字符串完全相同。下面这种写法看上去是在比较“同一句错误”，实际上比较的是两个不同实例：

// 反例：函数每次创建新错误，调用方没有稳定的比较目标。
func checkQuota() error {
    return errors.New("quota exceeded")
}

func badMatch(err error) bool {
    // 新建的错误与 checkQuota 返回值不是同一个哨兵。
    return errors.Is(err, errors.New("quota exceeded"))
}

更稳的做法是在拥有该语义的包里声明一个哨兵，所有返回路径都包装或返回它，调用方只引用这个公开目标：

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

func checkQuota(remaining int) error {
    if remaining <= 0 {
        // 返回共享哨兵，允许上层用 errors.Is 识别领域语义。
        return ErrQuotaExceeded
    }
    return nil
}

func saveOrder() error {
    if err := checkQuota(0); err != nil {
        // 添加订单上下文，但不切断原错误链。
        return fmt.Errorf("保存订单失败: %w", err)
    }
    return nil
}

如果调用方需要同时记录订单号，应该把订单号放在外层消息或结构化日志里，而不是复制一个新字符串再比较。这样既有可读上下文，也保留了稳定的程序接口。

需要语义匹配时，实现自定义 Is

有些错误不是一个固定实例，而是同一类领域状态，例如资源名称不同但都表示“资源已存在”。这时可以让错误类型实现 Is(error) bool，让它声明自己与某个公开哨兵等价。官方建议这个方法只做当前值与目标值的浅比较，不要在里面继续调用 Unwrap。

var ErrConflict = errors.New("resource conflict")

type ResourceConflict struct {
    Resource string
}

func (e ResourceConflict) Error() string {
    return "资源冲突: " + e.Resource
}

func (e ResourceConflict) Is(target error) bool {
    // 只表达当前类型与公开语义的等价关系，不递归检查其他错误。
    return target == ErrConflict
}

func upsert(name string) error {
    // 资源名是上下文，ErrConflict 是调用方稳定依赖的语义。
    return fmt.Errorf("写入 %s: %w", name, ResourceConflict{Resource: name})
}

func handleConflict() {
    if err := upsert("order-17"); err != nil {
        // errors.Is 会经过包装层并调用 ResourceConflict.Is。
        if errors.Is(err, ErrConflict) {
            fmt.Println("改走冲突处理")
        }
    }
}

这里不要把 ResourceConflict.Is 写成“只要目标的文字相同就算匹配”。错误文本是面向人的描述，哨兵或类型才是面向调用方的契约；开放的比较规则越宽，后续越容易把不相关的失败归到同一个分支。

把修复收敛成一张判断表

我现在会按这个顺序排查：先找错误被包装的那一层，再确认目标哨兵是否复用，最后才看自定义 Is 是否覆盖了预期目标。这样通常不需要改动业务分支，只需修复错误链和错误契约。

常见问题

把 fmt.Errorf("%w", err) 再包一层会失效吗？

不会。只要每层都使用 %w，errors.Is 可以沿着连续的包装链查找目标。

自定义 Is 里可以比较错误文字吗？

技术上可以，但不建议把文案当作契约。更稳的是比较公开哨兵、固定字段或明确的领域属性，并保持匹配范围足够窄。

已经用了 %v，还能从文字恢复原错误吗？

不能可靠恢复。原错误没有进入链时，后续只能回到产生错误的位置改用 %w，或显式返回一个新的、可识别的领域错误。

总结一下：errors.Is 判断包装错误的关键不是错误文字，而是可遍历的错误链和稳定的比较目标。用 %w 保留链，用共享哨兵表达固定语义，需要跨实例匹配时再用自定义 Is，错误判断就不会随着上下文文案变化而漂移。