Go语言中利用错误包装函数保留底层系统调用的完整Trace树

Go 1.20+ 里用 fmt.Errorf("%w") 包装系统调用错误，有个坑——它会悄悄丢掉底层 syscall.Errno 的类型信息。直接这么包装，上层想精准判断错误类型？基本没戏，比如区分 syscall.ENOENT 和 syscall.EACCES 就会失效，trace 的可追溯性也跟着崩了。

根子就在这儿：%w 这个格式化动词，只负责保留 Unwrap() 链，但很多系统错误，比如 *os.PathError，它的 Unwrap() 返回的是 error 接口，而不是具体的 syscall 错误类型。中间但凡跳一步，链子就断了。

那怎么解决？业界的主流做法有这么几条路：

• 用 errors.Join，或者手动构造一个带多层 Unwrap() 的 wrapper，确保原始的 syscall.Errno 能被逐层解包。
• 更稳妥的方式，是在包装之前先用 errors.As(err, &errno) 把底层错误显式提取出来，然后通过自定义的 error 类型存起来。
• 千万别用 fmt.Errorf 来回嵌套包装——每套一层 %w，不仅增加解包开销，类型保真度也没保证。

Go 1.20+ 的 fmt.Errorf 包装会丢失底层 syscall.Errno 类型

直接用 fmt.Errorf("failed: %w", err) 包装系统调用错误——比如 os.Open 返回的 *os.PathError——会导致原始错误类型信息被抹除。尤其是那个关键的 syscall.Errno 值。这让上层无法做精准的错误判断，比如区分 syscall.ENOENT 和 syscall.EACCES，trace 的可追溯性也跟着受损。

根本原因在于 %w 仅保留 Unwrap() 链，但很多系统错误（如 *os.PathError）的 Unwrap() 返回的是 error 接口而非具体 syscall 错误类型，中间一断开，链子就断了。

• 正确做法：用 errors.Join 或手动构造带多层 Unwrap() 的 wrapper，确保原始 syscall.Errno 可被逐层解包。
• 更稳妥的方式是显式检查并保留底层 syscall.Errno：在包装前先用 errors.As(err, &errno) 提取，再通过自定义 error 类型存起来。
• 避免用 fmt.Errorf 多次嵌套包装——每套一层 %w 就增加一次间接解包开销，且不保证类型保真。

自定义 wrapper 必须实现 Unwrap() 和 Is() 才能参与错误匹配

光实现 Unwrap() 可不够。Go 的 errors.Is 和 errors.As 会递归调用 Is() 方法（如果存在），否则才 fallback 到 Unwrap() 链。而标准库里 syscall.Errno 的 Is() 是基于值比较的，你的 wrapper 若没透传过去，errors.Is(err, syscall.ENOENT) 就会失败。

举个例子：

type OpError struct {
    Op  string
    Err error
}

func (e *OpError) Error() string { return e.Op + ": " + e.Err.Error() }
func (e *OpError) Unwrap() error { return e.Err }

// ❌ 缺少 Is() —— errors.Is(e, syscall.ENOENT) 总是 false

// ✅ 应该加：
func (e *OpError) Is(target error) bool {
    if errors.Is(e.Err, target) {
        return true
    }
    // 如果 target 是 syscall.Errno，也尝试直连底层 errno 值
    var errno syscall.Errno
    if errors.As(e.Err, &errno) && errors.Is(errno, target) {
        return true
    }
    return false
}

runtime/debug.Stack() 不能替代错误 trace，它只记录当前 goroutine 调用栈

有人会在 wrapper 的 Error() 方法里拼接 debug.Stack() 输出，想着“模拟 trace”。这是个误区：栈快照是静态的，只反映错误创建时刻的调用路径，根本没法体现错误在传播过程中经过哪些 handler、middleware 或 retry loop。真正的 trace 树依赖的是 Unwrap() 链的动态可遍历性。

• 真正需要 trace 时，用 errors.Unwrap 循环解包，配合 fmt.Printf("%+v", err)（需启用 go run -gcflags="-l" ... 才显示行号）。
• 生产环境建议用 github.com/pkg/errors 的 WithStack——但它已不维护；更推荐 golang.org/x/exp/errors（实验包）或自己封装带 Frame 字段的 error 类型。
• 注意：debug.Stack() 本身有性能开销（分配 KB 级内存），绝不应在高频路径中调用。

HTTP handler 中传递错误时，http.Error 会切断 Unwrap() 链

一个典型反模式：if err != nil { http.Error(w, err.Error(), http.StatusInternalServerError); return }。这等于把原始 error 转成了纯字符串，trace 树彻底丢失。

正确的做法分两层：

• 开发/调试环境：用 fmt.Fprintf(w, "%+v", err) 输出带栈帧和 Unwrap() 链的完整结构——前提是你的 wrapper 实现了 fmt.Formatter 接口。
• 生产环境：提取关键错误码（如 errors.Is(err, syscall.ENOENT)）映射为 HTTP 状态码，同时记录完整 error 对象到日志（用 log.Printf("op=xxx err=%+v", err)）。
• 绝对不要在响应体里暴露原始 error 字符串——既不安全，又破坏 trace 结构。

说到底，trace 树不是靠打印出来的，是靠 Unwrap() 链活着的。一旦转成字符串，就彻底死了。