错误包装

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

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

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

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

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 更适合处理包装错误的原因。

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

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

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

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。

几个容易误判的边界

• 包装参数必须是 error。把普通字符串或数字放在 %w 后面不是正确的错误链设计；需要格式化普通值时用 %v 或其他动词。
• 不要比较错误文本。文案会随着上下文、翻译和日志策略变化；可比较的哨兵错误或自定义 Is 方法更稳定。
• nil 仍要先判断。只有在底层返回非 nil 错误时才包装，避免把“没有错误”写成一条新错误。
• 测试要同时测文本和语义。文本断言检查用户可读性，errors.Is 断言检查调用契约，两者用途不同。

常见问题

%w 和 %v 的日志输出一定不同吗？

不一定。对普通错误参数，它们经常产生相同的文本；真正的差异是是否保留错误链。

已经用了 %v，还能在上层恢复原错误吗？

通常不能。原错误只剩在字符串里，除非你另行传递结构化错误值，否则无法可靠地恢复。

什么时候应该直接返回原错误？

当当前层没有新增上下文时可以直接返回；只要补充了操作、对象或阶段信息，就用 %w 保留根因。

记忆这条边界即可：错误文本服务人，错误链服务程序。需要让程序继续判断，就用 %w；只需要一次性展示，才考虑 %v。