Go errors.Is 判断包装错误时怎么避免误判同类错误

Go 里最容易混淆的一点，是把“错误类型相同”“错误文本相同”和“errors.Is 匹配成功”当成一回事。它们不是同一个判断。errors.Is 检查的是错误树里是否存在目标错误，errors.As 才适合把包装后的错误取回并读取字段；使用 errors.Join 后，错误树还可能同时包含多个分支。

避免误判的核心是：跨层判断用稳定的哨兵错误，按类型读取细节用 errors.As，不要拿一个临时创建的同类错误或展示文本去做 errors.Is 目标。

先分清：errors.Is 判断目标，errors.As 提取类型

下面这个例子模拟表单校验：一个字段出错时返回 FieldError，上层再用 fmt.Errorf 增加上下文。虽然两个错误都描述“邮箱无效”，但把临时创建的 errors.New 传给 errors.Is，并不会因为文本一样就匹配。

package main

import (
    "errors"
    "fmt"
)

// FieldError 保留字段名，适合用 errors.As 取回细节。
type FieldError struct {
    Field string
    Code  string
}

func (e *FieldError) Error() string {
    return fmt.Sprintf("%s: %s", e.Field, e.Code)
}

func main() {
    err := fmt.Errorf("校验失败: %w", &FieldError{Field: "email", Code: "invalid"})

    // 两次 errors.New 创建的是两个不同的错误值，文本相同也不会相等。
    sameText := errors.New("email: invalid")
    fmt.Println(errors.Is(err, sameText)) // false

    // 类型判断交给 As，再读取字段做更精确的业务分支。
    var fieldErr *FieldError
    if errors.As(err, &fieldErr) {
        fmt.Println(fieldErr.Field, fieldErr.Code) // email invalid
    }
}

errors.Is 可以沿着 Unwrap() error 或 Unwrap() []error 继续查找，但它不会根据 Error() 返回的字符串猜测“同类”。如果业务只关心错误类别，应该先定义稳定目标；如果还要知道字段、代码或原始值，就用 errors.As。

用稳定哨兵错误收窄 errors.Is 的匹配范围

跨函数、跨包传播的错误类别，可以用包级哨兵表示。例如“输入无效”是稳定语义，而字段名和具体原因属于实例细节：

var ErrInvalidInput = errors.New("invalid input")

// ValidateEmail 给上层一个稳定类别，同时保留字段错误作为原因。
func ValidateEmail(value string) error {
    if value == "" {
        return fmt.Errorf("email: %w", ErrInvalidInput)
    }
    return nil
}

func handle(err error) string {
    // Is 判断公开类别；不要依赖 Error() 文本做分支。
    if errors.Is(err, ErrInvalidInput) {
        return "请检查输入"
    }
    return "请稍后重试"
}

这里的 %w 很重要：它让上层增加上下文的同时保留哨兵错误。相反，使用 %v 只会把文字拼进去，错误链断开，后续的 errors.Is 就找不到 ErrInvalidInput。哨兵也不要到处复制；调用方必须引用同一个导出的目标。

errors.Join 之后要接受多棵错误树的匹配

errors.Join 会丢弃 nil，并让非 nil 错误通过 Unwrap() []error 形成多分支错误树。校验多个字段时，调用方可以一次知道是否包含某个类别，同时用 errors.As 找到具体实例：

func ValidateForm(email, name string) error {
    var errs []error
    if email == "" {
        // 每个字段保留自己的实例细节。
        errs = append(errs, fmt.Errorf("%w: email", ErrInvalidInput))
    }
    if name == "" {
        errs = append(errs, fmt.Errorf("%w: name", ErrInvalidInput))
    }
    // Join(nil...) 会返回 nil，适合直接作为函数结果。
    return errors.Join(errs...)
}

err := ValidateForm("", "")
if errors.Is(err, ErrInvalidInput) {
    // 这里只能说明至少一个分支属于输入错误。
    fmt.Println("存在输入校验失败")
}

如果需要逐字段展示，不要把 Join 后的多行文本拆字符串。让每个分支携带可提取的类型，或者在校验阶段直接收集结构化结果。errors.Is 的语义是“错误树中是否有匹配目标”，不是“有且只有一个同类错误”，更不是“返回了哪个字段”。

自定义 Is 只比较稳定语义，不要把同类写成全相等

只有在确实需要“不同实例可被视为同一公开类别”时，才给自定义错误实现 Is(error) bool。实现应当只做浅比较，不能在里面继续调用 errors.Is 或递归解包：

type PermissionError struct {
    Resource string
}

func (e *PermissionError) Error() string {
    return "没有权限访问 " + e.Resource
}

// Is 只公开 PermissionError 这一类别，不比较具体资源名。
func (e *PermissionError) Is(target error) bool {
    _, ok := target.(*PermissionError)
    return ok
}

这种写法意味着不同资源的 PermissionError 都会匹配；如果调用方必须区分资源，就改用 errors.As 后比较 Resource。更窄的做法是匹配一个明确的哨兵，例如 ErrPermission，而不是让所有实现细节都成为“相等”。

发布前可以按下面三项复查：目标是否是稳定哨兵；需要字段时是否使用 errors.As；组合错误后是否把“至少一个匹配”误写成“唯一匹配”。只要把类别、实例和展示三层分开，包装与聚合都不会改变分支语义。

常见问题

errors.Is 能判断两个错误类型相同吗？

不能把它当成通用类型判断。需要类型和字段时，使用 errors.As；errors.Is 更适合哨兵值或明确实现的类别匹配。

errors.Join 只有一个非 nil 错误时还会包装吗？

它仍返回一个可检查的错误结果；调用方应继续使用 errors.Is 或 errors.As，不要依赖返回文本的行数。

为什么同样的错误消息 Is 还是 false？

因为错误值通常按实例身份或自定义 Is 规则匹配，Error() 文本只是展示内容。用共享哨兵，或改用 errors.As 提取类型。