错误被 fmt.Errorf 包了几层还想分类：用 errors.Is、errors.As 和 Join 保留判断能力

错误被包装并不等于信息丢失，真正容易出问题的是把“错误属于哪一类”和“错误携带了什么细节”混成一种判断。工程代码可以遵循一个简单分工：用 errors.Is 判断哨兵错误，用 errors.As 提取具体类型，用 errors.Join 汇总多个分支，再继续让前两者遍历错误树。

一、先把错误链拆成语义标签和具体类型

先定义跨层稳定的哨兵错误，再让底层错误携带操作、路径或状态等诊断信息。调用方只依赖公开契约，不依赖某一层的完整字符串。

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

func loadConfig(path string) error {
    if path == "" {
        return fmt.Errorf("config path is empty: %w", ErrQuota)
    }
    return nil
}

这里的文本适合日志阅读，但分类契约是 ErrQuota。每一层都可以继续用 %w 加上动作和对象，调用方仍能沿错误树找到它。

二、用 errors.Is 穿透包装判断哨兵错误

不要写 err == ErrQuota 来处理可能被包装的错误，也不要用 strings.Contains(err.Error(), ...) 代替分类。errors.Is 会检查当前错误及其 Unwrap 后代，适合权限、未找到、配额等有限类别。

err := loadConfig("app.yaml")
if err != nil {
    switch {
    case errors.Is(err, ErrQuota):
        return fmt.Errorf("请稍后重试：%w", err)
    case errors.Is(err, fs.ErrNotExist):
        return fmt.Errorf("配置文件不存在：%w", err)
    default:
        return err
    }
}

目标错误必须是可比较的；自定义错误也可以实现 Is(error) bool 做浅层等价判断，但不要在这个方法里再次递归调用 Unwrap。这样边界清楚，循环也不会意外出现。

三、用 errors.As 提取底层类型和诊断字段

当处理逻辑需要路径、操作名或系统错误码时，分类不够了，这时用 errors.As。它找到错误树中第一个可赋值到目标类型的错误，并把目标变量填好。

func explain(err error) string {
    var pathErr *fs.PathError
    if errors.As(err, &pathErr) {
        return fmt.Sprintf("操作 %s 失败，路径是 %s", pathErr.Op, pathErr.Path)
    }
    return "没有可提取的路径信息"
}

注意目标参数是指向目标类型的非空指针；如果目标类型是指针错误，通常要写成 var pathErr *fs.PathError 再传 &pathErr。不要先把顶层错误强转成 *fs.PathError，中间多了一层包装就会失败。

四、用 errors.Join 保留多个分支的失败原因

批量校验或并发任务结束时，单独返回第一个错误会丢掉其余分支的诊断信息。Go 1.20 起可以用 errors.Join 汇总非空错误；它实现的是 Unwrap() []error，因此后续的 Is 和 As 仍能遍历整棵树。

var errs []error
if err := checkFile("app.yaml"); err != nil {
    errs = append(errs, fmt.Errorf("检查配置：%w", err))
}
if err := checkFile("secret.yaml"); err != nil {
    errs = append(errs, fmt.Errorf("检查密钥：%w", err))
}
if err := errors.Join(errs...); err != nil {
    if errors.Is(err, fs.ErrNotExist) {
        // 至少一个输入文件不存在
    }
    return err
}

Join 会忽略 nil；所有输入都是 nil 时返回 nil。它的字符串表现是各错误文本按换行拼接，适合日志，但程序判断仍应使用 Is 或 As。如果业务只允许一个原因，就在边界处明确选择首错；如果需要完整复盘，则保留 Join 返回值。

相关问题

为什么错误文本相同，errors.Is 仍可能返回 false？

errors.New 每次调用都会得到不同的错误值。需要匹配时，应把哨兵错误保存为包级变量并重复使用，而不是每次根据相同文本重新创建。

errors.Unwrap 能不能拆开 Join？

不能直接拆开。errors.Unwrap 只处理返回单个 error 的方法；Join 使用的是 Unwrap() []error。通常不需要手工拆，继续使用 Is 和 As 查询即可。