Go errors.As 包装指针错误时目标变量该怎么声明

我在给服务层补错误分流时，最常见的误会就是把 errors.As 当成“传入想要的错误类型”。实际上，第二个参数是一个指向目标变量的指针：如果自定义错误由值实现 error，通常声明 var target MyError，传入 &target；如果只有指针类型实现 error，就声明 var target *MyError，再传入 &target，此时参数类型是 **MyError。

判断规则可以压缩成一句话：先看哪个具体类型实现了 error，再声明那个类型的变量，最后把这个变量的地址交给 errors.As。指针错误因此会自然多出一层指针。

先确认哪一个类型真正实现了 error

不要先凭变量名猜层级，先看 Error 方法的接收者。下面两个类型的差别决定了 target 的写法：

type ValueError struct { Code int }

// 值接收者：ValueError 和 *ValueError 都满足 error。
func (e ValueError) Error() string {
	// 返回稳定的错误描述，业务字段仍保留在 e 中。
	return fmt.Sprintf("value error: %d", e.Code)
}

type PointerError struct { Code int }

// 指针接收者：只有 *PointerError 满足 error。
func (e *PointerError) Error() string {
	// 指针接收者允许错误对象携带可变或较大的上下文。
	return fmt.Sprintf("pointer error: %d", e.Code)
}

因此，值错误可以按值存进 error，也可以按指针存进；指针错误则必须以 *PointerError 的形式进入错误链。这个事实比“错误有没有被包装”更早决定声明方式。

errors.As 传的是目标变量的地址

errors.As(err, target) 会在错误树中找到第一个可赋值的错误，并把它写入 target。也就是说，target 不是类型名，而是“结果要写到哪里”的地址。

var valueTarget ValueError
// ValueError 本身实现 error，所以 target 是 *ValueError。
if errors.As(err, &valueTarget) {
	fmt.Println(valueTarget.Code)
}

var pointerTarget *PointerError
// *PointerError 才实现 error，所以 target 是 **PointerError。
if errors.As(err, &pointerTarget) {
	fmt.Println(pointerTarget.Code)
}

这里的 &pointerTarget 看起来像“多取了一次地址”，其实正是让 errors.As 有机会把找到的 *PointerError 写回变量。若直接传 pointerTarget，它是 nil 指针，不是一个可写入的目标，调用会触发 panic。

用 %w 保留包装链，再判断匹配结果

声明正确还不够，产生包装错误时也要保留链。下面的例子把指针错误放进业务上下文，调用方仍可取出 Code：

package main

import (
	"errors"
	"fmt"
)

func load() error {
	// 指针错误进入 error 接口，后续用 errors.As 做类型分流。
	return &PointerError{Code: 503}
}

func handle() {
	err := load()
	// %w 保留原始错误，前缀只补充当前调用位置。
	err = fmt.Errorf("load profile: %w", err)

	var target *PointerError
	if errors.As(err, &target) {
		// 匹配成功后再读取字段，避免 target 仍为 nil。
		fmt.Println("code:", target.Code)
		return
	}
	// 未匹配时走通用错误路径，不假定具体类型存在。
	fmt.Println("unknown error:", err)
}

如果把 %w 改成普通的 %v，打印结果仍可能包含原错误文本，但类型链已经断开，errors.As 不会因为文字相同而匹配成功。多错误场景下，Go 会按错误树查找，并返回先遇到的可匹配类型。

遇到 panic 或 false 时按四项清单排查

还有一个容易漏掉的边界：传入 nil 的 err 会返回 false；目标变量本身可以是 nil，但传入的必须是非 nil 的指针，并且指向实现了 error 的类型或接口。自定义 As(any) bool 方法还能改变匹配方式，排查时要把它当作类型自己的额外规则。

常见问题

为什么声明了 var target *MyError 还要传 &target？

因为 target 是待写入的错误指针，errors.As 需要它的地址才能把链中的 *MyError 写回，所以参数类型是 **MyError。

值接收者的错误也能声明成指针吗？

可以，但匹配的具体类型必须和错误链中的动态类型一致。若链中存的是 ValueError，用 var target ValueError；若存的是 *ValueError，用 var target *ValueError。

什么时候应该用 errors.Is？

只关心固定哨兵错误或等价关系时用 errors.Is；需要取出具体类型并读取字段时用 errors.As。