该用 fmt.Errorf 套 %w 而非 %v 是为了保留原始错误类型和链路，使 errors.is/as 正常工作；%v 会丢失底层错误，导致判定失败。
什么时候该用 fmt.Errorf 套 %w，而不是 %v
用 %w 是为了保留原始错误的底层类型和链路，让 errors.Is 和 errors.As 能继续工作；用 %v 就断了——它只转成字符串再包一层，原始错误彻底“失联”。
- 常见错误现象：
errors.Is(err, io.EOF)返回false，明明上游确实返回了io.EOF，但你用了fmt.Errorf("read failed: %v", err) - 正确做法：必须写
fmt.Errorf("read failed: %w", err)，%w后面只能跟一个error类型值 - 注意：如果 err 是
nil，%w会自动透传nil，不会 panic，这点比很多人想的更安全
errors.Wrap（来自 github.com/pkg/errors）和标准库 fmt.Errorf + %w 的实际差异
标准库从 go 1.13 开始支持 %w，pkg/errors 的 Wrap 本质是早期兼容方案。现在二者行为高度一致，但仍有关键区别。
- 堆栈信息：
pkg/errors.Wrap默认捕获调用点堆栈，标准库fmt.Errorf+%w不带堆栈（除非你手动用errors.WithStack或第三方库） - 类型兼容性：用
pkg/errors包装过的错误，errors.Is和errors.As在 Go 1.13+ 仍能正常识别被包装的底层错误，没问题 - 性能影响：标准库无额外依赖、无反射、无运行时堆栈采集，开销更低；
pkg/errors每次Wrap都做一次 runtime.Caller，压测下可观测到差异
为什么不能对同一个错误反复用 %w 包装？
不是语法错误，但会导致错误链冗余、调试困难，甚至触发某些工具误判（比如错误去重逻辑或监控告警规则匹配）。
- 常见错误场景：中间层函数收到 err → 用
%w包一层 → 上层又用%w包一次 → 日志里看到 “failed to save user: failed to save user: failed to exec query…” - 根本原因：每个
fmt.Errorf(... %w)都生成新 error 实例，但原始错误未被修改，链路变长却没新增有效上下文 - 建议做法：只在语义边界处包装一次，比如从 DB 层到 service 层、从 http handler 到业务逻辑层；同一层内不要“接力包装”
- 检查方法：打印
fmt.printf("%+v", err)（需配合支持 %+v 的 error 实现，如github.com/pkg/errors或 Go 1.20+ 的errors.format）
自定义 error 类型加装饰字段时，Unwrap 方法怎么写才不踩坑
如果你实现了一个带额外字段（比如 Code、TraceID）的 error，并希望它能参与标准错误链，Unwrap 必须严格返回被包装的 error，且不能在 Unwrap 里做任何副作用或条件判断。
立即学习“go语言免费学习笔记（深入）”；
- 典型错误：在
Unwrap里加日志、调用外部服务、或根据某个 flag 返回 nil —— 这会让errors.Is行为不可预测 - 正确写法：只返回内部持有的
err字段，哪怕它是nil；如果没包装其他 error，就返回nil - 注意：Go 1.20+ 引入了
errors.Join，它的Unwrap返回多个 error，此时你的自定义类型若要兼容，得自己处理多值解包逻辑（通常不建议混用）
事情说清了就结束。真正难的不是选哪种包装方式，而是每次包装前想清楚：这个 error 接下来会被谁检查？靠 Is 判定类型？靠 As 提取上下文？还是只用来打日志？漏掉这步，后面所有包装都是徒劳。