Go http.Request.Clone 复制请求后怎样避免共享 Header 修改

在 Go 里，想保留一个基础请求，再为不同下游追加 Header，应优先使用 Request.Clone。它会为副本重新克隆 Header，所以修改 copyReq.Header 不会回写 baseReq.Header；WithContext 只做浅复制，不能承担 Header 隔离。需要特别记住的是，Body 仍然是浅复制，不能因为 Header 已隔离就把同一个请求体安全地并发重放。

官方文档：https://pkg.go.dev/net/http#Request.Clone

Request.Clone 真正隔离了哪些请求字段

Clone 先复制 Request 结构体，再把需要独立所有权的字段重新复制。对这个问题最关键的区别是：Header 是一个 map，map 本身及其字符串切片都会被克隆；URL、Trailer、Form、PostForm 和 MultipartForm 也会进入各自的复制路径。TransferEncoding、路由匹配值等切片或 map 也有独立副本。

用 Clone 修改 Header 的最小写法

典型场景是一个基础请求要发往多个下游：公共 Header 保持不变，每个副本再加入追踪号或路由标记。把修改动作放在 Clone 返回值上即可，原请求仍可继续复用。

package main

import (
    "context"
    "fmt"
    "net/http"
)

func main() {
    baseReq, err := http.NewRequest(http.MethodGet, "https://api.example.test/data", nil)
    if err != nil {
        // 构造请求失败时立即停止，避免继续使用半初始化对象。
        panic(err)
    }
    baseReq.Header.Set("X-Trace-ID", "base-001")

    copyReq := baseReq.Clone(context.Background())
    // 只给当前副本追加下游信息，不触碰基础请求的 Header。
    copyReq.Header.Set("X-Trace-ID", "worker-001")
    copyReq.Header.Set("X-Route", "inventory")

    fmt.Println(baseReq.Header.Get("X-Trace-ID")) // base-001
    fmt.Println(copyReq.Header.Get("X-Trace-ID")) // worker-001
}

这里的核心不是“重新创建了一个 HTTP 请求”，而是 Clone 保留了原请求的字段值，同时把需要隔离的引用型字段换成了新的容器。副本上的 Set、Add 和 Del 只作用于自己的 Header。

为什么 WithContext 不能解决共享 Header

WithContext 的定义是返回一个带新 context 的浅副本，它不会重新克隆 Header。下面的写法看起来也创建了新请求，但两个请求仍指向同一个 Header map：

shallowReq := baseReq.WithContext(context.Background())
// 这里修改的是共享 Header，可能回写 baseReq。
shallowReq.Header.Set("X-Route", "billing")

fmt.Println(baseReq.Header.Get("X-Route")) // billing

// 需要隔离字段时，改用 Clone，而不是仅替换 context。
clonedReq := baseReq.Clone(context.Background())
clonedReq.Header.Set("X-Route", "shipping")

因此可以把两个 API 分工记成一句话：只想换 context 且接受浅复制时使用 WithContext；要为请求副本修改 Header、URL 或表单时使用 Clone。如果 Header 可能为 nil，先初始化副本的 Header 再写入；由 http.NewRequest 创建的常规客户端请求通常已经有可用 Header。

Body 的浅复制是重试时的边界

官方文档对 Clone 留了一个重要例外：Body 只做浅复制。也就是说，Clone 解决的是请求元数据的所有权问题，不会把底层 reader 的当前位置、缓冲区或网络流复制成两份。一个副本读完 Body 后，另一个副本可能只能读到剩余内容。

需要重试 POST、上传或签名请求时，优先检查原请求是否提供 GetBody。如果它为 nil，就不要把 Clone 当成重放保证；应保留原始字节、重新创建 reader，再用 NewRequestWithContext 或新的请求对象构造下一次发送。这样做也更容易明确谁负责关闭每次发送对应的 Body。

if req.GetBody == nil {
    // 任意 io.Reader 不一定能回到起点，重试前要改用可重复生成的原始数据。
    return fmt.Errorf("request body is not replayable")
}

retryBody, err := req.GetBody()
if err != nil {
    // GetBody 失败时不能复用旧 Body，直接把错误交给上层重试策略。
    return err
}
retryReq := req.Clone(ctx)
retryReq.Body = retryBody
// Header 仍由 Clone 隔离，Body 则由 GetBody 提供新的读取对象。

采用清单：什么时候该用 Clone

• 同一组公共 Header 要派生多个下游请求，并且每个请求会追加不同字段时，使用 Clone。
• 只替换 context、不会修改 Header 或其他引用型字段时，WithContext 可以满足需求。
• 请求包含 Body 时，把“Header 是否隔离”和“Body 是否可重放”当成两项独立检查。
• 并发发送派生请求时，不要继续修改基础请求的 Header；先完成基础模板，再分别 Clone。

相关问题

Clone 会复制请求体吗？

不会。Request.Clone 对 Body 是浅复制，需要重试时通过 GetBody 或原始字节重新构造读取对象。

修改 Clone 后的 Header 会影响原请求吗？

正常情况下不会。Clone 会调用 Header 的复制逻辑，副本的 map 和值切片与原请求分开。

WithContext 和 Clone 应该怎么选？

只换 context 可以用 WithContext；只要还要修改 Header、URL、Trailer 或表单，就用 Clone，并另外检查 Body 边界。