go-omni/reports/headerPropagationAcceptance.md

Header 传播适配验收

范围

本次为 go-omni 增加通用 telemetry.HeaderPropagator。调用方配置 Trace ID、Span ID 和可选 Request ID Header 后，框架负责入站父链路、日志关联、访问日志和出站传播；框架不识别任何网关名称，也不解析业务 Header。

标准 W3C traceparent 与兼容 Header 同时出现时优先 W3C。兼容 Header 必须是合法的 32 位 Trace ID 和 16 位 Span ID；旧 Header 没有采样位，合法成对值按已采样处理。Request ID 只用于关联，不参与 Span 父子关系。兼容传播只应放在已校验 Header 的受信入口。

验收结果

• GO_OMNI_SCAFFOLD_INTEGRATION=1 go test -count=1 ./...：通过，包含生成器、生命周期、存储、i18n、telemetry 和离线示例。
• go test -race ./telemetry ./examples/telemetryHeaders：通过。
• GO_OMNI_SCAFFOLD_INTEGRATION=1 GOTOOLCHAIN=go1.22.12 go test -count=1 ./...：通过。
• go vet ./...、go build ./...、git diff --check：通过。
• go run ./examples/telemetryHeaders：通过，示例打印固定 Trace ID、Request ID 和 JSON 响应。

完整竞态套件在高并发生成器生命周期用例中出现了已有的时序超时（TestGeneratedMainLifecycle/drainBeforeClose、TestGeneratedBackgroundPhases/nethttp）；单独重跑受影响的 TestManagedGeneratedProject 通过，功能定向竞态测试通过，未发现本次 Header 传播相关竞态。

代码边界

• 默认 telemetry.Config 仍使用 W3C 传播，未配置新适配器的项目行为不变。
• telemetry.Transport 在兼容模式下同时注入 W3C 与配置 Header，调用方请求对象不会被修改。
• 无效 ID、重复 Header 名称以及试图覆盖 traceparent / tracestate 的配置会被拒绝或忽略。
• 不增加认证、租户、幂等、业务重试或网关依赖。