Go errors.Is 自定义错误需要实现哪个方法才能匹配

自定义错误想让 errors.Is 匹配，关键不是把错误字符串写成一样，而是给错误类型实现 Is(error) bool。Error() string 只负责给日志和人看，Unwrap() error 只负责暴露被包装的底层错误；三者职责不同。本文用一个“配额不足”小项目把这条规则跑通。

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

先定义可被调用方依赖的哨兵错误

先公开一个稳定的分类值。调用方依赖它，而不是依赖“quota exceeded”这类可能会调整的展示文本。下面的类型还保存了当前用户和已用额度，方便日志定位。

package main

import "fmt"

// ErrQuotaExceeded 是调用方可以稳定判断的业务分类。
var ErrQuotaExceeded = fmt.Errorf("quota exceeded")

// ErrNotFound 代表另一个无关的业务分类，用来测试误匹配。
var ErrNotFound = fmt.Errorf("not found")

// QuotaError 保存展示上下文，同时通过 Is 暴露业务分类。
type QuotaError struct {
    UserID string
    Used   int
    Limit  int
}

// Error 只负责生成可读信息，不承担分类匹配。
func (e QuotaError) Error() string {
    return fmt.Sprintf("user %s used %d/%d quota", e.UserID, e.Used, e.Limit)
}

自定义错误要实现 Is(error) bool

真正决定 errors.Is(err, target) 是否命中的方法是 Is(error) bool。方法接收调用方传入的 target，做一次浅比较即可。这里用指针接收者不是硬性要求，但要保证实际返回的错误值确实拥有这个方法。

// Is 把同一类配额错误映射到公开哨兵值。
// 只比较当前错误与 target，不递归调用 Unwrap。
func (e QuotaError) Is(target error) bool {
    return target == ErrQuotaExceeded
}

// Check 返回带有业务上下文的自定义错误。
func Check(userID string, used, limit int) error {
    if used 

这个方法不会让任意两个 QuotaError 自动相等，也不会按错误文本比较。它只承诺一个明确的业务关系：当前错误属于 ErrQuotaExceeded 这一类。

用 %w 保留底层错误链

到服务层后，通常还要补充订单号、接口名或请求动作。用 %w 包装，而不是用 %v 把错误格式化成普通字符串，否则错误链会断掉。

import (
    "errors"
    "fmt"
)

// createOrder 模拟创建订单时增加请求上下文。
func createOrder() error {
    // %w 保留 QuotaError，让 errors.Is 还能继续遍历错误树。
    if err := Check("u-1024", 120, 100); err != nil {
        return fmt.Errorf("create order: %w", err)
    }
    return nil
}

func main() {
    err := createOrder()
    // errors.Is 会调用自定义错误的 Is 方法寻找业务分类。
    fmt.Println(errors.Is(err, ErrQuotaExceeded)) // true
    fmt.Println(errors.Is(err, errors.New("quota exceeded"))) // false
}

第二个结果是 false 很重要：每次 errors.New 都会得到新的错误值，即使文本一样也不是同一个哨兵。要匹配，就复用包级的 ErrQuotaExceeded，或让自定义错误的 Is 明确声明关系。

用表格与测试验收匹配边界

可以把职责和验收结果压缩成一张表，排查时先看错误值是否仍在链上，再看 target 是否是稳定契约。

最后给关键路径写测试，至少覆盖直接返回、%w 包装和无关 target。测试断言的是公开语义，不要把完整错误字符串当作 API。

func TestQuotaErrorMatch(t *testing.T) {
    // 直接错误和包装错误都应该属于配额超限。
    direct := QuotaError{UserID: "u-1", Used: 11, Limit: 10}
    wrapped := fmt.Errorf("service: %w", direct)
    if !errors.Is(direct, ErrQuotaExceeded) || !errors.Is(wrapped, ErrQuotaExceeded) {
        t.Fatal("quota error should match its sentinel")
    }
    // 无关分类必须保持不匹配，防止 Is 写成过宽的 true。
    if errors.Is(wrapped, ErrNotFound) {
        t.Fatal("quota error must not match not-found")
    }
}

相关问题

只实现 Error()，errors.Is 会按文本匹配吗？

不会。标准库先比较错误值本身，再看自定义的 Is(error) bool，不会把 Error() 返回的字符串当作匹配键。

Is 方法里需要调用 Unwrap 吗？

不需要。错误树的遍历由 errors.Is 负责；自定义 Is 只做当前值与 target 的浅比较。

什么时候应该实现 Unwrap？

当错误需要保留一个底层原因，并允许调用方继续判断它时实现 Unwrap() error；它和“把当前错误映射到某个业务哨兵”是两种不同职责。