Go errors.Is 为什么需要自定义 Is 方法

如果一个业务错误既要保留自己的字段，又希望调用方用统一的哨兵错误判断，单靠错误文本或直接比较通常不够。这正是 errors.Is 允许错误类型提供 Is(error) bool 方法的原因：把“这个错误在业务语义上等价于什么”交给错误类型自己定义。

官方地址：https://pkg.go.dev/errors#Is

自定义 Is 方法不是为了让所有错误都互相匹配，而是为一个具体错误类型提供稳定、浅层的等价关系；它仍然会参与 errors.Is 的错误树遍历，也不会按错误文本自动比较。

• 默认规则：errors.Is 先比较当前错误，再沿 Unwrap 得到的错误树继续查找。
• 扩展入口：当前错误实现 Is(target error) bool 后，可以把内部错误映射到公开哨兵。
• 实现边界：Is 只做浅层比较，不在里面再次调用 Unwrap。

errors.Is 先检查什么

errors.Is(err, target) 不是简单的字符串搜索。它先看当前的 err 是否与 target 直接相等；如果没有命中，再根据 Unwrap() error 或 Unwrap() []error 继续检查错误树。当前错误还可以通过 Is(target error) bool 主动声明匹配关系。

这个顺序解释了为什么包装不会天然破坏哨兵判断：只要包装链中的某个节点能直接相等，或者它的自定义 Is 方法返回 true，整个判断就可以命中。反过来，错误消息相同并不代表错误值相同。

为什么普通错误匹配不到哨兵

下面的示例故意创建两个文本相同的错误。它们的消息一样，但每次调用 errors.New 都会得到独立的错误值，所以用其中一个去匹配另一个不会成功。工程代码应该把需要跨层判断的语义保存成可复用的哨兵错误。

package main

import (
    "errors"
    "fmt"
)

func main() {
    // 两次 errors.New 得到不同的错误值，文本相同也不会自动等价。
    first := errors.New("permission denied")
    second := errors.New("permission denied")
    fmt.Println(errors.Is(first, second)) // false

    // 哨兵错误需要被复用，调用方才有稳定的匹配目标。
    var ErrPermission = errors.New("permission denied")
    wrapped := fmt.Errorf("load profile: %w", ErrPermission)
    fmt.Println(errors.Is(wrapped, ErrPermission)) // true
}

这里的 %w 只负责把哨兵放进包装链，真正让判断稳定的是同一个 ErrPermission 值。若把每次返回的错误都写成新的 errors.New，调用方就没有可长期依赖的目标。

自定义 Is 方法怎样接入匹配

当错误需要携带用户、资源或请求编号等上下文时，直接返回哨兵会丢失细节；把哨兵包在错误文本里又会把判断绑到字符串格式。更合适的做法是让自定义错误保留字段，并用 Is 方法声明它对应的公开语义。

package main

import (
    "errors"
    "fmt"
)

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

type PermissionError struct {
    User string
}

func (e PermissionError) Error() string {
    return fmt.Sprintf("user %q has no permission", e.User)
}

func (e PermissionError) Is(target error) bool {
    // 只比较当前错误与公开哨兵的语义，不递归检查包装链。
    return target == ErrPermission
}

func main() {
    err := PermissionError{User: "alice"}
    fmt.Println(err)
    fmt.Println(errors.Is(err, ErrPermission)) // true
}

调用方只关心 errors.Is(err, ErrPermission)，日志仍然可以输出具体用户。这样把“公开分类”和“内部上下文”分开：哨兵负责稳定判断，自定义错误负责携带细节。

把自定义错误放进包装链

自定义错误不必处在最外层。下面把它交给 fmt.Errorf 包装，外层增加操作上下文，内层仍然通过自己的 Is 方法命中 ErrPermission。这就是错误树遍历和自定义匹配共同工作的最小场景。

package main

import (
    "errors"
    "fmt"
)

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

type PermissionError struct{ User string }

func (e PermissionError) Error() string {
    return fmt.Sprintf("user %q has no permission", e.User)
}

func (e PermissionError) Is(target error) bool {
    // Is 只负责当前节点的浅层语义映射，Unwrap 由 errors.Is 负责。
    return target == ErrPermission
}

func loadConfig() error {
    // %w 保留原始错误，让调用方仍能沿错误树判断类别。
    return fmt.Errorf("load config: %w", PermissionError{User: "alice"})
}

func main() {
    err := loadConfig()
    fmt.Println(errors.Is(err, ErrPermission)) // true
}

这里的判断不依赖错误消息，也不要求调用方知道 PermissionError 的字段。错误类型只暴露它愿意承诺的等价关系，包装层则负责补充操作上下文。

哪些写法容易让语义失控

第一，不要用错误文本作为协议。文本适合日志阅读，不适合跨包契约；如果确实需要稳定分类，就定义并复用哨兵错误。第二，target 必须是可比较的错误值，通常使用由 errors.New 创建的哨兵即可。第三，Is 方法应当只做当前节点的浅层判断，不要在里面调用 Unwrap 或重新遍历错误树，否则会把遍历职责和匹配职责混在一起。

还要控制匹配范围。一个业务错误可以匹配一个明确的公开类别，但不应为了“方便判断”而让它对多个无关哨兵都返回 true。调用方一旦依赖这个关系，它就会成为错误处理协议的一部分，后续修改需要考虑兼容性。

用一张表记住选择

常见问题

errors.Is 会按错误消息匹配吗？

不会。默认匹配依赖错误值相等、错误树中的匹配节点，或节点提供的自定义 Is 方法。消息相同的两个独立错误不等价。

实现 Is 方法后还需要 Unwrap 吗？

是否需要取决于错误是否还要暴露一个底层原因。Is 负责当前节点的语义匹配，Unwrap 负责把底层错误接入错误树，两者职责不同。

Is 方法里能不能调用 errors.Is？

不建议。官方语义要求自定义 Is 做浅层比较，不要通过 Unwrap 重新遍历；这样可以避免递归、重复判断和难以预测的匹配范围。

什么时候只用哨兵错误就够了？

如果调用方只需要固定类别，不需要附带额外上下文，直接定义并复用哨兵通常更简单。只有在错误值需要保留结构化字段时，才值得增加自定义类型。