Go RoundTripper 修改原始 Request 的并发边界与安全包装方式

自定义 http.RoundTripper 最容易踩的坑，是为了加一个请求头，直接改传入的 *http.Request。这种写法在单次调用里可能看不出问题，但传输器通常会被多个 goroutine 共享，调用方也可能在响应体关闭前持有请求引用。更稳妥的做法是：把 RoundTripper 限定为一次 HTTP 传输，在副本上修改 Header，再交给底层传输器。

先分清 RoundTripper 的职责和 Request 所有权

官方接口约定要求 RoundTripper 可被多个 goroutine 并发使用；它不应解释 HTTP 状态码，也不应自行处理重定向、认证和 Cookie。接口还明确指出，除消费并关闭请求体外，RoundTrip 不应修改 Request。调用方在响应体关闭前也不应修改或复用同一个请求。

这里有两个容易混淆的对象：Transport 是可共享的执行器，Request 是某次事务的输入。共享执行器没有问题，共享并原地改同一个 Request 才会把请求头、URL 或上下文变成竞争数据。静态关系可以概括为“调用方持有请求，包装器持有底层传输器，RoundTrip 只建立一次传输边界”。

原地改 Header 为什么会变成并发问题

例如下面的思路会把临时字段写回调用方传入的请求：

func (t headerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    // 直接改入参 Header，多个 goroutine 共享 req 时会产生竞态。
    req.Header.Set("X-Trace-ID", t.traceID)
    // 这里仍然把被修改过的原始请求交给底层传输器。
    return t.base.RoundTrip(req)
}

风险不只在 Header.Set 这一行。一个请求可能被日志中间件、重试包装器或测试代码继续读取；而 Header 本身是 map，URL、Body 和上下文也各有自己的生命周期。即便当前调用路径没有数据竞争，原始请求也可能残留上一层包装器写入的内部字段。

用 Clone 包装请求而不是原地改字段

Request.Clone 会复制请求结构和上下文，适合在中间层为单次传输添加 Header。下面的包装器只在副本上写入追踪头，原始请求仍由调用方保留：

type headerTransport struct {
    base    http.RoundTripper
    traceID string
}

func (t headerTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    // 明确拒绝空请求，避免后续 Clone 或底层调用出现难定位的 panic。
    if req == nil {
        return nil, errors.New("nil HTTP request")
    }
    base := t.base
    if base == nil {
        // 使用默认 Transport，但不把全局客户端状态写进包装器。
        base = http.DefaultTransport
    }
    cloned := req.Clone(req.Context())
    if cloned.Header == nil {
        // Clone 后仍保护 Header 为空的自定义请求。
        cloned.Header = make(http.Header)
    }
    cloned.Header.Set("X-Trace-ID", t.traceID)
    // 只把副本交给底层；响应体仍由 Client 调用方负责关闭。
    return base.RoundTrip(cloned)
}

要注意，Clone 解决的是 Request 结构被包装器修改的问题，不等于自动让 Body 可重复读取。需要重试或多次发送时，必须确认 GetBody 或业务层重新构造输入的能力；这已经超出本标题的传输边界。

落地时的检查清单

• 包装器是否只依赖自己的不可变配置，而不是保存上一次请求的可变状态？
• 是否在副本上修改 Header、URL 或上下文，并避免回写入参？
• 是否处理 nil Transport、nil Request 和 nil Header？
• 是否把响应体关闭责任留给 http.Client 的调用方？

相关问题

RoundTripper 能不能修改请求体？

接口允许它消费并关闭 Body，但不要把“可以消费”理解成“可以随意重放”。需要重复发送时，应使用可重建的 Body 或明确的 GetBody。

为什么不直接复制 Header 再改原始 Request？

复制 Header 只能隔离 map；如果同时要调整上下文、URL 或其他请求字段，直接改原始结构仍会留下共享状态。统一 Clone 更容易保持边界。

自定义 RoundTripper 是否必须自己关闭响应体？

它要遵守底层接口的返回约定，但正常的 Client 调用路径由调用方读取并关闭 Response.Body。包装器不要偷偷吞掉这个责任。