Go 自定义错误为什么 errors.As 取不到字段

我第一次遇到这个问题，是在 HTTP 层想把底层的自定义错误字段写进响应：日志里明明打印出了 Code 和 Field，但 errors.As 却一直返回 false。后来发现，字段本身通常没有问题，真正出错的是“目标类型”和“错误链”没有对上。

排查时我会按三层看：调用方传给 errors.As 的目标是否是正确的二级指针，返回路径是否用 %w 保留了自定义错误，最后再确认调用方要匹配的是值类型还是指针类型。

问题现场：日志有字段，As 却返回 false

errors.As 会检查当前错误以及通过 Unwrap() error 或 Unwrap() []error 暴露出来的错误树。它不会扫描 Error() 生成的文字，也不会因为字段名字相同就自动转换类型。

package main

import (
	"errors"
	"fmt"
)

type ValidationError struct {
	Code  string
	Field string
}

func (e *ValidationError) Error() string {
	// 指针接收者表示真正实现 error 的是 *ValidationError。
	return fmt.Sprintf("%s: %s", e.Field, e.Code)
}

func validate() error {
	// 直接返回指针，调用方应以 **ValidationError 作为 As 的目标。
	return &ValidationError{Code: "required", Field: "email"}
}

func main() {
	var target *ValidationError
	if errors.As(validate(), &target) {
		fmt.Println(target.Code, target.Field)
	}
}

这里的 target 先是一个 *ValidationError，再把它的地址 &target 传给 As，所以目标实际类型是 **ValidationError。这是从错误接口中取出指针错误的标准写法。

第一次误判：把错误文字当成了类型传递

为了加上下文，我一度把错误格式化成字符串，再交给上层。这样日志依旧完整，但自定义字段已经不在错误树里了。

func keepType() error {
	// %w 保留 ValidationError，errors.As 才能继续向内查找。
	return fmt.Errorf("保存表单失败: %w", validate())
}

func loseType() error {
	// %v 只复制错误文字，不提供可遍历的 Unwrap 关系。
	return fmt.Errorf("保存表单失败: %v", validate())
}

func readField(err error) string {
	var target *ValidationError
	if errors.As(err, &target) {
		// 命中后再读取字段，避免把文本解析当作业务判断。
		return target.Field
	}
	return "unknown"
}

keepType 和 loseType 打印出来可能只差一个前缀，但前者仍然携带 ValidationError，后者只剩一段消息。修复点应该放在最早添加上下文的地方，而不是让 HTTP 层反向解析字符串。

根因定位：值类型和指针类型并不是一回事

第二次踩坑来自接收者声明。若 Error 方法使用值接收者，ValidationError 和 *ValidationError 都可以满足 error；若使用指针接收者，只有 *ValidationError 满足接口。调用方的目标声明必须和真正放进错误链的动态类型一致。

type FieldError struct {
	Name string
}

func (e FieldError) Error() string {
	// 值接收者让 FieldError 与 *FieldError 都具备 Error 方法。
	return "invalid field: " + e.Name
}

func returnValue() error {
	// 这里放入错误接口的是 FieldError，而不是 *FieldError。
	return FieldError{Name: "email"}
}

func readValue(err error) string {
	var target FieldError
	if errors.As(err, &target) {
		// 目标是 *FieldError，As 会把匹配到的值写入 target。
		return target.Name
	}
	return "unknown"
}

如果把 returnValue 改成返回 &FieldError{...}，读取逻辑也要改成 var target *FieldError 再传入 &target。这不是字段访问语法差异，而是错误接口动态值的差异。

跨层传递：需要字段时给自定义错误补上 Unwrap

自定义错误往往还要携带一个公开哨兵值，让上层既能取字段，又能用 errors.Is 判断大类。此时可以让自定义错误实现 Unwrap() error，把两种判断连接起来。

var ErrInvalidInput = errors.New("invalid input")

type RequestError struct {
	Field string
	Err   error
}

func (e *RequestError) Error() string {
	// Error 负责展示字段和原因，不能代替 Unwrap。
	return e.Field + ": " + e.Err.Error()
}

func (e *RequestError) Unwrap() error {
	// Unwrap 让 errors.As/Is 继续看到内部错误。
	return e.Err
}

func decode() error {
	return &RequestError{Field: "email", Err: ErrInvalidInput}
}

func inspect(err error) (string, bool) {
	var requestErr *RequestError
	if !errors.As(err, &requestErr) {
		return "unknown", false
	}
	// 先取结构化字段，再用 Is 判断共享的错误身份。
	return requestErr.Field, errors.Is(err, ErrInvalidInput)
}

这里要分清职责：As 用来取结构化字段或类型，Is 用来判断共享哨兵。不要为了让 As 成功而把错误文本拼得更像，也不要在 Unwrap 中重复调用 errors.As。

防复发：errors.As 返回 false 时按这张清单排查

我现在处理这类问题的顺序是：先打印动态类型确认错误接口里放的到底是什么，再检查每一层是否保留错误链，最后才看字段名和业务分支。这样能把“字段取不到”从一个模糊症状，缩小到目标类型或包装关系上的具体断点。

相关问题

errors.As 的 target 能不能直接传 nil？不能。它要求 target 是非空指针，并且指向实现 error 的类型或接口；否则会触发 panic。

只需要字段，不需要错误分类，还要实现 Unwrap 吗？如果自定义错误本身就在错误链中，通常不需要；只有还要继续访问内部错误或支持 errors.Is 时才补 Unwrap。

errors.As 能处理 errors.Join 吗？可以，errors.Join 暴露的是多错误树，As 会沿树查找匹配类型；调用方仍要使用正确的目标指针。