Go errors.As 怎样提取多层包装错误

在 Go 里，错误经过多层包装后，直接做类型断言通常只能看到最外层。要提取链中某个具体错误类型，应使用 errors.As：它会沿着错误的 Unwrap 关系查找，找到第一个匹配的类型后把值写入目标变量。

最小规则是：包装时用 %w，提取时准备“目标类型的指针”，再用 errors.As(err, &target) 判断是否匹配。返回 false 只是说明链中没有该类型，不代表程序异常。

先确认包装错误链是可遍历的

errors.As 不会解析错误字符串，也不会因为错误信息里出现某个类型名就成功。它依赖错误值本身提供的链：fmt.Errorf 使用 %w 时会保留被包装的错误，标准库和自定义错误也可以通过 Unwrap() error 暴露下一层。

package main

import (
    "errors"
    "fmt"
)

type ParseError struct {
    Field string
}

func (e *ParseError) Error() string {
    return "字段解析失败: " + e.Field
}

func load() error {
    base := &ParseError{Field: "age"}
    // %w 会保留底层错误，调用方才能继续使用 errors.As。
    return fmt.Errorf("读取用户配置: %w", fmt.Errorf("解码请求: %w", base))
}

func main() {
    var target *ParseError
    err := load()
    // target 是目标错误的指针，&target 才是可写入的目标地址。
    if errors.As(err, &target) {
        fmt.Println(target.Field)
    }
}

这里有两层包装，但它们都使用了 %w，因此链条可以从外向内被遍历。如果把其中一个 %w 改成 %v，错误文本仍然看起来完整，类型链却会在那一层断开。

目标参数为什么要写成二级指针

errors.As 的第二个参数不是“类型名称”，而是一个可以被函数写入的目标。对于 *ParseError 这种指针错误，先声明 var target *ParseError，再传 &target，函数成功后 target 才会指向链中的实际错误。

// 目标类型是 *ParseError，所以目标变量要声明成 *ParseError。
var target *ParseError
if errors.As(err, &target) {
    // 匹配成功后再读取字段，避免 target 仍为 nil。
    fmt.Println(target.Field)
}

// 值类型错误则准备值类型变量。
var valueTarget ValueError
if errors.As(err, &valueTarget) {
    // 只有匹配成功后，valueTarget 才是链中的目标值。
    fmt.Println(valueTarget.Code)
}

常见错误是写成 errors.As(err, target)，这会把目标错误的指针直接交给函数，而不是交给函数一个“可以改变 target 的地址”。对于指针实现 error 的类型，看到 var target *T 后再取地址，是最稳妥的判断方式。

多层包装时只接收第一个匹配类型

错误链可能是业务层、传输层和底层解析层逐层添加上下文。errors.As 会从当前错误开始检查，再沿 Unwrap 关系继续查找；遇到第一个满足目标类型的错误就返回 true，并不会把所有同类型错误收集到切片里。

type RequestError struct {
    Op string
}

func (e *RequestError) Error() string { return e.Op }

func request() error {
    inner := &RequestError{Op: "decode"}
    // 两层错误都提供上下文，但最内层类型仍可被提取。
    return fmt.Errorf("handler: %w", fmt.Errorf("client: %w", inner))
}

func readRequest() {
    var target *RequestError
    // false 表示没有 RequestError，不能据此猜测错误文本。
    if errors.As(request(), &target) {
        fmt.Println("操作:", target.Op)
    }
}

因此，类型提取适合回答“这次失败是否属于某一类错误，以及该错误携带了什么字段”。如果业务需要保留每一层上下文，应让外层错误提供清晰的文本或字段，而不是尝试让一次 errors.As 返回多个结果。

未匹配时返回 false，自定义 As 要谨慎

当错误链里没有目标类型时，errors.As 返回 false，目标变量不会成为一个可用的匹配值。调用方应在 if 分支内使用它，不要在匹配失败后读取目标字段。

错误类型还可以实现 As(any) bool，把自身映射成调用方关心的抽象类型。这适合隐藏内部实现、稳定对外契约，但实现者必须负责检查目标类型并正确写入目标；如果只是为了让任何类型都匹配，反而会让错误 API 变得不可预测。

type PublicError struct {
    Kind string
}

func (e *PublicError) Error() string { return e.Kind }

type internalError struct{ kind string }

func (e *internalError) Error() string { return e.kind }

func (e *internalError) As(target any) bool {
    // 只向明确的公开类型映射，避免污染调用方的类型判断。
    p, ok := target.(**PublicError)
    if !ok {
        return false
    }
    *p = &PublicError{Kind: e.kind}
    return true
}

设计包级错误时，还要决定是否把底层实现暴露给调用方：使用 %w 或自定义 As 会成为可被依赖的 API；如果不希望调用方依赖内部错误类型，就不要为了保留信息而无条件暴露它。

一张表记住 errors.As 的写法

排查“为什么提取不到”时，可以按这个顺序看：包装点是否使用 %w；目标变量的类型是否与实际错误一致；指针错误是否传入了目标变量地址；最后再检查是否存在自定义 As 或多错误树的遍历行为。这样处理，多层错误仍能保留上下文，同时让调用方只依赖真正稳定的错误类型。

相关问题

• errors.As 和 errors.Is 有什么区别？ As 按类型提取错误值，Is 按目标错误值或匹配规则判断条件。
• 为什么 %v 包装后 errors.As 失败？ 因为 %v 只生成文本，不会提供 Unwrap 关系。
• errors.As 成功后还要判断 target 是否为空吗？ 对正确实现的目标类型，成功分支会写入匹配值；仍应只在 true 分支读取目标。