Go errors.Is 怎样判断被包装错误的原始类型

Go 里给错误增加上下文后，最容易混淆的是“它是不是某个错误值”和“它的具体类型是什么”。errors.Is 解决前一个问题：沿着错误的包装树查找目标错误值；如果要取出被包装的 *ConfigError 并读取字段，应使用 errors.As（或较新的 errors.AsType）。

先区分错误值匹配和错误类型判断

errors.Is 的目标通常是包级哨兵错误，例如 io.EOF、fs.ErrNotExist 或业务包定义的 ErrPermission。它检查当前错误以及不断调用 Unwrap 得到的后代，找到匹配值就返回 true。所以它回答的是“这条错误链是否包含某种已约定的原因”，不是“最底层对象的 Go 类型叫什么”。

用 %w 建立可检查的包装链

包装时只改变展示文本，不应该丢掉调用方需要判断的原因。%v 只把错误格式化进字符串；%w 才会让返回值提供可遍历的 Unwrap() error。

package main

import (
    "errors"
    "fmt"
)

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

func loadConfig() error {
    // %w 保留底层哨兵错误，调用方才能用 errors.Is 检查。
    return fmt.Errorf("read config: %w", ErrPermission)
}

func main() {
    err := fmt.Errorf("start service: %w", loadConfig())
    // 多一层上下文不会阻断对 ErrPermission 的匹配。
    fmt.Println(errors.Is(err, ErrPermission)) // true
}

如果把两个 %w 误写成 %v，打印出来的文本可能完全一样，但错误链已经断开，errors.Is 会返回 false。这也是判断“包装是否有效”时最值得先查的一行。

用 errors.Is 判断原始哨兵错误

对外部包或业务层约定的稳定原因，优先用 errors.Is。它不依赖错误文本，也不要求调用方知道中间经过了哪些模块。

func handle(err error) string {
    // 先判断稳定的语义原因，再决定提示或重试策略。
    switch {
    case errors.Is(err, ErrPermission):
        return "请检查配置权限"
    case errors.Is(err, errors.ErrUnsupported):
        return "当前实现不支持该操作"
    default:
        return "记录原错误并交给上层处理"
    }
}

如果错误来自 errors.Join，它的多个子错误也会组成一棵错误树，errors.Is 仍然可以查找其中的目标。匹配成立只说明“树中存在该原因”，并不说明它是唯一原因或最先发生的原因。

用 errors.As 提取原始具体类型

当问题是“被包装的原始错误是不是 *ConfigError，并且我需要它的 File 字段”，就换成 errors.As。目标变量应声明为要提取的错误类型；如果该类型实现 Error 的是指针接收者，目标也要是指针类型。

type ConfigError struct {
    File string
    Err  error
}

func (e *ConfigError) Error() string { return e.File + ": " + e.Err.Error() }
func (e *ConfigError) Unwrap() error { return e.Err }

func show(err error) {
    var configErr *ConfigError
    // &configErr 是“指向目标变量的指针”，不是把错误强转成字符串。
    if errors.As(err, &configErr) {
        fmt.Println("配置文件:", configErr.File)
        return
    }
    fmt.Println("不是 ConfigError")
}

在支持 Go 1.26 及以上的项目中，也可以写成 configErr, ok := errors.AsType[*ConfigError](err)。需要兼容更早版本时继续使用 errors.As 更稳妥。

按匹配目标选择 API 并处理边界

排查时可以按这张清单快速定位：先看创建包装时是否使用了 %w；再确认 Is 的第二个参数是同一个哨兵值，而不是重新 errors.New 出来的同文案错误；需要字段时改用 As，并检查目标指针层级；最后不要把 err.Error() 的文本当作稳定协议。

错误包装也是 API 承诺的一部分。只有希望调用方依赖底层原因时才用 %w；如果底层实现属于内部细节，公开包装可能让后续替换实现变得困难。

相关问题

errors.Is 能返回被匹配的原始错误对象吗？

不能，它只返回 bool。需要对象或字段时使用 errors.As 或 errors.AsType。

为什么 errors.Is 比 err == ErrPermission 更合适？

== 只比较当前值；errors.Is 还会检查通过 Unwrap 暴露的包装错误。

把 %v 改成 %w 就一定应该吗？

不一定。是否暴露底层错误取决于它是否属于当前函数的公开契约，内部实现细节不宜随意暴露。