用错误包装保留上下文并支持 errors.Is 分类判断

Go 里给错误增加上下文时，关键不是把字符串拼得更长，而是决定是否保留一条可检查的错误链。需要让调用方识别“未找到”“无权限”等类别时，用 fmt.Errorf("...: %w", err) 包装；只想记录内部实现细节时用 %v，不要把底层错误意外变成公共 API。

先定义稳定的错误分类

错误文本适合日志和排查，不适合业务分支。先声明包级哨兵错误，让调用方依赖语义而不是依赖某一段提示文字：

package store

import "errors"

// ErrNotFound 表示记录不存在，调用方可以长期依赖这个分类。
var ErrNotFound = errors.New("store: not found")

// ErrPermission 表示当前主体没有执行操作的权限。
var ErrPermission = errors.New("store: permission denied")

哨兵错误本身不需要携带文件名或用户输入。上下文应该在真正失败的那一层添加，这样同一种错误在不同入口仍能被归类。

用 %w 把动作和资源信息接到错误链上

下面的示例模拟读取配置文件。示例只展示错误处理边界，readConfigFile 可以替换成项目自己的读取函数：

package store

import (
    "fmt"
    "os"
)

func loadConfig(path string) ([]byte, error) {
    data, err := os.ReadFile(path)
    if err != nil {
        // %w 保留底层错误，路径只作为当前层的排查上下文。
        return nil, fmt.Errorf("读取配置 %q: %w", path, err)
    }
    return data, nil
}

func loadRequiredConfig(path string) ([]byte, error) {
    data, err := loadConfig(path)
    if err != nil {
        // 再包一层时仍保留同一条错误链，便于上层分类处理。
        return nil, fmt.Errorf("加载服务配置: %w", err)
    }
    return data, nil
}

这条链的文本可以包含“加载服务配置”和具体路径，但机器判断不应解析文本。图1把哨兵错误、包装层和调用方的可见边界放在同一张静态结构图里。

用 errors.Is 做分类判断，不比较错误字符串

调用方只关心自己能处理的类别时，直接用 errors.Is：

package main

import (
    "errors"
    "fmt"
    "os"
)

func handle(path string) error {
    _, err := os.ReadFile(path)
    if err != nil {
        // 这里把系统错误包装成带资源上下文的错误。
        return fmt.Errorf("读取 %q 失败: %w", path, err)
    }
    return nil
}

func report(path string) {
    err := handle(path)
    if err == nil {
        return
    }
    // Is 会沿错误链寻找匹配项，不依赖错误文本是否改变。
    if errors.Is(err, os.ErrNotExist) {
        fmt.Println("配置文件不存在，可以创建默认配置")
        return
    }
    // 未命中已知类别时保留原错误，交给日志或更上层处理。
    fmt.Println("配置读取失败:", err)
}

如果包自己的函数返回 ErrNotFound，上层同样写 errors.Is(err, store.ErrNotFound)。不要写 err.Error() == "..."，因为路径、动作和底层系统提示都可能变化。

%w 还是 %v：取决于 API 是否愿意暴露底层错误

%w 不是“更完整的日志格式”，而是 API 语义的一部分。若底层错误来自调用方传入的 io.Reader，调用方通常有理由检查它；若数据库驱动只是包内部实现，直接包装 sql.ErrNoRows 会让调用方依赖当前驱动细节。此时可以用 fmt.Errorf("查询用户失败: %v", err) 只返回文字，或者转换为自己定义的哨兵错误。

发布前的错误链检查清单

逐个返回路径检查五件事：成功时是否返回 nil；需要分类的错误是否从哨兵开始；上下文是否通过 %w 保留；调用方是否统一使用 errors.Is 或 errors.As；底层类型是否真的属于公共兼容承诺。尤其不要为了让日志更好看，把 %w 换成字符串拼接后又期待上层继续分类。

常见问题

多包一层会让 errors.Is 失效吗？

不会。只要每一层都用 %w 或实现了 Unwrap() error，errors.Is 会继续检查错误链。

错误文本相同就可以直接比较吗？

不可以。文本是给人看的，分类判断应使用哨兵错误、错误类型或包提供的匹配方法。

什么时候不应该使用 %w？

当底层错误只是内部实现，且不希望调用方依赖它时，用 %v 或转换为稳定的包级错误。