Go errors.Is 自定义错误为什么必须实现 Is 方法

我第一次遇到这个问题，是把接口层的业务错误改成了带字段的自定义类型：日志里能看到同一个错误码，测试里的 errors.Is 却一直是 false。原因不在错误文本，而在 Go 默认先比较错误值本身；如果调用方要表达“只要错误码相同就算同一种错误”，自定义类型就需要实现 Is(error) bool。

官方资料：https://pkg.go.dev/errors

不是所有自定义错误都必须实现 Is。只要你直接返回一个可复用的哨兵错误，或只需要判断具体类型，通常不需要它；当错误要按部分字段、错误码或业务类别进行匹配时，才用 Is 把这种语义明确写出来。

先看懂 errors.Is 默认比较什么

errors.Is(err, target) 会检查当前错误以及它通过 Unwrap 暴露出的错误树。默认情况下，某个节点只有在与 target 相等时才匹配。fmt.Errorf("...: %w", err) 负责把链路接起来，却不会替你改变自定义类型的相等规则。

下面的类型使用指针承载错误。两个指针的字段完全相同，但它们是两个不同的地址，因此默认比较仍然失败：

package main

import (
    "errors"
    "fmt"
)

type CodeError struct {
    Code int
    Msg  string
}

func (e *CodeError) Error() string { return fmt.Sprintf("%d: %s", e.Code, e.Msg) }

func main() {
    err := fmt.Errorf("读取用户: %w", &CodeError{Code: 404, Msg: "not found"})
    target := &CodeError{Code: 404}
    // 只写 Error 方法时，target 是另一个指针，默认匹配不会按 Code 判断。
    fmt.Println(errors.Is(err, target)) // false
}

如果把错误改成值类型且字段都可比较，值相等可能让示例碰巧返回 true；但这不是稳定的业务契约。错误里一旦出现指针、切片或需要忽略的描述字段，就不能靠结构体的默认相等表达“同类错误”。

Is 方法把“同一种错误”定义成业务规则

Is 的职责是回答：当前错误是否可以被看作调用方给出的目标错误。常见做法是只比较稳定的错误码，忽略每次请求都可能不同的消息；目标错误不是同一类型时直接返回 false。

// Is 只比较稳定的业务字段，不递归调用 Unwrap。
func (e *CodeError) Is(target error) bool {
    t, ok := target.(*CodeError)
    if !ok {
        return false
    }
    // Code 是对外承诺的分类；Msg 只用于日志，不参与匹配。
    return t.Code != 0 && e.Code == t.Code
}

func loadUser() error {
    // %w 保留包装关系，让 errors.Is 能走到 CodeError。
    return fmt.Errorf("读取用户失败: %w", &CodeError{Code: 404, Msg: "user id=42"})
}

func check() {
    if errors.Is(loadUser(), &CodeError{Code: 404}) {
        fmt.Println("可以走未找到分支")
    }
}

此时包装文字可以变化，Msg 也可以携带用户 ID，但目标只写 Code: 404 仍能命中。标准库文档还特别强调，Is 应做浅比较，不要在里面再次调用 Unwrap；遍历错误树的工作由 errors.Is 完成。

Is、Unwrap 和哨兵错误不要混为一谈

这三个机制解决的是不同问题：

如果你的 API 只需要一个稳定分类，优先定义哨兵并用 %w 包装：

var ErrNotFound = errors.New("not found")

func find() error {
    // 对外承诺 ErrNotFound，但保留当前操作的上下文。
    return fmt.Errorf("用户 42: %w", ErrNotFound)
}

func caller() {
    // 不比较错误文本，也不依赖具体包装类型。
    if errors.Is(find(), ErrNotFound) {
        fmt.Println("进入未找到处理")
    }
}

只有当目标需要“同类模板匹配”，例如错误码相同即可，才增加 Is。如果底层错误属于实现细节，也不要为了方便排查而盲目 %w；一旦包装它，调用方就可能把这个底层错误当成你的 API 承诺。

写完 Is 后检查这几个边界

1. 先问清楚匹配依据：错误码、资源类型还是完整字段？只比较真正稳定的字段。
2. 目标类型不符、目标为空或字段不满足匹配条件时返回 false，不要把所有错误都判为相等。
3. 包装上下文用 %w，仅展示文字但不希望暴露内部实现时用 %v。
4. 为“同码不同消息”“经过一层包装”“不同错误码”分别写测试，避免只测一个直连样例。

所以，标题里的“必须”应该理解为 API 语义上的必须，而不是接口实现上的硬性要求：Error() 让类型成为错误，Unwrap() 让它连接原因，Is() 才让它能按你定义的规则与另一个错误匹配。

相关问题

errors.Is 能不能比较错误文本？

不能把错误文本当作可靠身份。文本适合日志和展示；程序判断应使用哨兵错误、错误类型或自定义 Is。

实现 Is 后还需要 Unwrap 吗？

看是否需要保留底层原因。需要让调用方继续检查底层错误时实现 Unwrap；只做业务分类匹配时，单独实现 Is 也可以。