Go errors.As 怎么从包装链里取出自定义错误

Go 里如果只用 err.(*MyError) 检查最外层错误，调用方一旦用 fmt.Errorf("读取配置: %w", err) 增加上下文，类型断言就会失效。处理这类错误时，应让 errors.As 沿着包装链查找目标类型；关键是目标变量的类型要和自定义错误真正放进 error 接口时的动态类型一致。

errors.As 查找的对象是整条错误包装链

errors.As(err, target) 先检查当前错误，再按照 Unwrap() error 或 Unwrap() []error 继续查找。fmt.Errorf 中的 %w 会建立这条可遍历关系；如果只写 %v，输出文本看起来一样，但底层类型不会被包装链保留下来。

package main

import (
	"errors"
	"fmt"
)

type QuotaError struct {
	Limit int
}

func (e *QuotaError) Error() string {
	return fmt.Sprintf("quota exceeded: %d", e.Limit)
}

func loadReport() error {
	// 用 %w 保留原始错误，让调用方仍可按类型处理。
	return fmt.Errorf("load report: %w", &QuotaError{Limit: 100})
}

func main() {
	var quotaErr *QuotaError
	if err := loadReport(); err != nil && errors.As(err, "aErr) {
		// 匹配成功后，quotaErr 指向包装链里的原始错误。
		fmt.Println(quotaErr.Limit)
	}
}

这里的目标不是从错误字符串里“猜”出 100，而是获得可访问的 QuotaError 对象。官方文档把 As 定义为查找错误树中第一个匹配项；因此包装层可以负责补充上下文，业务层仍能按结构化字段做决定。

目标变量必须和自定义错误的动态类型对齐

最容易出错的是指针层级。上例把 &QuotaError{} 放入 error，动态类型就是 *QuotaError，所以先声明 var quotaErr *QuotaError，再把它的地址 "aErr 传给 errors.As。As 需要通过 target 写回匹配结果，因而 target 本身必须是非 nil 指针。

如果自定义错误采用值接收者并以值放入接口，目标就应声明为值类型；不要把“实现了 Error 方法”误认为“必然是指针错误”。判断标准只有一个：看生产错误时究竟返回了 MyError{} 还是 &MyError{}。

把直接类型断言迁移成可穿透包装的写法

旧代码常写成下面这样：它只能判断最外层的动态类型，遇到上下文包装便直接走不到分支。

if e, ok := err.(*QuotaError); ok {
	// 这里只检查 err 当前这一层，不能主动穿透 %w。
	return retryWithLimit(e.Limit)
}

迁移时把断言替换为 errors.As，并让判断分支保持原来的业务动作：

func handle(err error) error {
	var quotaErr *QuotaError
	if errors.As(err, "aErr) {
		// 只在类型匹配后读取字段，避免对 nil 目标解引用。
		return retryWithLimit(quotaErr.Limit)
	}
	if errors.Is(err, context.Canceled) {
		// 哨兵值或标准错误用 errors.Is，不和类型匹配混用。
		return nil
	}
	return err
}

errors.As 与 errors.Is 可以连续使用，但职责不同：前者取得一个类型对象，后者判断错误树里是否存在指定错误值。两者都比比较错误文本稳定；生产代码还应保留原始错误作为返回值，避免为了分类丢失上下文。

回归检查要覆盖包装、指针和多错误

迁移完成后，不必运行复杂测试矩阵，先用下面的清单覆盖最常见的边界：

如果一个错误类型需要被视为另一种类型，可以实现 As(any) bool 自定义匹配，但应由该方法负责给 target 赋值。普通业务错误不需要这层扩展；优先让错误类型清晰、包装关系可追踪。

常见问题

errors.As 能按错误消息匹配吗？

不能。它按具体类型或错误自定义的 As 方法匹配；消息应供日志阅读，不应作为程序分支条件。

为什么传 &QuotaError{} 仍然报 target 错误？

通常是把一个新对象的地址当成了 target。正确做法是先声明 var target *QuotaError，再传 &target，让 As 能写回指针。

什么时候应该用 errors.Is？

当代码只关心哨兵错误或可判定的错误值，例如取消、文件不存在时用 errors.Is；需要读取自定义字段时才用 errors.As。

记住这条迁移规则即可：生产方用 %w 保留错误关系，消费方按动态类型准备 target，再用 errors.As 取出结构化信息。