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

我在给多个请求复用一组默认请求头时，遇到过一个很隐蔽的串改：给“副本”增加一个 Header，原请求的 Header 也跟着变了。原因是 http.Header 的底层形态是 map[string][]string，直接赋值只复制了 map 句柄，手写一层复制也可能继续共享值切片。

如果目标是得到可以独立修改的请求头，直接使用 cloned := original.Clone()。它会复制每个键对应的值切片；如果原 Header 是 nil，返回值仍是 nil。需要注意，Values 返回的切片不是副本。

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

先定位共享修改的根因

旧代码常见的写法是 copied := original。这不是深复制，两个变量仍指向同一个 map。即使改成逐键复制，如果直接把 []string 放进新 map，值切片仍然共享底层数组。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    original := http.Header{}
    original.Set("X-Trace", "base")

    // 直接赋值只复制 map 头部，两个变量仍然指向同一份请求头。
    shared := original
    shared.Set("X-Trace", "changed")

    // 原 Header 也会看到 changed，说明这里没有形成隔离副本。
    fmt.Println(original.Get("X-Trace"))
}

这类问题通常出现在“默认头 + 单次请求头”的组合代码里：调用方以为自己只改了临时变量，实际却污染了后续请求。排查时先找出赋值点，再确认是否同时复制了每个值切片。

用 Header.Clone 创建隔离副本

Header.Clone 从 Go 1.13 开始提供。官方实现会遍历每个键，重新安排值切片的存储，因此副本后续通过 Set、Add 或直接按键赋值时，不会把同一个值切片改回原 Header。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    base := http.Header{}
    base.Set("X-Trace", "base")
    base.Add("Accept", "application/json")

    // Clone 会同时复制键和值切片，适合生成一次请求的可变副本。
    perRequest := base.Clone()
    perRequest.Set("X-Trace", "request-42")
    perRequest.Add("Accept", "text/plain")

    // 原 Header 保持原值，副本拥有自己的多值列表。
    fmt.Println("base:", base.Get("X-Trace"), base.Values("Accept"))
    fmt.Println("request:", perRequest.Get("X-Trace"), perRequest.Values("Accept"))
}

这里的迁移重点不是把所有 Header 都 Clone 一遍，而是把“即将被修改的共享默认值”在边界处 Clone。只读场景可以继续复用同一个 Header，但一旦不同请求要追加或覆盖字段，就应先创建副本。

处理 nil 与多值请求头

迁移时最容易漏掉两个边界。第一，nilHeader.Clone() 返回 nil，不会凭空创建可写 map；如果后续要写入，先显式初始化。第二，一个键可能有多个值，Get 只取第一个值，Values 才能看到全部值。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    var empty http.Header
    cloned := empty.Clone()

    // nil Header 的 Clone 结果仍为 nil；写入前需要初始化 map。
    if cloned == nil {
        cloned = make(http.Header)
    }
    cloned.Add("Accept", "application/json")
    cloned.Add("Accept", "text/plain")

    // Get 只取首个值，Values 返回全部值；返回的切片本身不是副本。
    fmt.Println("first:", cloned.Get("Accept"))
    fmt.Println("all:", cloned.Values("Accept"))
}

如果只是读取多个值，不要把 Values 返回的切片当成新的隔离容器。需要改变值集合时，优先对 Header 使用 Set、Add 或 Del；如果业务确实要保存一份值列表，再自行复制返回的切片。

版本迁移与回归检查

迁移后可以按这份清单回归：

• 默认 Header 和单次请求 Header 是否在修改后保持不同值。
• 多值字段是否仍按预期保留顺序，读取时是否误用了 Get。
• nil Header 的路径是否在写入前初始化。
• 项目最低 Go 版本是否已经包含 Go 1.13；如果更低，先确认升级策略，不要把新 API 静默带入旧构建环境。

相关问题：

Header.Clone 会复制请求体吗？不会，它只处理 Header；请求体重放属于 Request 和 GetBody 的另一个问题。

为什么 Clone 后原 Header 仍可能变化？先检查是否又把副本重新赋回原 Header，或是否修改了 Clone 返回的 Values 切片之外的共享业务数据。

什么时候不需要 Clone？当 Header 只读、生命周期明确且不会被并发请求分别修改时，可以复用；一旦存在请求级 Add、Set 或 Del，就在修改前 Clone。