Go errors 用 As 匹配包装类型

在 Go 服务里，底层错误经常会被一层层补充上下文。直接写类型断言时，最外层可能已经变成了 fmt.wrapError，于是明明还能看到原始错误文本，却拿不到它的字段。解决办法是让包装链保持为 %w，再用 errors.As 沿错误树查找目标类型。

本文用一个带路径字段的自定义错误说明完整写法：errors.As(err, &target) 中的第二个参数不是错误值本身，而是“接收匹配结果的目标变量地址”。匹配成功后，就可以安全读取目标类型的字段；匹配失败时则继续走通用错误分支。

为什么包装之后的类型断言会失效

先定义一个业务层想识别的错误类型，再模拟底层调用和上层补充上下文。如果中间使用 %w，错误关系会被保留下来；但传统的类型断言只看当前这一层。

package main

import (
    "errors"
    "fmt"
)

// PathError 保存调用方需要展示或记录的路径信息。
type PathError struct {
    Path string
    Op   string
}

// Error 让 PathError 满足 error 接口。
func (e *PathError) Error() string {
    return fmt.Sprintf("%s %s failed", e.Op, e.Path)
}

// loadConfig 模拟底层函数返回具体错误。
func loadConfig() error {
    return &PathError{Path: "/etc/demo/app.yaml", Op: "read"}
}

func main() {
    err := loadConfig()
    if err != nil {
        // %w 会保留可供 errors.As 继续查找的包装关系。
        err = fmt.Errorf("load service config: %w", err)
    }

    // 直接断言只检查 err 当前这一层，包装后通常会失败。
    if _, ok := err.(*PathError); !ok {
        fmt.Println("direct assertion: not matched")
    }

    // 输出错误文本仍能看到原始信息，但文本不等于类型匹配。
    fmt.Println(err.Error())

    // errors.As 会继续向 Unwrap 返回的错误查找目标类型。
    var target *PathError
    if errors.As(err, &target) {
        fmt.Println("matched:", target.Op, target.Path)
    }
}

这里的关键不是把错误字符串拆出来，而是保留错误对象本身。若把 %w 改成 %v，输出文本看起来仍然相似，但调用方无法再通过 errors.As 访问被包住的 PathError。

用 errors.As 取出包装链中的目标类型

最常见的写法是先声明一个目标指针，再把它的地址传给 errors.As。函数返回 true 时，目标变量已经被设置为匹配到的错误对象；返回 false 时不要读取目标字段。

func classify(err error) string {
    // 目标变量的类型决定了 As 要寻找的具体错误类型。
    var pathErr *PathError
    if errors.As(err, &pathErr) {
        // 只有匹配成功后才能安全使用 PathError 的字段。
        return fmt.Sprintf("路径操作失败：%s %s", pathErr.Op, pathErr.Path)
    }

    // 未匹配到目标类型时保留通用错误处理。
    if err != nil {
        return "其他错误：" + err.Error()
    }
    return "没有错误"
}

As 会先检查当前错误，再继续检查它通过 Unwrap() error 或 Unwrap() []error 暴露出的子错误。也就是说，目标类型可以在多层上下文中，调用方不必知道中间增加了多少层日志前缀。

自定义错误与接口目标怎么写

如果目标是一个具体错误类型，通常使用指针变量；如果目标是某个错误接口，则需要把接口变量的地址传给 As。接口目标适合表达“具备某种能力”，例如错误是否提供临时性或超时信息，而不是绑定到某个包的具体结构。

type temporary interface {
    error
    Temporary() bool
}

func isTemporary(err error) bool {
    // 指向接口变量的指针是这里的合法目标形式。
    var t temporary
    if errors.As(err, &t) {
        // 先确认匹配成功，再调用接口方法。
        return t.Temporary()
    }
    return false
}

目标必须是非 nil 指针，并且指向实现了 error 或相关接口的类型；否则程序会在调用时触发 panic。不要把一个已经构造好的错误值直接传入，例如 errors.As(err, pathErr)，那不是用于接收结果的地址。

还要注意自定义错误的接收者形式。若 Error() 定义在指针接收者上，目标就应声明为 var target *PathError；若定义在值接收者上，目标类型也要跟实际返回的值或指针形式保持一致。类型不同，即使字段看起来相同，也不会匹配。

As、Is 和多错误包装如何选择

这三个判断解决的问题不同，可以按“我要拿到什么”来选：

func handle(err error) string {
    // 该片段需要 import "os"，以使用 os.ErrNotExist。
    // Is 用于判断固定错误值，不需要接收具体对象。
    if errors.Is(err, os.ErrNotExist) {
        return "配置文件不存在"
    }

    // As 用于拿到 PathError 的路径和操作字段。
    var pathErr *PathError
    if errors.As(err, &pathErr) {
        return "路径错误：" + pathErr.Path
    }

    // 两种判断都未命中时，返回通用信息。
    return "未分类错误"
}

如果函数返回的是 errors.Join(errA, errB)，调用方仍然可以用 errors.As 或 errors.Is 搜索整棵错误树。不要用字符串包含判断替代它们：错误文本适合日志和展示，类型与哨兵值才适合程序分支。

常见误区与速查

• 包装上下文时使用 %w，需要向调用方暴露底层错误时尤其如此。
• 目标变量要声明成期望的具体类型或接口类型，再传入它的地址。
• 只有 As 返回 true 后，才读取目标变量字段。
• 要判断固定值用 Is，要取得类型对象用 As，不要混用。

把一句话记住即可：errors.As 负责“从包装错误树里取出我关心的类型”，errors.Is 负责“这棵树里有没有这个固定错误”。只要包装关系使用 %w 保持下来，上层代码就能在增加上下文的同时继续做稳定的错误分流。

相关问题

errors.As 能不能替代所有类型断言？

不能。对没有包装关系的普通值，直接断言仍然可以工作；当错误可能被包装或来自多层调用时，优先使用 errors.As。

为什么 errors.As 的目标参数要传指针？

因为 As 需要把匹配到的错误写入调用方变量，所以传入的是目标变量的地址，而不是一个只读的错误值。