Go http.NewRequestWithContext 和 Request.WithContext 怎么选：取消责任与请求复用边界

给外部服务加超时的时候，很多 Go 代码只是把 req = req.WithContext(ctx) 填进去，却没有想清楚这个请求是不是还要复用、请求体能不能再次读取。更稳妥的判断是：第一次创建请求就已经知道上下文，用 http.NewRequestWithContext；已有请求只需要换一份取消范围，用 Request.WithContext；需要连请求头、URL 和其他可变字段一起隔离时，改用 Request.Clone。

NewRequestWithContext 负责“创建时绑定”，WithContext 返回只替换 context 的浅拷贝，Clone 才会深拷贝大部分请求字段；三者都不会替你复制 Body。

两个 API 的差别先看清

http.NewRequestWithContext(ctx, method, url, body) 在创建新的 Request 时写入上下文，并返回错误。传入的 ctx 不能为 nil；它控制客户端获取连接、发送请求、等待响应头以及读取响应体的整个过程。

req.WithContext(ctx) 返回当前请求的浅拷贝，只替换上下文。它适合已有请求的取消范围需要变化、但不准备改动请求结构的场景。两个 API 都要求非 nil context，错误边界要在调用处处理。

创建时绑定：让取消信号进入 Client.Do

下面的控制流故意把超时放在请求构造前。Client.Do 收到的就是带 deadline 的请求，服务器迟迟不返回时，调用方可以从 ctx.Err() 判断是超时还是主动取消。

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()

req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://api.example.com/profile", nil)
if err != nil {
    return err
}
resp, err := http.DefaultClient.Do(req)
if err != nil {
    return fmt.Errorf("request profile: %w", err)
}
defer resp.Body.Close()

这条链路里真正重要的节点是 NewRequestWithContext、Client.Do 和 ctx.Err。不要只捕获一个字符串错误就结束判断：网络库可能返回包装后的 url.Error，应结合上下文状态决定是否属于本次 deadline。

已有请求换上下文：WithContext 的浅拷贝边界

如果请求已经由公共方法创建，或者基础请求上已经放好了固定 Header，可以按请求尝试单独套 deadline：

baseReq, err := http.NewRequest(http.MethodGet, "https://api.example.com/profile", nil)
if err != nil {
    return err
}
baseReq.Header.Set("Accept", "application/json")

ctx, cancel := context.WithTimeout(context.Background(), time.Second)
defer cancel()
req := baseReq.WithContext(ctx)
// req 与 baseReq 的 Header 指向同一个 map，别在并发请求中交叉修改它们。

WithContext 不会复制 Header map，也不会重绕 Body。因此它适合“只换取消信号”的请求，而不适合把一个可变请求当成并发模板。若每个下游还要改 Authorization、查询参数或 URL，就应该先做更完整的复制。

需要独立修改请求时，用 Clone 而不是硬套 WithContext

Clone 返回带新 context 的深拷贝，适合在同一基础请求上派生多个版本：

first := baseReq.Clone(ctx)
first.Header.Set("X-Route", "primary")

second := baseReq.Clone(ctx)
second.Header.Set("X-Route", "backup")

这里两份 Header 可以分别修改，但 Clone 对 Body 仍然只是浅处理。POST 请求如果要重发，应该保存原始字节并用新的 bytes.Reader 重新构造请求，不能假设 Clone 会把已读过的流恢复。

一个容易误判的边界：请求取消不等于业务回滚

客户端 context 取消，只能中断客户端等待或传输过程；服务端是否已经完成写入，要看服务端自己的事务和幂等设计。对付款、发货这类操作，超时后不要直接重复提交，先用业务流水号查询结果。

另外，成功拿到响应后仍要关闭 resp.Body。context 的生命周期结束并不能替代资源清理，连接复用也依赖调用方正确消费和关闭响应体。

相关问题

WithContext 会复制请求头吗？

不会。它是浅拷贝，Header map 仍可能共享；只换 context 时问题不大，并发改 Header 时应使用 Clone 或重新构造。

什么时候必须重新创建 Body？

需要重试或给两个请求发送同一 POST 内容时，必须从可重复读取的原始数据重新创建 reader，不能复用已经消费的 Body。

请求超时后可以马上重试吗？

查询类请求通常可以在退避后重试；有副作用的请求先用幂等键或业务查询确认服务端状态，再决定是否继续。

最后的选择口诀

新请求、新上下文，用 NewRequestWithContext；已有请求只换取消范围，用 WithContext；要分别改 Header、URL 或其他请求字段，用 Clone，但 Body 仍按流的生命周期单独设计。把这三个边界分开，代码里的超时就不再只是“加了一行 context”。