Go 的 errors.Is 为什么匹配不到：错误包装丢失与 %w 的边界

线上订单查询返回“库存服务暂不可用”时，业务层通常还要判断它是不是 ErrInventoryUnavailable，决定重试、降级还是直接提示用户。问题在于，日志里明明能看到这段文字，errors.Is(err, ErrInventoryUnavailable) 却返回了 false。Go 里这通常不是比较写错，而是中间某一层把错误链包装丢了。

只要错误要继续被上层识别，就用 %w 保留链路；%v 只适合把错误当文本展示。errors.Is 判断的是错误链，errors.As 才是把链上的具体类型取出来。

为什么错误文字对了，errors.Is 还是返回 false

先看一个最小场景。仓储层拿到库存服务错误后，给它加上业务上下文：

var ErrInventoryUnavailable = errors.New("inventory unavailable")

func queryStock(ctx context.Context, sku string) error {
    if sku == "SKU-EMPTY" {
        return ErrInventoryUnavailable
    }
    return nil
}

func loadOrder(ctx context.Context, sku string) error {
    if err := queryStock(ctx, sku); err != nil {
        return fmt.Errorf("load order %s: %v", sku, err)
    }
    return nil
}

err := loadOrder(ctx, "SKU-EMPTY")
fmt.Println(err) // load order SKU-EMPTY: inventory unavailable
fmt.Println(errors.Is(err, ErrInventoryUnavailable)) // false

第二行输出容易误导排查者：字符串确实包含了目标错误的文本。但 errors.Is 不会在整段文本里做子串搜索，它会沿着错误链调用 Unwrap，逐层比较错误值。上面的 %v 只生成了新的文本错误，没有告诉标准库“原错误是谁”。

把 %v 换成 %w，错误链才会继续向上游传递

修复只需要改一个格式动词：

func loadOrder(ctx context.Context, sku string) error {
    if err := queryStock(ctx, sku); err != nil {
        return fmt.Errorf("load order %s: %w", sku, err)
    }
    return nil
}

err := loadOrder(ctx, "SKU-EMPTY")
if errors.Is(err, ErrInventoryUnavailable) {
    // 这里可以走有限次重试或库存降级
}

此时返回错误仍然带有 load order SKU-EMPTY: 前缀，日志可读性没有损失；同时，fmt.Errorf 生成的包装错误实现了 Unwrap() error，上层可以继续遍历。这个组合是 %w 最实用的价值：给人看的上下文和给程序判断的身份同时保留。

errors.Is 和 errors.As 分别解决哪一类判断

把两者混用，是错误处理代码里另一个常见坑。可以先按“判断类别”和“取出对象”来区分：

例如库存服务返回一个带 SKU 和 HTTP 状态码的错误：

type StockError struct {
    SKU        string
    StatusCode int
}

func (e *StockError) Error() string {
    return fmt.Sprintf("stock request failed: sku=%s status=%d", e.SKU, e.StatusCode)
}

func handleStockError(err error) {
    var target *StockError
    if errors.As(err, &target) {
        fmt.Println(target.SKU, target.StatusCode)
    }
}

errors.As 的目标变量要传指针的地址，且目标类型必须和链上的实际类型匹配。若返回的是 StockError 值而不是 *StockError，目标声明也要对应调整；不要只凭错误文本猜类型。

自定义错误的 Unwrap 如何保持可判断性

当需要给错误加上请求号、租户号等字段时，可以让自定义类型保存底层错误，并实现 Unwrap：

type OrderLoadError struct {
    OrderID string
    Err     error
}

func (e *OrderLoadError) Error() string {
    return fmt.Sprintf("order=%s: %v", e.OrderID, e.Err)
}

func (e *OrderLoadError) Unwrap() error { return e.Err }

func loadOrder(ctx context.Context, orderID, sku string) error {
    if err := queryStock(ctx, sku); err != nil {
        return &OrderLoadError{OrderID: orderID, Err: err}
    }
    return nil
}

没有 Unwrap 时，OrderLoadError 只是一个新的错误对象；有了它，errors.Is 与 errors.As 都能穿过这一层。若一个包装层同时需要暴露多个底层错误，可以考虑 Go 1.20 引入的 Unwrap() []error，但普通单错误链不要为了“灵活”增加复杂度。

测试里要验证错误链，而不只是验证 Error 文本

下面的测试能稳定复现修复前后的差异：

func TestLoadOrderKeepsCause(t *testing.T) {
    err := loadOrder(context.Background(), "ORDER-1001", "SKU-EMPTY")
    if err == nil {
        t.Fatal("want error")
    }
    if !errors.Is(err, ErrInventoryUnavailable) {
        t.Fatalf("cause lost: %v", err)
    }

    var orderErr *OrderLoadError
    if !errors.As(err, &orderErr) {
        t.Fatalf("want OrderLoadError, got %T", err)
    }
    if orderErr.OrderID != "ORDER-1001" {
        t.Fatalf("unexpected order id: %s", orderErr.OrderID)
    }
}

如果项目里有统一的错误转换层，也应在这里补一条测试：当错误进入 HTTP handler、消息发布器或日志中间件后，链路是否仍然存在。只比较 err.Error() 的测试很容易让 %v 这种回归混过去。

几个容易踩到的边界

• 不要用 err.Error() == "inventory unavailable" 代替 errors.Is，包装上下文一变就会失效。
• %w 不是“更强的格式化”，它表达的是包装关系；只在确实要暴露底层错误时使用。
• 错误链里可能包含敏感参数，给错误加上下文前先确认不会把令牌、密码或完整请求体写进日志。
• 跨进程传输后的错误通常只剩状态码和文本，不能期待远端的 Go 错误对象自动保留在本地错误链里。

相关问题

errors.Is 会比较错误字符串吗？

不会。它比较错误值或错误链中的可匹配关系；文字相同不代表是同一个错误。

一个错误可以包装多个错误吗？

可以，在适用版本中实现 Unwrap() []error 或使用支持多错误的组合方式；如果只有一个原因，保持单链更容易理解。

什么时候应该用自定义错误而不是哨兵错误？

只需区分固定类别时用哨兵错误；需要携带订单号、状态码、字段名等上下文时，用自定义错误并实现 Unwrap。

把错误处理约定写进代码审查清单

遇到 errors.Is 匹配不到时，先沿返回路径搜索 fmt.Errorf 的格式动词，再检查自定义错误是否实现 Unwrap，最后用单元测试同时覆盖类别判断和字段提取。这样排查通常比盯着一整段错误文本更快，也能把这类问题挡在合并之前。