Go errors.As 为什么取不到自定义错误：指针接收者与目标类型的匹配边界

Go 里的 errors.As 返回 false，不一定说明错误链里没有目标错误。更常见的原因是：自定义错误是值还是指针，和目标变量声明的类型没有对齐。把这两个层次分开看，问题通常几分钟就能定位。

errors.As(err, &target) 的第二个参数不是“任意错误变量”，而是一个指向目标类型变量的指针；目标类型必须和错误链中实际存放的值兼容。

先看最小可用写法：目标变量要和实际错误对齐

假设订单校验失败时返回一个自定义错误：

package main

import (
    "errors"
    "fmt"
)

type AppError struct {
    Code string
    Msg  string
}

func (e AppError) Error() string {
    return e.Code + ": " + e.Msg
}

func validateOrder() error {
    return AppError{Code: "ORDER_INVALID", Msg: "amount is zero"}
}

func main() {
    err := validateOrder()
    var target AppError
    if errors.As(err, &target) {
        fmt.Println(target.Code)
    }
}

这里的 Error 方法使用值接收者，AppError 和 *AppError 都实现了 error 接口；但 validateOrder 返回的是值，所以目标变量写成 var target AppError 最直接。传入 &target 后，库函数可以把匹配到的错误写回这个变量。

值接收者和指针接收者，实际匹配的是两种类型

最容易混淆的是“实现了 error 接口”和“能被 errors.As 匹配”是两件事。若错误构造时改为返回指针：

func validateOrder() error {
    return &AppError{Code: "ORDER_INVALID", Msg: "amount is zero"}
}

var target AppError
matched := errors.As(err, &target) // false：链中是 *AppError

此时应该让目标也表达为指针：

var target *AppError
if errors.As(err, &target) {
    fmt.Println(target.Code)
}

注意这里出现了两层指针含义：target 的类型是 *AppError，而传给 errors.As 的是 &target，类型自然是 **AppError。第二层不是错误对象本身，而是让函数能够回填目标变量。

使用场景怎么选：返回值还是指针

小型、只读、字段不多的错误，用值返回通常更容易读；错误带有较大上下文、需要统一修改字段，或项目约定所有领域错误都用指针时，可以返回指针。真正重要的是在一个包内保持约定，不要让调用方猜。

适合返回值错误的场景

错误结构很小，创建后不会改变，而且调用方只需要读取错误码和提示文本。此时 AppError 的值形态清楚，测试也不必额外处理空指针。

适合返回指针错误的场景

错误含有较多上下文，或者必须区分“没有匹配到”和“匹配到了一个零值对象”。这类场景使用 *AppError 时，记得在目标变量声明上保留指针类型。

错误链能不能查到，取决于包装方式

类型对齐后，如果仍然返回 false，再检查中间的包装是否保留了原错误：

func loadOrder() error {
    err := validateOrder()
    if err != nil {
        return fmt.Errorf("load order: %w", err)
    }
    return nil
}

err := loadOrder()
var target AppError
if errors.As(err, &target) {
    fmt.Println(target.Code)
}

%w 会把原错误放进可遍历的错误链。若改成普通的 %v，输出文本看起来仍然包含原错误，但类型信息已经丢失，errors.As 没有可匹配的对象。

一段测试把三种边界一次验完

不要只断言最终返回字符串。测试里分别覆盖值错误、指针错误和错误链，后续有人改构造方式时，失败位置会很明确：

func TestErrorsAsShape(t *testing.T) {
    valueErr := AppError{Code: "VALUE"}
    var valueTarget AppError
    if !errors.As(valueErr, &valueTarget) {
        t.Fatal("value error should match AppError")
    }

    pointerErr := &AppError{Code: "POINTER"}
    var pointerTarget *AppError
    if !errors.As(pointerErr, &pointerTarget) {
        t.Fatal("pointer error should match *AppError")
    }

    wrapped := fmt.Errorf("outer: %w", pointerErr)
    var wrappedTarget *AppError
    if !errors.As(wrapped, &wrappedTarget) {
        t.Fatal("wrapped pointer error should match")
    }
}

如果业务代码统一返回 error，这组测试也能提醒维护者：改成指针返回后，调用方的目标变量要同步改动，而不是只看编译器能不能通过。

常见误区与一个可执行的排查顺序

第一，别把 errors.Is 和 errors.As 混为一谈：前者回答是否等于某个已知错误，后者回答能否取出某种类型。第二，别看到 **AppError 就认为错误链里有二级指针，它通常只是“指向目标变量的指针”。第三，检查包装格式时优先搜索 %w，不要被日志里的错误文本骗过。

实际排查可以按这个顺序走：打印或查看构造点，确认返回的是值还是指针；查看 Error 方法的接收者；核对目标变量类型；最后沿每一层包装检查是否保留了 %w。这个顺序比在调用点反复更换 target 声明更快。

相关问题

errors.As 的第二个参数为什么必须是指针？

因为函数需要把链中找到的目标写回调用方变量。传入目标变量的地址，函数才有修改它的能力。

把 %w 改成 %v 后为什么日志没变化？

日志只是字符串，仍可能显示原错误文本；但 %v 不保留可供标准库遍历的包装关系，因此类型匹配会失败。

值错误和指针错误应该统一哪一种？

优先遵循项目已有约定。无论选哪一种，都要让构造点、目标变量和测试保持同一类型形态。

小结

errors.As 的匹配失败，通常落在三个检查点：错误实际是值还是指针、目标变量是否声明成对应类型、包装是否使用了 %w。把这三点按顺序核对，基本可以在不改动业务逻辑的情况下定位问题。