net/http Request.Clone 与 WithContext 应该怎么选

我在给 Go 的 HTTP 中间件加超时和请求头时，最容易犹豫的地方就是：已经有一个 *http.Request，到底该调用 WithContext，还是调用 Clone？可以先记住一个判断：只想换取消、超时或 trace 上下文，用 WithContext；还要让 URL、Header、表单等请求元数据与原请求隔离，就用 Clone。官方文档入口是 https://pkg.go.dev/net/http。

两者都会返回一个新的 Request 指针，但复制深度不同：WithContext 是浅复制后替换 context，Clone 会深复制大部分请求元数据；两者对 Body 都只做浅复制。

• 只换上下文：优先 req.WithContext(ctx)。
• 需要改 Header、URL、表单且不影响原请求：优先 req.Clone(ctx)。
• 需要重新读取请求体：不要只依赖 Clone，必须准备独立的 Body 或可重复读取方案。

我先把两个方法放到同一场景里

假设一个入站请求经过鉴权中间件后，要把剩余处理交给下游 handler。鉴权只需要把截止时间传下去，并不修改原请求的 URL、Header 或表单，这时 WithContext 的意图最清楚：保留原请求字段，只替换它关联的 context。

// WithContext 适合只替换取消、超时或链路上下文。
func withDeadline(next http.Handler, timeout time.Duration) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        ctx, cancel := context.WithTimeout(r.Context(), timeout)
        defer cancel() // 释放计时器，避免请求结束后仍保留资源

        next.ServeHTTP(w, r.WithContext(ctx))
    })
}

这个方法返回的是 r 的浅复制：普通字段值会被复制，但字段指向的对象不因此自动变成独立对象。WithContext 要求传入非 nil context，传入 nil 会 panic，所以中间件应当从 context.Background() 或已有请求上下文派生。

WithContext 和 Clone 的复制边界

Clone 同样会把 context 换成传入值，但还会复制 URL、Header、Trailer、TransferEncoding、Form、PostForm 和 MultipartForm 等请求元数据。换句话说，如果你准备在派生请求上追加一个只给下游看的 Header，Clone 更符合“修改副本”的语义。

// Clone 适合派生一个要独立修改元数据的请求副本。
func addInternalHeader(r *http.Request, ctx context.Context) *http.Request {
    cloned := r.Clone(ctx)
    cloned.Header.Set("X-Internal-Route", "profile") // 修改副本，不把意图写回原 Header
    if cloned.URL != nil {
        cloned.URL.RawQuery = "view=compact" // Clone 已复制 URL，适合调整副本的查询参数
    }
    return cloned
}

需要特别注意的是 Body。官方实现明确说明 Clone 只对 Body 做浅复制；如果原请求和派生请求都读取同一个流，它们仍然共享读取位置。Clone 解决的是请求元数据隔离，不是请求体重放、缓存或并发读取问题。

按请求生命周期做选择

我现在会先问“下一个处理者要不要改请求元数据”，再决定方法，而不是把 Clone 当成更安全的 WithContext。

在 handler 链路里，如果只是把截止时间向下传递，WithContext 的副本关系足够；在需要把入站请求映射成另一个业务请求时，Clone 可以减少手工复制字段的遗漏，但仍要单独处理 Body。对于全新的下游请求，直接使用 http.NewRequestWithContext 往往比复制入站请求更容易审查。

常见误区与最后的选择口诀

第一，不要把“返回新指针”理解成“所有字段都深复制”；Body 是最容易被忽略的共享资源。第二，不要给 WithContext 传 nil；它不是清空上下文的方法。第三，若只是新建出站请求，不必为了复用字段而复制一个入站 Request，明确写出新请求的 method、URL 和 Body 更稳妥。

可以用一句话收尾：只换 context 用 WithContext，要隔离请求元数据用 Clone，要重新定义一次出站调用用 NewRequestWithContext；请求体是否可重读，另算一笔。

相关问题

Clone 会复制 Request.Body 吗？

不会。Clone 只对 Body 做浅复制，派生请求仍可能共享同一个读取流；需要重放时应准备独立的 Body 或合适的 GetBody。

WithContext 能修改 Header 吗？

它不负责隔离 Header。若后续要改 Header 且不希望影响原请求，应使用 Clone 后再修改副本。

context.Context 可以传 nil 吗？

不可以。WithContext 和 Clone 都要求非 nil context，调用前应从已有上下文或明确的根上下文派生。