Go errors.Is 穿透包装层匹配哨兵错误

errors.Is 能穿透包装层，是因为 fmt.Errorf 使用 %w 后会保留底层错误，并提供可展开关系。调用方应使用 errors.Is(err, target)，而不是 err == target 或比较错误文本。标准库说明：https://pkg.go.dev/errors。

一、最小可用写法

package main

import (
    "errors"
    "fmt"
)

var ErrNotReady = errors.New("service not ready")

func loadConfig(name string) error {
    // %w 保留哨兵错误，同时附加配置名称。
    return fmt.Errorf("load config %q: %w", name, ErrNotReady)
}

func main() {
    err := loadConfig("worker")
    // Is 会沿包装链找到 ErrNotReady。
    if errors.Is(err, ErrNotReady) {
        fmt.Println("稍后重试")
    }
}

这里返回给日志的是带上下文的完整错误，而业务分支仍能稳定识别 ErrNotReady。上下文和机器判定互不冲突。

二、errors.Is 如何穿透包装层

一个错误只要实现 Unwrap() error 或 Unwrap() []error，就形成错误树。errors.Is 先检查当前错误，再深度优先检查子节点。普通可比较错误与目标相等时匹配；自定义错误还可以实现 Is(error) bool 定义等价规则。

package main

import (
    "errors"
    "fmt"
)

var ErrDenied = errors.New("permission denied")

func query() error {
    // 第一层记录存储动作。
    inner := fmt.Errorf("read profile: %w", ErrDenied)
    // 第二层记录请求维度，底层身份仍然保留。
    return fmt.Errorf("request 42 failed: %w", inner)
}

func main() {
    fmt.Println(errors.Is(query(), ErrDenied))
}

三、为什么 %v 和重复 errors.New 会失效

%v 只把底层错误格式化进字符串，不建立包装关系；每次调用 errors.New 又会创建新的错误值，即使文本相同也不是同一个哨兵。因此下面两种写法都不能稳定匹配。

package main

import (
    "errors"
    "fmt"
)

var ErrMissing = errors.New("missing")

func main() {
    // %v 只有文本，没有 Unwrap 关系。
    textOnly := fmt.Errorf("load item: %v", ErrMissing)
    fmt.Println(errors.Is(textOnly, ErrMissing))

    // 相同文本不代表相同错误值。
    another := errors.New("missing")
    fmt.Println(errors.Is(another, ErrMissing))
}

四、在服务边界做错误分类

哨兵错误适合表达调用方需要采取动作的稳定类别，例如“未找到”“冲突”“暂不可用”。底层函数用 %w 添加参数、资源或操作上下文，边界层用 errors.Is 映射状态码和重试策略。

package service

import (
    "errors"
    "fmt"
)

var (
    ErrNotFound  = errors.New("not found")
    ErrTemporary = errors.New("temporary failure")
)

func handle(err error) (code int, message string) {
    // 外部响应使用稳定分类，不暴露完整内部错误文本。
    switch {
    case errors.Is(err, ErrNotFound):
        return 404, "资源不存在"
    case errors.Is(err, ErrTemporary):
        return 503, "服务暂不可用"
    default:
        return 500, "内部错误"
    }
}

func load(id string) error {
    // 具体 ID 留给内部日志，分类由哨兵错误提供。
    return fmt.Errorf("load id=%s: %w", id, ErrNotFound)
}

公开一个可包装的哨兵错误等于承诺调用方可以依赖这一分类。若底层实现细节未来可能更换，就不要随意暴露数据库或文件系统的原始哨兵；在模块边界转换为自己的稳定错误。

五、写法对照

六、常见问题

1. 一层包装能用，包装很多层还可以吗？

可以。只要每层都通过 %w 或 Unwrap 方法保留关系，errors.Is 就会继续遍历。

2. 什么时候继续使用 ==？

只有明确知道错误未被包装且只比较当前值时才可使用；库和服务边界通常优先选择 errors.Is。

3. 哨兵错误和具体错误类型如何选择？

只需要回答“属于哪一类”时用哨兵错误；需要读取路径、偏移量等结构化字段时，用具体错误类型配合 errors.As。