Go net/http Request.Clone 的上下文复制与请求体边界

在 Go 客户端中，一个请求经常要带着新的超时、取消信号或少量请求头继续发送。此时最容易误解的是：Request.Clone 虽然被文档描述为深复制，但它对 Body 只做浅复制。也就是说，复制后的请求可以安全地改自己的 URL、Header 和 context，却不能因此获得一份独立的可读请求体。

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

Request.Clone(ctx) 的正确理解是“复制大部分请求字段，并把 context 换成非空的 ctx；Body 仍然共享同一个 io.ReadCloser”。需要重新读取 body 时，应依靠 GetBody 或重新构造请求体。

一、先分清 Clone 和 WithContext

这两个方法都能替换请求的 context，但复制范围不同。WithContext 只创建 Request 结构体的浅副本，适合只需要换 context、并且调用方不会修改共享字段的场景；Clone 会进一步复制 URL、Header、Trailer、表单和值切片等字段，适合要基于原请求派生一个可独立调整的请求。

package main

import (
    "context"
    "net/http"
)

func deriveRequest(src *http.Request) (*http.Request, *http.Request) {
    ctx, cancel := context.WithCancel(context.Background())
    // 这里把 cancel 的生命周期交给上层调用方管理；示例只展示复制边界。
    _ = cancel

    shallow := src.WithContext(ctx)
    // Clone 要求 ctx 非空，并会复制更多请求字段。
    deep := src.Clone(ctx)
    return shallow, deep
}

两种方法都要求传入非空 context；传入 nil 会触发 panic。实际选择时，不要把“用了 WithContext”理解为所有请求字段都已经隔离，尤其要注意 URL、Header 这类引用型字段的后续修改。

二、Request.Clone 到底复制了哪些字段

当前标准库实现先复制 Request 的基础字段，再把 ctx、URL、Header、Trailer、TransferEncoding、Form、PostForm、MultipartForm 以及 ServeMux 路径匹配相关数据分别复制。对调用方最重要的结果是：复制请求后修改 clone.Header 或 clone.URL，通常不会直接改动原请求对应的字段。

package main

import (
    "context"
    "net/http"
)

func addTraceHeader(src *http.Request, traceID string) *http.Request {
    // 使用 Clone 后只改派生请求的 Header，避免把追踪信息写回原请求。
    clone := src.Clone(context.Background())
    clone.Header.Set("X-Trace-ID", traceID)
    return clone
}

这里的“独立”只针对 Clone 明确复制的字段。它不意味着 Request 中所有指针、接口或底层资源都会递归复制；调用方仍应逐项确认自己要修改的字段是否属于 Clone 的复制范围。

三、Body 为什么仍然是浅复制

Body 的类型是 io.ReadCloser，它代表一个带生命周期的读取资源，而不是一块可以随意复制的普通值。Clone 会让新请求保留同一个 Body 引用，因此原请求或克隆请求一旦读取它，另一个请求看到的读取位置也会受到影响；关闭其中一个 Body，也可能影响另一个请求继续读取。

package main

import (
    "bytes"
    "context"
    "io"
    "net/http"
)

func cloneWithBodyBoundary() (*http.Request, *http.Request, error) {
    body := bytes.NewBufferString(`{"name":"demo"}`)
    src, err := http.NewRequestWithContext(context.Background(), http.MethodPost, "https://example.test/items", body)
    if err != nil {
        return nil, nil, err
    }
    // Clone 不会把 Body 变成第二个独立的 ReadCloser。
    clone := src.Clone(context.Background())
    // 这里只读取一次，避免示例把共享 body 当成可重复读取资源。
    _, err = io.ReadAll(clone.Body)
    return src, clone, err
}

代码中的 src 和 clone 都保留了同一个请求体边界。若业务需要发送两个独立请求，应该在复制前保存原始字节，或者为每个请求分别创建一个新的 Reader，而不是直接把 Clone 当作 body 重放器。

四、GetBody 解决的是“重新取得”，不是共享 Body

GetBody 是一个可选函数，用来返回新的 Body 副本。标准库在一些可重放的客户端请求中会自动设置它，例如请求体来自 *bytes.Buffer、*bytes.Reader 或 *strings.Reader 时，NewRequest 能记录长度并准备重新取得 body 的函数。

package main

import (
    "context"
    "io"
    "net/http"
    "strings"
)

func newReplayableRequest() (*http.Request, io.ReadCloser, error) {
    req, err := http.NewRequestWithContext(
        context.Background(),
        http.MethodPost,
        "https://example.test/items",
        strings.NewReader(`{"name":"demo"}`),
    )
    if err != nil {
        return nil, nil, err
    }
    if req.GetBody == nil {
        // Body 可读不等于能够重新创建；没有 GetBody 就不要假设可重放。
        return req, nil, io.ErrUnexpectedEOF
    }
    replay, err := req.GetBody()
    // 新副本必须单独关闭，不能把它当成原请求 Body 的别名。
    if err != nil {
        return req, nil, err
    }
    return req, replay, nil
}

因此，Body 和 GetBody 的职责要分开：前者是当前请求实际消费的资源，后者是需要时才调用的“创建另一个读取资源”的入口。自定义流式 Reader 通常不会天然拥有 GetBody，这时应由业务自己保存可重建的数据或明确放弃重放。

五、复制请求时的推荐写法

一个稳妥的派生函数通常只做三件事：先用 Clone 替换 context，再修改 Clone 明确复制的字段，最后在需要重放 body 时检查 GetBody。这样既保留了原请求的基础信息，也把请求体生命周期单独表达出来。

package main

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

func deriveForAttempt(src *http.Request, ctx context.Context) (*http.Request, error) {
    if ctx == nil {
        // 与 net/http 的约定保持一致：派生请求不能接收 nil context。
        return nil, fmt.Errorf("context is nil")
    }
    clone := src.Clone(ctx)
    // Header 已由 Clone 独立复制，可以只修改派生请求。
    clone.Header.Set("X-Attempt", "1")
    if clone.Body != nil && clone.GetBody == nil {
        // 流式 body 没有重新创建入口时，不把它伪装成可重试请求。
        return nil, fmt.Errorf("request body is not replayable: %w", io.ErrClosedPipe)
    }
    return clone, nil
}

这里没有在函数内部偷偷读取或关闭 src.Body。发送动作和资源关闭仍由客户端请求生命周期负责；如果调用方要重试，先通过 GetBody 创建新的 body，再创建对应的请求副本，边界会更清楚。

六、常见误区与结果判断

排查复制请求问题时，先问三个问题：要改的是 context、Header/URL，还是 Body；这个字段是否被 Clone 独立复制；如果需要第二次读取，是否存在可调用的 GetBody。三问都能回答，通常就能避免把“请求副本”和“请求体副本”混成同一个概念。

七、总结

Request.Clone 适合从一个客户端请求派生出带新 context、独立 Header 和 URL 调整空间的请求。它会复制不少请求字段，但刻意不复制 Body 的底层读取资源。需要 body 重放时，应使用或补充 GetBody；没有这个入口，就把请求视为不可自动重试，并重新设计数据保存或 Reader 创建方式。

相关问题

• Request.Clone 和 WithContext 应该如何选择？
• 为什么复制请求后修改 Header 不一定影响原请求？
• 自定义 io.Reader 怎样提供安全的 GetBody？
• 请求重试前为什么不能只判断 Body != nil？