Go fmt.Errorf 怎样正确包装可检查错误

Go 里给错误加上“读取配置失败”“保存用户失败”这类上下文时，最容易出现一个看似合理却难排查的写法：日志信息变完整了，调用方的 errors.Is 却突然判断失败。关键不在错误文本，而在是否保留了底层错误链。

官方地址：https://pkg.go.dev/fmt

先记住结论：fmt.Errorf("读取配置：%w", err) 用 %w 包装底层错误；上层再用 errors.Is 或 errors.As 检查。%v 只能把错误格式化进新文本，适合展示，不适合作为可检查的包装协议。

为什么日志有上下文，errors.Is 却判断失败

假设文件读取层返回一个稳定的哨兵错误，服务层希望补充文件名。两种写法打印出来都可能是“读取配置：文件不存在”，但它们对调用方的含义完全不同。

package main

import (
	"errors"
	"fmt"
)

var errConfigMissing = errors.New("配置文件不存在")

func loadWithText() error {
	// %v 只把底层错误转成文本，新错误不承诺保留原错误链。
	return fmt.Errorf("读取 settings.yaml：%v", errConfigMissing)
}

func loadWithChain() error {
	// %w 用于包装 error，让调用方还能沿链检查原始错误。
	return fmt.Errorf("读取 settings.yaml：%w", errConfigMissing)
}

func main() {
	textErr := loadWithText()
	chainErr := loadWithChain()
	fmt.Println(textErr)
	fmt.Println(errors.Is(textErr, errConfigMissing))
	fmt.Println(chainErr)
	fmt.Println(errors.Is(chainErr, errConfigMissing))
}

这个示例的判断重点不是输出文字，而是最后两个布尔值的语义：文本写法把原错误的信息复制出来了，链式写法则把原错误作为可遍历的底层原因保留下来。生产代码不应再从 Error() 文本中反向解析“文件不存在”。

用 %w 包装单个底层错误

fmt.Errorf 仍然负责组织自然语言上下文，区别只在于底层 error 放在哪个格式动词后面。一个服务层函数通常应该把“动作”和“对象”写进前缀，把真正的失败原因交给 %w。

func readSettings(path string) error {
	data, err := os.ReadFile(path)
	if err != nil {
		// 路径是上下文，err 是需要保留的底层原因。
		return fmt.Errorf("读取配置 %q：%w", path, err)
	}
	_ = data
	return nil
}

上面代码需要导入 os，这里只展示返回约定。调用方可以用 errors.Is(err, fs.ErrNotExist) 判断“文件不存在”，也可以用 errors.As 取得更具体的错误类型。这样日志仍然包含路径，机器判断却不依赖路径或语言描述。

包装层不应该把所有信息都重复一次。底层已经说明“权限不足”时，外层补充操作对象即可；如果每层都把错误全文拼接两遍，日志会变长，却没有增加可用语义。

用 errors.Is 和 errors.As 读取包装结果

errors.Is 解决的是“这条错误链里是否包含某个稳定原因”，errors.As 解决的是“这条错误链里是否有我需要的具体类型”。它们读取的是包装关系，不是错误展示文本。

package main

import (
	"errors"
	"fmt"
	"io/fs"
)

func handle(err error) string {
	if err == nil {
		return "成功"
	}
	if errors.Is(err, fs.ErrNotExist) {
		// Is 适合处理稳定的哨兵语义，不需要比较完整错误字符串。
		return "配置缺失，可走默认配置"
	}
	var pathErr *fs.PathError
	if errors.As(err, &pathErr) {
		// As 取得具体类型后，再读取该类型提供的结构化字段。
		return "路径操作失败：" + pathErr.Op
	}
	return "其它读取失败"
}

func main() {
	// 这里的示例错误带有上下文，Is 和 As 仍可继续检查。
	err := fmt.Errorf("加载配置：%w", &fs.PathError{Op: "open", Path: "settings.yaml", Err: fs.ErrNotExist})
	fmt.Println(handle(err))
}

判断顺序可以按业务优先级调整：先处理最具体的稳定原因，再处理更宽泛的类型。errors.Is 的目标必须适合比较；errors.As 的目标则必须是接收匹配类型的指针。两者都不要求调用方知道中间包了几层。

多层包装、多个 %w 和 nil 怎么处理

错误链可以有多层。底层负责提供原因，中间层负责补充动作，入口层负责决定如何响应。只要每一层对底层 error 使用 %w，最外层调用 errors.Is 时仍能找到目标。

func openUserConfig(path string) error {
	if err := readSettings(path); err != nil {
		// 中间层只补充自己的动作，不拆解或重写底层原因。
		return fmt.Errorf("初始化用户配置：%w", err)
	}
	return nil
}

func loadApp() error {
	if err := openUserConfig("settings.yaml"); err != nil {
		// 最外层继续保留链，入口才可以统一决定错误响应。
		return fmt.Errorf("启动应用：%w", err)
	}
	return nil
}

在当前 Go 标准库语义中，fmt.Errorf 也支持多个 %w，返回错误会保留多个底层原因；不过不要为了“看起来全面”把互不相关的错误随意塞进一个格式串。若错误是并列收集的校验结果，应先明确调用方需要怎样读取，再考虑聚合方式。

nil 也值得单独处理：没有错误时直接返回 nil，不要调用 fmt.Errorf 制造一个“成功但非 nil”的错误。若要包装变量，先判断它是否为空，否则上下文包装本身就会改变返回协议。

什么时候不该用 fmt.Errorf 包装

第一种情况是边界已经要转换协议，例如把内部数据库错误转换成对外的统一错误码。此时可以记录内部原因，再返回明确的外部类型；不要把含有敏感细节的完整错误链直接暴露给客户端。

第二种情况是调用方只需要固定的业务结果，而底层错误不应该跨层传播。是否包装不是“层数越多越好”，而是要判断上层是否确实需要沿链做分支。包装过度会让内部实现细节变成长期兼容负担。

第三种情况是为了展示而格式化。日志、指标标签和用户提示可以使用 %v 或 err.Error()，但如果返回值还要给代码判断，就应保留 %w 的链路。可以把同一个错误用于展示和检查，不要把展示字符串当成检查结果。

常见疑问与判断清单

把 %v 改成 %w 就一定正确吗？

前提是对应操作数实现了 error。如果参数不是 error，%w 不满足包装约定；先确认变量的类型和返回协议，再决定格式动词。

为什么已经包装了，直接 err == target 仍然失败？

直接相等只比较当前值，不能替代沿链检查。对哨兵错误使用 errors.Is，对具体错误类型使用 errors.As。

错误链里的文本可以作为 API 返回吗？

通常不应直接暴露。内部文本可能包含路径、驱动信息或实现细节；对外响应应采用稳定的业务错误结构，并把链留给日志和内部判断。

• 需要保留底层原因时写 %w，只需要拼展示文本时才考虑 %v。
• 判断哨兵错误用 errors.Is，取得具体类型用 errors.As。
• 每一层只补充自己的上下文，不重复拼接完整错误消息。
• 成功路径直接返回 nil，不要把空值包装成非 nil 错误。
• 跨越对外边界时重新设计错误协议，避免泄露内部链路。