Go fmt.Errorf 包装自定义格式化错误如何保留类型

当底层函数返回自定义错误时，外层通常还要补充“加载哪个字段、执行哪一步”等上下文。fmt.Errorf 只有在格式串中使用 %w，才会把原错误挂进错误链；之后用 errors.As 取回类型和字段。若写成 %v，日志看起来一样，类型信息却已经丢失。

先判断 fmt.Errorf 有没有真的保留错误链

自定义错误最有价值的部分往往不是字符串，而是字段。例如解析失败时，调用方可能需要读取字段名和偏移量，再决定是否提示用户。下面的包装层只改变上下文，不改变内层错误的身份。

package main

import (
    "errors"
    "fmt"
)

type FieldError struct {
    Field string
    Pos   int
}

// 值接收者让 FieldError 和 *FieldError 都满足 error。
func (e FieldError) Error() string {
    return fmt.Sprintf("字段 %s 在位置 %d 无效", e.Field, e.Pos)
}

func load() error {
    inner := FieldError{Field: "email", Pos: 12}
    // %w 才会保留 inner，供 errors.As 继续查找。
    return fmt.Errorf("读取用户配置失败: %w", inner)
}

func main() {
    err := load()
    var fieldErr FieldError
    // As 的第二个参数必须是指向目标类型的指针。
    if errors.As(err, &fieldErr) {
        fmt.Println(fieldErr.Field, fieldErr.Pos)
    }
}

这里的 err 是包装层，fieldErr 才是链中的自定义错误。把 %w 改成 %v 后，输出文字仍会包含“email”，但 errors.As 将返回 false，因为包装层不再提供可遍历的 Unwrap 关系。

值接收者和指针接收者决定 As 的目标

如果错误类型的 Error 方法使用值接收者，值和指针都可以作为 error。上例包装的是 FieldError 值，所以目标写成 var fieldErr FieldError，再传 &fieldErr。

如果改为 func (e *FieldError) Error() string，只有 *FieldError 实现 error，包装时也必须传指针：

// 只有指针类型满足 error，因此 %w 的操作数也传指针。
return fmt.Errorf("保存配置失败: %w", &FieldError{Field: "email", Pos: 12})

var fieldErr *FieldError
// &fieldErr 是 **FieldError，As 会把匹配到的指针写入它。
if errors.As(err, &fieldErr) {
    fmt.Println(fieldErr.Field)
}

这两个写法不能凭感觉混用。实际项目里建议让错误构造方式固定：要么始终包装值并用值目标，要么始终包装指针并用指针目标。这样接口文档、测试和调用方都更清楚。

为什么直接类型断言经常判断失败

下面的断言检查的是最外层动态类型，而不是错误链内部的类型：

// 外层通常是 fmt 包创建的包装错误，这个断言不应作为链路判断。
if _, ok := err.(FieldError); ok {
    fmt.Println("只检查了最外层")
}

// errors.As 会沿 Unwrap 关系查找自定义错误。
var fieldErr FieldError
if errors.As(err, &fieldErr) {
    fmt.Printf("字段=%s，位置=%d\n", fieldErr.Field, fieldErr.Pos)
}

只有在你明确知道没有包装层、并且确实只关心最外层类型时，类型断言才合适。跨函数、跨服务层传递的错误通常会不断增加上下文，errors.As 更能抵抗这种变化。

一张表复查包装边界

还要注意 errors.As 的目标不能是 nil 指针，也不能把“字段值为零”误判为“没有匹配”。先看返回值，再读取目标字段；如果底层错误可能为空，先保留常规的 err != nil 判断。

常见问题

%w 可以包装普通字符串吗？

不可以。%w 的操作数应实现 error；普通描述请用 %v 或先创建一个错误值。

错误只想记录日志，还要用 %w 吗？

如果调用方不需要继续判断类型或哨兵错误，%v 足够；只要错误还会返回给上层，通常应保留链。

多个 %w 怎么办？

现代 Go 支持多个包装错误并形成多错误链。若业务只需要一个主错误，单个 %w 更易读；多个错误则要让调用方明确会匹配哪一个。