17370845950

Go 1.20+ 错误链基石是 errors.Join 和 fmt.Errorf 的 %w：前者聚合多错误并支持遍历，后者单层包装添加上下文；二者均通过 Unwrap() 实现链式访问，配合 errors.Is/As 可穿透多层判断，自定义错误需显式实现 Unwrap 才能参与链式检查。

Go 1.20+ 的 errors.Join 和 fmt.Errorf 带 %w 是错误链的基石

Go 错误链（error chain）不是靠自定义结构体或第三方库实现的，而是语言原生支持：只要错误值实现了 Unwrap() error 方法，就能被 errors.Is、errors.As 和 errors.Unwrap 识别为链式节点。标准库中 fmt.Errorf("...", %w) 和 errors.Join(...) 生成的错误天然满足这一点。

关键点在于：%w 不是格式化占位符，而是“包装指令”——它会让新错误持有对原错误的引用，并暴露 Unwrap() 方法；而 errors.Join 则用于合并多个独立错误（比如并发任务中多个 goroutine 同时失败），返回一个可遍历所有子错误的复合错误。

• fmt.Errorf("failed to parse config: %w", err) → 单层包装，适合添加上下文
• errors.Join(err1, err2, err3) → 多错误聚合，errors.Unwrap 会返回 nil，但 errors.UnwrapAll（需自行实现）或遍历 errors.Frame 需配合 errors.Cause 类逻辑（实际用 errors.Is 检查更稳妥）
• 多次 %w 包装不会自动“扁平化”，errors.Is 会逐层 Unwrap 直到匹配或返回 nil

用 errors.Is 和 errors.As 判断错误类型比直接比较更可靠

直接用 == 或 errors.Is(err, os.ErrNotExist) 看似简单，但一旦中间有包装层就会失效。例如：

err := fmt.Errorf("read file failed: %w", os.ErrNotExist)
if err == os.ErrNotExist { // false
    // ...
}

正确做法是始终用 errors.Is 检查目标错误是否在链中存在：

• errors.Is(err, os.ErrNotExist) → 返回 true，无论包装几层
• errors.As(err, &pathErr) → 尝试将链中任意一层的错误赋值给 pathErr（需是 *os.PathError 类型指针）
• 注意：errors.As 只找第一个匹配项，不保证是最近一层；若需精确获取某层包装，得手动 errors.Unwrap 多次

自定义错误类型加 Unwrap 方法才能参与链式判断

如果你写了一个带字段的错误结构体（比如含重试次数、请求 ID），想让它也能被 errors.Is 正确识别，就必须显式实现 Unwrap() error：

type MyError struct {
    Msg   string
    Code  int
    Cause error
}
func (e MyError) Error() string { return e.Msg }
func (e MyError) Unwrap() error { return e.Cause }

这样 errors.Is(myErr, io.EOF) 才能穿透 MyError 找到内部的 Cause。漏掉 Unwrap 方法，整个错误就变成链的“终点”，无法继续向下检查。

• 如果 Cause 是 nil，Unwrap() 必须返回 nil，否则 errors.Is 会 panic
• 不要在 Unwrap 中做计算或日志，它可能被频繁调用
• 避免循环引用：A.Wrap(B), B.Wrap(A) —— errors.Is 会因无限递归 panic

调试时用 fmt.Printf("%+v", err) 查看完整错误链和栈帧

默认 fmt.Println(err) 只打印最外层错误文本，丢失上下文和堆栈。用 %+v 格式符能展开整个链，并显示每层的文件/行号（前提是包装时用了 fmt.Errorf，且 Go 版本 ≥ 1.19）：

err := fmt.Errorf("service timeout: %w", fmt.Errorf("http call failed: %w", os.ErrPermission))
fmt.Printf("%+v\n", err)

输出类似：

service timeout: http call failed: permission denied
    ma
in.go:12
  - http call failed: permission denied
    main.go:11
  - permission denied

这个输出依赖运行时的 runtime.CallersFrames，所以务必确保：

• 没用 errors.New 或 fmt.Errorf 不带 %w 的方式覆盖原始错误（会丢帧）
• 生产环境若关闭了帧信息（如通过 GODEBUG=asyncpreemptoff=1），%+v 也会降级为普通字符串
• 第三方日志库（如 zap）需启用 Stacktrace 配置才能捕获这些帧

错误链真正难的不是怎么建，而是怎么不建错：包装时机不对、Unwrap 返回非预期值、过度嵌套导致栈帧膨胀，都会让排查变得更慢而不是更快。