Go http.Request.Clone 怎样复制请求头而不共享映射

在 Go 的 HTTP 中间件、重试逻辑或请求转发里，经常需要复制一个请求，再给副本增加追踪头、租户头或重试标记。推荐使用 Request.Clone(ctx)：它会创建新的请求副本，Header 不再与原请求共用同一张映射；但 Body 仍然只是浅拷贝，不能把它误解成“所有字段都能独立重放”。

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

如果目标是“换 context 并隔离 Header”，用 Clone；如果只想换 context 且不修改共享字段，WithContext 才是更轻的选择。

Request.Clone 解决的是哪一种复制问题

Request.Clone 的参数是一个非 nil 的 context，返回带新 context 的请求副本。官方文档把它定义为深拷贝，同时明确说明 Body 只做浅拷贝。对本文关注的 Header 来说，副本中的键和值切片可以独立修改，因此给副本设置请求头不会回写原请求。

这个语义适合“同一份请求信息派生多个变体”的场景，例如给重试请求追加 X-Retry，给转发请求替换 Authorization，或者在测试中为副本注入独立的跟踪标识。

最小写法：复制后只改副本 Header

package main

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

func main() {
	// 原请求保留父级追踪标识，副本使用新的标识。
	original, err := http.NewRequest("GET", "https://api.example.com/items", nil)
	if err != nil {
		// 构造请求失败时立即退出，避免继续使用空请求。
		panic(err)
	}
	original.Header.Set("X-Trace", "parent")

	// Clone 会更换 context，并为可复制字段建立独立副本。
	cloned := original.Clone(context.Background())
	cloned.Header.Set("X-Trace", "retry-1")
	cloned.Header.Set("X-Request-Mode", "retry")

	// 修改副本后，原请求仍保留 parent。
	fmt.Println(original.Header.Get("X-Trace"))
	fmt.Println(cloned.Header.Get("X-Trace"))
}

示例的关键不是输出字符串，而是修改路径：先 Clone，再只操作 cloned.Header。需要删除某个字段时使用 cloned.Header.Del("X-Request-Mode")；需要保留重复值时使用 Add，不要把多值 Header 简化成单个字符串。

Clone 和 WithContext 不要混用语义

WithContext 返回的是浅拷贝，主要用途是替换 context。它不会为 Header 建立本文所需的独立隔离层。如果后续代码会修改 Header，直接使用 WithContext 容易让调用方误判副本关系。

如果代码使用结构体字面量手工复制请求，至少要显式写出 Header: r.Header.Clone()。不要只复制 Header map 的指针，也不要用一次 Set 操作就推断所有多值字段都已隔离。

中间件里的推荐边界

中间件需要给请求增加内部标记时，可以把“派生”和“发送”分开：先根据当前 context Clone，再在副本上设置 Header，最后把副本交给下游。这样原请求仍可用于日志、审计或另一条分支。

func withRetryHeader(r *http.Request, retry int) *http.Request {
	// 使用原请求的 context，保持取消链不被意外切断。
	cloned := r.Clone(r.Context())
	// 只在副本上写入内部标记，避免污染上游请求。
	cloned.Header.Set("X-Retry", fmt.Sprintf("%d", retry))
	return cloned
}

这段函数只处理 Header 和 context，不负责重新创建 Body。若请求体来自不可回退的流，重试前必须由调用方准备可重复读取的数据源，并在每次发送时创建新的 Body；这正是 Clone 没有替你完成的部分。

常见问题

为什么 Clone 后改 Header，原请求没有变化？

因为 Clone 会复制请求的可复制字段，Header 不再指向原请求的同一份映射。这个结论只覆盖 Header 等可复制字段，不代表 Body 也能被安全重复读取。

只想换 context，是否一定要 Clone？

不一定。后续不会修改 Header、URL 等共享字段时，WithContext 足够；一旦要派生请求并修改字段，就应使用 Clone，或者手动对相关字段做明确复制。

小结

记住三点：要隔离请求字段优先用 Request.Clone；只换 context 可以用 WithContext；Body 是浅拷贝，重试请求必须单独设计可重读的数据源。这样既能安全添加请求头，也不会把 context 变更误认为完整请求复制。