错误包装

来源：17golang原创 2026-11-11 17:02:09 0浏览收藏

Go 的错误包装，关键不在日志文字长不长，而在新错误是否保留了原错误链。用 fmt.Errorf("读取配置: %w", err) 增加上下文，errors.Is 仍能找到底层错误；如果把同一位置写成 %v，打印结果可能几乎一样，但匹配会失败。需要让上层按根因分支时用 %w，只想生成一条展示文本时才用 %v。

官方文档：https://pkg.go.dev/fmt　https://pkg.go.dev/errors

要点速览

%w 会为错误包装提供 Unwrap，errors.Is 才能继续查找。
%v 只负责格式化文本；日志相同，不代表错误语义相同。
错误链留给程序判断，错误文本留给人阅读，两者不要混用。

先用同一个错误看清两种写法

下面故意让两条错误都包含相同的上下文。区别只在包装动词，因此更容易定位“看起来一样、判断却不同”的原因。

package main

import (
    "errors"
    "fmt"
)

var ErrQuota = errors.New("quota exceeded")

func withChain() error {
    // %w 保留 ErrQuota，让调用方可以继续检查错误链。
    return fmt.Errorf("保存订单失败: %w", ErrQuota)
}

func withTextOnly() error {
    // %v 只把错误格式化进文本，不建立可遍历的包装关系。
    return fmt.Errorf("保存订单失败: %v", ErrQuota)
}

func main() {
    fmt.Println(withChain())
    fmt.Println(errors.Is(withChain(), ErrQuota))
    fmt.Println(withTextOnly())
    fmt.Println(errors.Is(withTextOnly(), ErrQuota))
}

两条错误打印出来都带有“保存订单失败: quota exceeded”，但最后两个判断分别是 true 和 false。因此不能用日志是否相同来判断包装是否成功。

判断依据是 Unwrap，不是错误字符串

fmt.Errorf 的格式串包含 %w 且参数实现了 error 时，返回值会实现返回底层错误的 Unwrap() error。errors.Is 会先比较当前错误，再沿着 Unwrap 继续向下查找；这也是它比 err == ErrQuota 更适合处理包装错误的原因。

Go fmt.Errorf 使用 %w 保留错误链并由 errors.Is 向下匹配的静态结构说明图 — 图1：错误链结构说明图；%w 连接上下文错误与根因，%v 只生成文本。

可以把它理解成两条不同的数据路径：

写法	输出文本	错误链	适合场景
`%w`	有上下文	保留，可被 Is/As 查找	跨层返回、需要分类处理
`%v`	有上下文	不保留	只做展示或最终日志

服务层包装、调用层判断的落地方式

推荐让每一层只补充自己知道的上下文，把是否重试、返回什么状态码等决策放在更上层。这样既保留定位信息，也不会让底层包依赖业务层的处理策略。

func saveOrder() error {
    if err := persist(); err != nil {
        // 这一层只补充动作和对象，不吞掉底层原因。
        return fmt.Errorf("保存订单: %w", err)
    }
    return nil
}

func handle() error {
    err := saveOrder()
    if errors.Is(err, ErrQuota) {
        // 依据哨兵错误做稳定分支，不依赖中文错误文本。
        return fmt.Errorf("请求过于频繁，请稍后重试")
    }
    return err
}

如果最终只需要写日志或把错误传给不再做判断的边界，%v 可以接受；但在中间层使用它，会切断后续的 errors.Is 和 errors.As。