Go net/http Request.Clone 怎样避免复用 Header 导致请求互相污染

在 Go 里复用一个 HTTP 请求模板时，最容易被忽略的是 Header 本质上是映射。直接复制 http.Request 指针，或用只做浅拷贝的方式换上下文，后续对一个请求调用 Header.Set，就可能把另一个请求的请求头一起改掉。

官方地址：https://pkg.go.dev/net/http#Request.Clone

处理请求元数据时，优先使用 Request.Clone(ctx)：它会复制请求的主要元数据，新的请求使用传入的非空上下文；但官方文档明确说明，Body 只做浅拷贝。因此，解决 Header 污染与重放请求体是两个问题。

为什么 Request.Clone 能解决 Header 互相污染

典型场景是一个公共模板带有固定鉴权头，每次发送前再补充 trace ID。正确做法是保留模板不变，用新的上下文克隆出请求，再只修改克隆对象的 Header。

package main

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

func buildRequest(template *http.Request, traceID string) *http.Request {
	// Clone 会复制请求元数据；传入请求级 context，避免复用旧请求的取消边界。
	cloned := template.Clone(context.Background())
	// 只改当前副本的 Header，模板和其它副本不会共享这张映射。
	cloned.Header.Set("X-Trace-ID", traceID)
	return cloned
}

func main() {
	// 模板只保存不会随单次调用变化的默认头。
	template, _ := http.NewRequest(http.MethodGet, "https://api.example.test/items", nil)
	template.Header.Set("Authorization", "Bearer demo")

	first := buildRequest(template, "trace-a")
	second := buildRequest(template, "trace-b")
	fmt.Println(template.Header.Get("X-Trace-ID")) // 空：模板未被污染
	fmt.Println(first.Header.Get("X-Trace-ID"))   // trace-a
	fmt.Println(second.Header.Get("X-Trace-ID"))  // trace-b
}

这里的关键不是“复制后就能随便改”，而是复制发生在每次请求的边界内。若模板本身的 Header 之后还会被修改，就连模板也应视为只读对象，避免和构建请求的 goroutine 并发写入。

Clone、WithContext 和 Header.Clone 有什么区别

Request.Clone 的目标是得到一个带新 context 的深拷贝请求；Request.WithContext 只返回浅拷贝，适合明确知道其它字段不会被修改的情况。官方的 Header.Clone 则只复制 Header 映射，适合你已经有一个请求副本、只想隔离请求头的场景。

因此，若请求只有 GET 元数据，Clone 通常是更清楚的入口；若只是在已有副本上重建 Header，也可以显式写 req.Header = req.Header.Clone()，把隔离意图留在代码里。

Body 为什么不能按 Header 的方式理解

请求体是读取器，不是普通的值对象。Request.Clone 不会把它的内容复制成另一份可独立读取的字节流。两个请求如果共享同一个 Body，其中一个读取了数据，另一个看到的就可能是剩余内容；并发读取还会引入竞态和顺序问题。

func newJSONRequests(ctx context.Context, payload []byte, urls []string) ([]*http.Request, error) {
	requests := make([]*http.Request, 0, len(urls))
	for _, endpoint := range urls {
		// 每个请求都从同一份只读字节数据重建 Body，不能复用已经读过的 io.Reader。
		req, err := http.NewRequestWithContext(ctx, http.MethodPost, endpoint, bytes.NewReader(payload))
		if err != nil {
			return nil, fmt.Errorf("创建请求失败: %w", err)
		}
		// 设置当前请求自己的 Header，避免后续并发修改公共模板。
		req.Header.Set("Content-Type", "application/json")
		requests = append(requests, req)
	}
	return requests, nil
}

上面的示例用 bytes.NewReader 为每个请求建立新的读取位置。若必须从一个已有请求派生多个带 Body 的请求，应保存原始字节、文件偏移或可重新创建读取器的工厂，而不是把 Body 当作已被 Clone 的独立副本。

并发复用请求模板时的防污染清单

1. 把模板请求当成只读配置，创建后不要在并发发送阶段调用 Header.Set、URL 修改或替换 Body。
2. 每次发送先用 Request.Clone 派生请求，并传入本次调用的 context。
3. 单独复制 Header 时使用 Header.Clone，不要只复制 Header 指针。
4. 带请求体时从原始数据重新创建读取器；不要假设 Clone 会重置读取位置。
5. 不要把包含敏感鉴权头的模板暴露给不受信任的调用方，动态 Header 应在边界内写入。

一句话总结：Request.Clone 解决的是请求元数据的隔离和 context 替换，不能替你复制 Body。Header 污染通常来自共享映射，Body 重复发送则来自共享读取位置；把这两类状态分开处理，代码才不会在并发或重试时出现偶发串请求。

相关问题

Request.Clone 的 context 可以传 nil 吗？

不可以。官方文档要求传入非空 context；需要默认上下文时显式使用 context.Background()，请求级操作则优先传入调用方的 context。

只想隔离 Header，必须 Clone 整个 Request 吗？

不一定。已有请求对象不会被其它 goroutine 使用时，可以单独执行 Header.Clone；如果还要切换 context 或复制 URL、表单等元数据，直接使用 Request.Clone 更不容易遗漏字段。