Go error包装后直接比较字符串失效的替代判断

Go 里最容易留下隐患的一种错误判断，是先用 fmt.Errorf("...: %w", err) 增加上下文，后面又拿完整的 err.Error() 去比较固定字符串。包装后的文本本来就允许变化，直接比较既会被前缀打断，也无法表达“这是同一个错误语义”。稳定的做法是：可比较的哨兵错误用 errors.Is，需要读取字段的具体错误用 errors.As 或 errors.AsType，字符串只负责日志和展示。

先把错误文本和错误身份分开

下面这段代码中，err.Error() 可能是“读取用户配置：文件不存在”，而底层语义仍然是 fs.ErrNotExist。前者适合记录上下文，后者才适合决定是否创建默认配置。

var ErrConfigMissing = errors.New("config missing")

func loadConfig() error {
    // %w 保存底层错误身份，同时把文件位置补进展示文本。
    return fmt.Errorf("读取用户配置: %w", fs.ErrNotExist)
}

func handle() error {
    err := loadConfig()
    if err == nil {
        return nil
    }
    // 不比较完整字符串，避免上下文调整后分支失效。
    if errors.Is(err, fs.ErrNotExist) {
        return ErrConfigMissing
    }
    return err
}

还有一个常见误区：每次调用 errors.New("same message") 都会产生不同的错误值，文本相同不代表身份相同。需要跨函数传递的哨兵错误应当定义一次并复用，或者直接匹配标准库提供的哨兵值。

用 errors.Is 替代字符串和直接等号判断

errors.Is(err, target) 会检查当前错误及其通过 Unwrap 暴露的包装树。它比 err == target 更适合调用边界，因为中间层可以添加上下文，甚至使用 errors.Join 保留多个原因。

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

func save() error {
    // 这里的 %w 让调用方仍能识别 ErrPermission。
    return fmt.Errorf("保存报表: %w", ErrPermission)
}

func classify(err error) string {
    // 语义判断只看哨兵，不依赖中文提示或前缀。
    switch {
    case errors.Is(err, ErrPermission):
        return "请申请写入权限"
    case errors.Is(err, fs.ErrNotExist):
        return "请先创建目标目录"
    default:
        return "记录原错误并交给上层处理"
    }
}

如果包装时使用的是 %v 而不是 %w，文本仍然会拼接出来，但错误链已经断开，后续的 errors.Is 无法找到底层值。需要保留可判定性时，格式化动词本身就是接口设计的一部分。

需要字段时用 errors.As，而不是拆字符串

当调用方关心路径、操作名或自定义错误中的状态码，目标就不再是某个固定错误值，而是某种错误类型。errors.As 会沿包装链寻找可赋值的类型，命中后直接拿到结构化字段。

func explain(err error) string {
    var pathErr *fs.PathError
    // 目标必须是非 nil 指针；命中后 pathErr 才能读取结构化字段。
    if errors.As(err, &pathErr) {
        return fmt.Sprintf("操作 %s 访问 %s 失败", pathErr.Op, pathErr.Path)
    }
    return err.Error() // 这里只作为最终展示文本，不再向下游传播作判断
}

较新的 Go 版本还提供 errors.AsType，可以用类型参数返回匹配值，减少目标指针的样板代码；如果项目需要兼容较老工具链，继续使用 errors.As。两种方式都要求错误类型通过包装链可达，不能把一个已经用 %v 拼平的字符串重新“猜”回原类型。

自定义匹配和多错误包装的边界

自定义错误可以实现 Is(error) bool，把一组内部错误映射到公开的语义；也可以实现 As(any) bool，为调用者提供兼容的目标类型。实现时只做浅层匹配，不要在自定义 Is 中再次递归调用 Unwrap，否则职责会和标准库遍历重复。

errors.Join(errA, errB) 会形成多子节点包装树，errors.Is 和 errors.As 仍然可以分别找到其中的原因。相反，fmt.Errorf("%v", err) 只保留最终文本；这通常是跨边界“只展示、不再判定”的明确选择，不应在内部错误链中随意使用。

把错误处理写成发布前检查清单

排查“包装后比较失效”时，可以依次问五件事：目标是哨兵值还是具体类型；生产包装是否使用了 %w；调用方是否需要错误字段；对外文案是否和程序协议混在一起；多错误场景是否允许任一原因命中。只要答案清楚，判断分支就能从字符串改成稳定的语义匹配。

相关问题

为什么 err.Error() 看起来一样，直接比较仍可能失败？

错误文本相同不代表接口值身份相同；不同的 errors.New 调用会生成不同实例，包装后还会增加上下文。

什么时候可以读取 err.Error()？

用于日志、响应提示和最终展示时可以读取；如果结果要驱动重试、降级或分支，应改用 errors.Is 或 errors.As。

errors.As 找不到自定义错误类型怎么办？

先检查中间层是否使用 %w 或实现了正确的 Unwrap，再确认目标是与实际错误一致的指针或接口类型。