Go errors 用 Is 处理多层 Unwrap

在服务层给错误补充上下文后，直接用 == 比较底层哨兵错误很容易失效。Go 的 errors.Is 解决的是“错误被包了几层，仍然能不能按原因分类”这个问题：它会检查当前错误以及由 Unwrap 暴露出的错误链；errors.Unwrap 则只负责取下一层。

官方资料：https://pkg.go.dev/errors、https://go.dev/blog/go1.13-errors。

errors.Is(err, target) 适合做错误分类判断；errors.Unwrap(err) 适合需要查看下一层时使用。只要包装时保留了 %w，外层上下文不会阻断底层哨兵错误的匹配。

多层错误链为什么适合用 errors.Is

一个请求常常经过仓储层、业务层和接口层。底层知道“记录不存在”，业务层想补充查询条件，接口层还要说明当前请求动作。如果每层都把错误改写成新的文本，最外层就只能猜字符串；如果每层使用 %w 包装，原始原因会留在链里。

package main

import (
    "errors"
    "fmt"
)

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

func loadUser() error {
    // 用 %w 保留底层错误，调用方才能继续用 errors.Is 判断。
    return fmt.Errorf("load user from repository: %w", ErrNotFound)
}

func handleRequest() error {
    if err := loadUser(); err != nil {
        // 第二层仍然保留错误链，只增加当前业务动作。
        return fmt.Errorf("handle profile request: %w", err)
    }
    return nil
}

func main() {
    err := handleRequest()
    // Is 会检查外层错误和多层 Unwrap 后的目标。
    if errors.Is(err, ErrNotFound) {
        fmt.Println("可以返回资源不存在")
    }
}

这里的返回值仍然包含两层上下文，但分类判断不需要知道中间经过了几个函数。图中上方是负责补充语境的包装边界，下方是负责提供原因和判断的错误边界；它表达的是静态关系，不是运行截图。

用 %w 连接上下文，用 %v 只保留文字

fmt.Errorf 中的 %w 是这条链能否被检查的关键。若改成 %v，打印出来的错误文本可能看起来一样，但新错误不会把原始值作为可解包的底层错误交给 errors.Is。

func wrapForLog(err error) (error, error) {
    // %w 适合需要让上层继续分类的边界。
    keepChain := fmt.Errorf("query failed: %w", err)

    // %v 只适合明确不希望暴露底层错误语义的文本边界。
    loseChain := fmt.Errorf("query failed: %v", err)
    return keepChain, loseChain
}

工程代码里通常应该把 %w 当作默认选择，再根据 API 契约决定是否在对外边界隐藏底层原因。隐藏原因不等于把字符串当作分类协议；可以返回稳定的业务错误，也可以在日志中保留上下文。

errors.Unwrap 与 errors.Is 的职责边界

errors.Unwrap(err) 只调用一次错误的 Unwrap 方法，因此结果可能仍然是一个包装错误。手写循环既容易漏掉自定义匹配，也会让分类逻辑和错误树结构耦合。需要知道“是否属于某个原因”时，直接调用 errors.Is 更清楚。

import (
    "context"
    "errors"
)

func classify(err error) string {
    // 先判断稳定的哨兵错误，不依赖完整错误文本。
    switch {
    case errors.Is(err, ErrNotFound):
        return "not-found"
    case errors.Is(err, context.Canceled):
        return "canceled"
    default:
        return "unknown"
    }
}

如果确实要读取一层，例如调试一个自定义包装类型，可以暂存 errors.Unwrap(err) 的结果；但不要把“取下一层”误当成“已经判断完整错误链”。另外，Go 的错误树还支持返回 []error 的 Unwrap，聚合错误应继续交给 errors.Is 处理，而不是假设只有一条链。

写错误判断时的三个边界

• 目标要稳定：哨兵错误应代表可被调用方依赖的语义；不要把临时日志文本当成 API。
• 包装要有意图：需要保留原因就用 %w，不需要暴露底层语义时应在接口设计上给出明确的替代错误。
• 分类与展示分开：errors.Is 负责判断，err.Error() 负责展示或记录；两者不要互相替代。

常见问题

多包一层后 errors.Is 还有效吗？

只要每层通过 %w 或实现约定的 Unwrap 保留底层错误，增加上下文不会影响 errors.Is 对目标的匹配。

什么时候应该直接调用 errors.Unwrap？

当你需要检查自定义包装类型的下一层或做调试时可以用它；常规错误分类应优先用 errors.Is，因为它表达的是完整链路匹配。