Go错误包装必须保留TraceID字段，需自定义TracedError类型嵌入Err和TraceID，实现Error()和TraceID()方法，避免fmt.Errorf("%w")、errors.Join等丢失字段操作，并在HTTP中间件中通过context透传与注入。
Go 错误包装必须保留 TraceID 字段才能透传
Go 原生 error 接口不支持附加字段，直接用 fmt.Errorf 或 errors.Wrap 会丢掉 TraceID。必须让自定义错误类型实现 Error() 方法的同时，暴露可读取的 TraceID() 方法（或其他命名），否则下游日志、中间件根本拿不到它。
- 别用
fmt.Errorf("failed: %w", err)包装带TraceID的错误——%w只递归调用Error()，不继承结构体字段 - 推荐用嵌入方式构造错误：定义
type TracedError struct { Err error; TraceID string }，并在Error()中拼接TraceID字符串 - 如果用
github.com/pkg/errors，它不支持字段透出，得自己写Unwrap()和TraceID()方法，否则errors.Cause()后就只剩底层错误
HTTP 中间件里提取并注入 TraceID 到 context.Context
分布式调用中，TraceID 通常来自 HTTP Header（如 X-Trace-ID），必须在请求入口就解析并塞进 context.Context，后续所有错误包装都应从该 ctx 中取值，而不是靠全局变量或函数参数传递。
- 中间件里用
ctx = context.WithValue(r.Context(), traceKey, traceID)注入，traceKey推荐用私有类型（如type traceKey struct{}）避免 key 冲突 - 不要在 handler 里手动解析 header——重复逻辑易漏，且无法保证所有路径都覆盖
- 如果用了 Gin/Echo，注意它们的
Context是封装过的，需用c.Request.Context()获取原生context.Context - 下游服务调用时，记得从
ctx取TraceID并写入 outbound request header，否则链路断开
errors.Join 会丢掉所有自定义字段，慎用于带 TraceID 的错误聚合
Go 1.20+ 的 errors.Join 返回的是内部 joinError 类型，只保留错误文本和嵌套关系，所有结构体字段（包括 TraceID）全部丢失。一旦你用它合并多个带追踪信息的错误，等于主动放弃定位能力。
- 替代方案：自己写聚合函数，例如返回
struct{ Errors []error; TraceID string }，显式携带TraceID - 如果必须用
errors.Join，确保最外层错误已提前注入TraceID（比如用TracedError{Err: errors.Join(...), TraceID: getTraceID(ctx)}） - 日志打印前检查是否为
joinError：可用errors.As(err, &jerr)尝试转换，但注意它没有公开字段可读
日志输出时别只打 err.Error()，要显式拼接 TraceID
很多日志库（如 log/slog、zap）默认只调用 err.Error()，而如果你的 TracedError.Error() 没包含 TraceID 字符串，或者格式混乱（比如放在末尾被截断），排查时根本没法关联。
立即学习“go语言免费学习笔记（深入）”；
- 强制在
Error()方法里把TraceID放最前面：例如return fmt.Sprintf("[trace:%s] %v", e.TraceID, e.Err) - 用
slog.With("trace_id", getTraceID(ctx))单独打字段，比依赖错误字符串更可靠 - 测试时故意触发一个带
TraceID的错误，用curl -H 'X-Trace-ID: abc123' ...验证日志是否真出现abc123，别只信代码逻辑
TraceID 不是加个字段就完事——它得能被错误链完整携带、被日志稳定捕获、被中间件无损透传。最容易被忽略的是：每次 Wrap 或 Join 都可能切断这个链路，而问题往往在线上压测或偶发故障时才暴露。
