Go errors.Is 自定义类型没匹配到是因为缺少什么

很多Go开发者在做错误匹配时都碰到过，errors.Is怎么调用都识别不到自己写的自定义错误类型，大部分场景下缺的就是自定义错误类型上适配errors.Is规则的Is方法实现。

如果你的自定义错误类型没有实现对应的Is方法，Go标准库的errors.Is默认只会做值相等对比，不会自动把目标错误和同类型的自定义错误判定为匹配，补全符合签名要求的Is方法逻辑，就能覆盖这类自定义类型的匹配场景。

给自定义错误写了 Error()，errors.Is 还是匹配不到，通常不是 errors.Is 失效，而是类型只满足了 error 接口，却没有告诉错误链如何展开，或者没有定义它与目标错误的语义关系。

自定义错误包着底层错误时，实现 Unwrap() error；希望它与某个哨兵错误等价时，实现 Is(error) bool。如果目的是取回自定义类型并读取字段，则应该使用 errors.As，不能把 errors.Is 当成类型断言。

先分清：你要找底层错误，还是定义一个匹配规则

errors.Is(err, target) 会检查当前错误以及它能通过 Unwrap 暴露出的错误树。默认匹配是错误值相等；自定义类型还可以通过 Is(error) bool 覆盖当前这一层的匹配规则。因此“自定义类型没匹配到”要先看需求：

只实现 Error() 并不会自动产生错误链，也不会让两个内容相同的指针错误相等。下面两个实现分别对应最常见的两种修复方向。

错误包着原因时，补上 Unwrap

如果自定义类型有一个导出的或明确要暴露给调用方的 Err 字段，Unwrap 应该返回它。这样错误可以增加上下文，同时仍然让上层识别哨兵错误：

package main

import (
    "errors"
    "fmt"
)

var ErrInvalid = errors.New("invalid request")

type FieldError struct {
    Field string
    Err   error
}

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

func (e *FieldError) Unwrap() error {
    // 暴露底层原因，让 errors.Is 能继续沿错误链查找。
    return e.Err
}

func validate() error {
    // 业务字段保留在外层，稳定的错误语义放在 ErrInvalid。
    return &FieldError{Field: "email", Err: ErrInvalid}
}

func main() {
    err := fmt.Errorf("validate user: %w", validate())
    // %w 和 Unwrap 配合，避免包装层截断错误链。
    fmt.Println(errors.Is(err, ErrInvalid))
}

这里真正让匹配成功的是 FieldError.Unwrap 返回了 ErrInvalid。如果把包装写成 fmt.Errorf("validate user: %v", validate())，错误文本仍然好看，但链已经被截断，errors.Is 无法再找到它。

不同实例代表同一种状态时，实现 Is

有些错误没有一个需要继续展开的内部错误，但希望满足条件的多个实例都匹配某个哨兵。例如远端操作失败时，只要 Temporary 为真，就让重试策略识别为可重试：

package main

import (
    "errors"
    "fmt"
)

var ErrRetryable = errors.New("retryable")

type RemoteError struct {
    Operation string
    Temporary bool
}

func (e RemoteError) Error() string {
    return fmt.Sprintf("%s failed", e.Operation)
}

func (e RemoteError) Is(target error) bool {
    // 只比较当前错误的字段，不在 Is 中递归展开错误链。
    return target == ErrRetryable && e.Temporary
}

func request() error {
    // 每次返回的新实例也能按业务语义匹配同一个目标。
    return RemoteError{Operation: "fetch profile", Temporary: true}
}

func main() {
    // Is 判断语义；As 才用于取回 RemoteError 的字段。
    fmt.Println(errors.Is(request(), ErrRetryable))
}

官方 errors 文档强调，Is 应该只做当前层的浅比较，不要在方法内部再调用 errors.Is；错误链的递归由标准库负责。如果类型同时保存了底层原因，也可以同时实现 Is 和 Unwrap，分别承担语义匹配和链路展开。

四个容易让 errors.Is 误判的坑

1. 只有 Error 没有 Unwrap：外层错误能打印内层文字，不代表程序能看见内层错误。需要继续匹配时补 Unwrap。
2. 用 %v 包装：它只格式化文本；对外承诺可匹配的错误要用 %w，否则调用方只能看到字符串。
3. 拿两个指针做内容比较：errors.Is(err, &FieldError{Field: "email"}) 默认比较的是指针相等，不会自动比较字段。需要按字段匹配就实现 Is，需要取字段就用 As。
4. 把 Is 当成 As：如果要取得自定义类型，写成下面这样；目标变量要传指针的指针，尤其当错误类型本身是指针时。

var fieldErr *FieldError
if errors.As(err, &fieldErr) {
    // fieldErr 指向链中的具体类型，可读取 Field 和 Err。
    fmt.Println(fieldErr.Field)
}

按这个检查清单定位匹配失败

• 目标是链中的哨兵或底层错误：确认每一层包装都使用 %w，自定义包装类型有 Unwrap() error。
• 目标是一个稳定业务语义：确认自定义类型实现了 Is(error) bool，并只做当前层比较。
• 目标是读取自定义字段：改用 errors.As，不要构造一个“看起来一样”的新指针传给 errors.Is。
• 不确定是否要暴露底层实现：谨慎添加 Unwrap。一旦调用方依赖这个错误类型，它就可能成为你的 API 契约。

相关问题

errors.Is 能按自定义结构体字段自动匹配吗？

不能。默认规则是错误值相等；需要按字段定义等价关系时，实现 Is(error) bool，或者改用 errors.As 后在业务代码中判断字段。

自定义错误一定要实现 Unwrap 吗？

不一定。只有当内部错误应该被调用方识别，或错误需要加入已有错误链时才实现；如果内部错误是实现细节，保留文字而不暴露链通常更稳妥。

Is 和 As 可以同时使用吗？

可以。Is 用于判断是否属于某种稳定语义，As 用于取回具体类型和字段，两者解决的是不同问题。