Go 自定义错误怎么实现 Is 方法匹配错误族

当一个服务会返回 timeout、rate_limited、user_missing 等动态错误码时，调用方真正关心的往往只有“能否重试”和“资源是否不存在”。这时可以给自定义错误实现 Is(error) bool：把多个具体错误映射到少量稳定的哨兵目标，调用方继续使用 errors.Is，不必比较字符串或了解全部错误码。

错误族解决的是调用方决策

我最初直接判断结构体里的 Code，很快发现 HTTP 层、任务层和测试代码都复制了同一组条件。错误码一增加，修改点就散落各处。错误族更适合作为包对外承诺的语义：例如 ErrRetryable 表示调用方可以进入重试策略，ErrNotFound 表示可以返回不存在结果。

Go 的 errors.Is(err, target) 会遍历错误树。对每个错误值，它先检查是否等于 target，再检查该错误是否实现 Is(error) bool。因此，自定义 Is 方法只需要回答“当前错误是否与这个目标语义等价”。

给自定义错误实现 Is 方法

下面把两个错误族定义为可复用的哨兵值，再让 ServiceError 按 Code 做浅层匹配。Is 内部不要再次调用 errors.Is，也不要主动展开 target；官方文档明确建议这里只做浅比较。

package service

import (
    "errors"
    "fmt"
)

var (
    ErrRetryable = errors.New("retryable service error") // 调用方可进入重试策略
    ErrNotFound  = errors.New("service resource not found") // 调用方可返回不存在
)

type ServiceError struct {
    Code string
    Op   string
    Err  error
}

func (e *ServiceError) Error() string {
    return fmt.Sprintf("%s: %s: %v", e.Op, e.Code, e.Err) // 保留可读上下文
}

func (e *ServiceError) Unwrap() error {
    return e.Err // 让底层原因继续留在错误树中
}

func (e *ServiceError) Is(target error) bool {
    switch target {
    case ErrRetryable:
        return e.Code == "timeout" || e.Code == "rate_limited" // 只比较当前值
    case ErrNotFound:
        return e.Code == "user_missing" || e.Code == "order_missing"
    default:
        return false
    }
}

这里没有把错误文本纳入判断，因为文本适合给人看，不适合做稳定 API。新增一个可重试错误码时，只需更新 ServiceError.Is 和对应测试，调用方不用跟着改。

包装后仍然能够匹配

业务层可以用 %w 增加操作上下文。errors.Is 会沿包装关系继续查找，最终调用 ServiceError 的 Is 方法，所以外层包装不会破坏错误族匹配。

func LoadUser() error {
    cause := errors.New("upstream deadline") // 模拟底层原因
    err := &ServiceError{Code: "timeout", Op: "load user", Err: cause}
    return fmt.Errorf("request failed: %w", err) // 用 %w 保留错误树
}

func Handle() string {
    err := LoadUser()
    if errors.Is(err, ErrRetryable) {
        return "稍后重试" // 上层只依赖稳定错误族
    }
    if errors.Is(err, ErrNotFound) {
        return "用户不存在"
    }
    return "内部错误"
}

这个写法还有一个实际好处：外层可以用 Is 决定响应策略，同时用 errors.As 取回 *ServiceError，记录 Code 和 Op。分类与详情互不冲突。

用测试锁定匹配边界

Is 方法一旦成为包的公开行为，错误码属于哪个族就需要测试保护。表驱动测试应同时覆盖命中、未命中和包装后的命中。

func TestServiceErrorIs(t *testing.T) {
    tests := []struct {
        name   string
        err    error
        target error
        want   bool
    }{
        {"超时可重试", &ServiceError{Code: "timeout"}, ErrRetryable, true},
        {"用户不存在", &ServiceError{Code: "user_missing"}, ErrNotFound, true},
        {"参数错误不可重试", &ServiceError{Code: "bad_request"}, ErrRetryable, false},
        {"包装后仍匹配", fmt.Errorf("api: %w", &ServiceError{Code: "rate_limited"}), ErrRetryable, true},
    }

    for _, tt := range tests {
        t.Run(tt.name, func(t *testing.T) {
            if got := errors.Is(tt.err, tt.target); got != tt.want {
                t.Fatalf("errors.Is() = %v, want %v", got, tt.want) // 固定公开匹配语义
            }
        })
    }
}

Is、As 和 Unwrap 怎么分工

Is 方法可以比较错误文本吗？

技术上能写，但不建议。文本可能因上下文、本地化或重构改变；稳定哨兵值、枚举字段或明确类型更适合表达 API 语义。

一个自定义错误能属于多个错误族吗？

可以，只要这些语义确实同时成立。例如某个上游限流错误既可归入可重试族，也可以通过 As 暴露具体类型；不要为了方便把互相矛盾的处理策略都返回 true。

官方参考：https://pkg.go.dev/errors