Go RoundTripper 怎样注入追踪请求头

Go 客户端可以通过包装 http.RoundTripper 统一注入追踪请求头：先用 Request.Clone 建立独立请求副本，只修改副本的 Header，再调用底层 RoundTrip，并原样返回响应和错误。不要直接给传入请求的 Header 赋值，也不要把每次调用的标识保存在共享 Transport 字段中。

设想一个服务同时调用库存与订单接口：调用点只负责把内部追踪标识放进 Context，客户端负责统一发送。这个示例追求的是调用方少写重复代码、并发请求不串号，以及出错后仍能按原来的方式处理；不涉及链路采样、Span 创建或服务端埋点。

Go 官方文档：https://pkg.go.dev/net/http

先约定字段名、覆盖规则和发送对象

本文采用自定义字段 X-Trace-ID，值为内部生成的32位小写十六进制字符串。这只是应用之间约定的关联标识，不是 W3C traceparent，也不会自动成为分布式追踪系统的一条完整链路。

为了让调用行为可预测，示例约定三点：允许的 HTTPS 目的端使用 Context 中的有效标识覆盖该字段；标识缺失或不符合格式时不发送；其他目的端删除这个自定义字段。AllowedHost 按 URL.Host 精确比较，显式端口也是其中一部分。生产中的域名、端口和跨域策略应由应用配置明确给出。

在请求副本上注入，不修改原始 Header

RoundTripper 的职责是完成一次传输。官方接口要求实现能被多个 goroutine 同时调用，且不应修改传入请求，消费和关闭请求体除外。Request.Clone 为 Header 建立副本；它并没有复制 Body 的内容。下面给出可放进独立包的原创实现：

package traceheader

import (
    "context"
    "net/http"
)

type traceKey struct{}

// WithID只接收内部生成的十六进制标识，不直接信任外部请求头。
func WithID(ctx context.Context, id string) context.Context {
    return context.WithValue(ctx, traceKey{}, id)
}

type Transport struct {
    Base http.RoundTripper
    AllowedHost string // 启动时配置，运行期间保持不变，包含必要的端口。
}

func (t *Transport) RoundTrip(req *http.Request) (*http.Response, error) {
    // Clone会复制Header，但Body仍然共享；本装饰器不读取或复制Body。
    out := req.Clone(req.Context())
    if out.Header == nil {
        out.Header = make(http.Header)
    }
    // 自定义字段只发给允许的HTTPS目的端，包括处理重定向后的新请求。
    out.Header.Del("X-Trace-ID")
    if out.URL != nil && out.URL.Scheme == "https" &&
        out.URL.Host == t.AllowedHost {
        id, _ := out.Context().Value(traceKey{}).(string)
        if validID(id) {
            out.Header.Set("X-Trace-ID", id)
        }
    }
    base := t.Base
    if base == nil {
        base = http.DefaultTransport
    }
    // 不把HTTP状态码转换为传输错误，也不额外重试。
    return base.RoundTrip(out)
}

func validID(id string) bool {
    if len(id) != 32 {
        return false
    }
    // 示例自定义协议只允许32位小写十六进制字符。
    for _, c := range id {
        if !(c >= '0' && c = 'a' && c 

这里把传入请求称为“原请求”，out 称为“请求副本”，副本中的映射称为“Header 副本”。Transport 只读配置，Base 指向已有传输实现。初始化阶段完成配置后，不再并发改动 Base、AllowedHost 或 http.DefaultTransport；如果底层自定义实现有可变状态，也必须自行满足并发契约。

每个请求的标识放入 Context

不要为每次请求修改共享 Transport 的 CurrentID 字段。Context 承载单次调用数据，Transport 承载共享策略，两者分开后，调用者只需要为本次业务调用准备标识。本例的 WithID 使用私有键类型，避免与其他包的字符串键冲突。

// 调用片段：按实际模块路径导入traceheader，另导入context、crypto/rand、encoding/hex、net/http、time。
raw := make([]byte, 16)
if _, err := rand.Read(raw); err != nil {
    return err // 未取得内部标识时交给调用方处理。
}
ctx := traceheader.WithID(context.Background(), hex.EncodeToString(raw))
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel() // 让取消信号随请求传到原有Transport。

req, err := http.NewRequestWithContext(ctx, http.MethodGet,
    "https://api.example.org/items", nil)
if err != nil {
    return err
}
client := &http.Client{
    Transport: &traceheader.Transport{AllowedHost: "api.example.org"},
}
resp, err := client.Do(req)
if err != nil {
    return err
}
defer resp.Body.Close() // 响应体由使用响应的调用方关闭。
// 在此处理状态码和业务响应；示例域名不是实际服务。

这段调用片段应放在返回 error 的业务函数内，示例未在本机执行，也没有真实访问示例域名。多处业务调用可以共用一个初始化好的 Client，而不是每次创建一个新的底层 Transport。若项目已有统一超时、代理、TLS 或连接池配置，应将其作为 Base 传入，不要因为加一个请求头而替换掉它们。

错误和响应体继续交给原来的调用方

return base.RoundTrip(out) 保持底层返回值。装饰器不把404、500等 HTTP 状态直接变成 error，不在这里读取或关闭响应 Body，也不把一次传输偷偷变成重试循环。消费响应的业务代码仍负责检查状态码并关闭响应体。

遇到重定向时，http.Client 会负责创建后续请求并再次使用 Transport。本文包装器按每次收到的 URL 判断是否注入，不能把 Client 对某些敏感字段的默认转发规则理解为对所有自定义追踪字段的保护。这里的白名单只管理 X-Trace-ID，不是完整的出站访问控制或其他凭据保护方案。

用替身传输描述预期行为

只检查请求头装饰，不需要向公网发请求。以下测试用函数适配器替代网络传输，检查副本、标识、Context、Body、底层调用次数与错误身份；它是供读者使用的测试代码，不是本文已完成的实测记录。

package traceheader

import (
    "context"
    "errors"
    "net/http"
    "testing"
)

type roundTripFunc func(*http.Request) (*http.Response, error)

// 函数适配器只替代网络传输，不启动HTTP服务器。
func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) {
    return f(r)
}

func TestInjectAndPreserve(t *testing.T) {
    const id = "0123456789abcdef0123456789abcdef"
    req, err := http.NewRequestWithContext(
        WithID(context.Background(), id),
        http.MethodGet, "https://api.example.org/items", nil)
    if err != nil {
        t.Fatal(err)
    }
    req.Header.Set("X-Trace-ID", "old")
    sentinel := errors.New("transport unavailable")
    calls := 0
    rt := &Transport{
        AllowedHost: "api.example.org",
        Base: roundTripFunc(func(out *http.Request) (*http.Response, error) {
            calls++
            if out == req || out.Header.Get("X-Trace-ID") != id {
                t.Fatal("请求副本或标识不符合预期")
            }
            if out.Context() != req.Context() || out.Body != req.Body {
                t.Fatal("上下文或请求体被替换")
            }
            return nil, sentinel
        }),
    }
    _, got := rt.RoundTrip(req)
    if got != sentinel || calls != 1 {
        t.Fatal("错误未原样返回或底层调用次数改变")
    }
    if req.Header.Get("X-Trace-ID") != "old" {
        t.Fatal("原请求头被修改")
    }
}

现有测试中的 Body 是 nil，因此表中的非空 Body 情况仍需另加样例；不要把引用相等检查当成可重复发送的证明。项目还可通过竞态检测检查自己编写的共享依赖，但本文没有执行测试或检测命令。

为什么不直接使用 WithContext 后改 Header？

WithContext 是浅拷贝，不能靠它取得独立 Header；需要显式复制映射或使用 Clone。只复制 Request 结构体也有同样问题。

Set 和 Add 应该选哪个？

本例的字段只允许一个内部标识，因此采用 Set。Add 适合协议明确允许多个值的情况，不应该让多层装饰把追踪字段叠加得不可预测。

已经使用追踪SDK，还要自己加这个字段吗？

不一定。若项目已经有负责传播上下文的 SDK，应以它的传播配置为准，避免自定义字段与标准传播重复或互相覆盖。本例只适合确实需要自定义关联字段的应用。

总结：把标识留在单次请求的 Context，把注入留在 Header 副本，把网络行为留给 Base。对调用方来说，接口体验仍然是一次普通的 Client.Do，而不是多出来一套隐藏的重试和响应处理规则。

相关一手资料：https://pkg.go.dev/net/http#RoundTripper；https://go.dev/src/net/http/request.go；https://go.dev/src/net/http/client.go。