Go http.NewRequestWithContext 怎样创建可取消的 HTTP 请求

给 Go 出站 HTTP 请求加取消能力，关键不是把 context.Context 塞进一个全局变量，而是在创建请求时直接使用 http.NewRequestWithContext。这样，context 会覆盖获取连接、发送请求、读取响应头和读取响应体的整个请求生命周期。

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

用一个非 nil 的派生 context 创建请求，把 cancel 放进明确的资源边界；调用 Client.Do 后先处理错误，再关闭成功响应的 Body。请求被取消时，执行错误应结合 ctx.Err() 判断，而不是解析错误字符串。

下面按一个“上游请求超时就停止等待”的场景展开。重点是请求上下文的适用力和边界，不把它与客户端全局配置混成同一层。

先看 NewRequestWithContext 绑定了什么

http.NewRequestWithContext(ctx, method, url, body) 返回一个适合交给 Client.Do 或 Transport.RoundTrip 的出站请求。官方文档明确说明，绑定的 context 控制获取连接、发送请求、读取响应头和读取响应体，因而它不是只在请求排队阶段有效的开关。

ctx 不能是 nil。没有合适的父 context 时，应先明确使用 context.Background() 或 context.TODO()，不要把 nil 当成“无限等待”的约定。URL 的解析和方法、请求体等参数仍由构造函数返回的 error 负责报告。

用 WithTimeout 构造可取消请求

最常见的模式是从调用方传入的父 context 派生一个带超时的子 context。创建请求、执行请求和关闭响应体都放在同一个函数里，调用方既能控制等待上限，也不会把取消责任遗留给更远的调用层。

package main

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

func fetch(ctx context.Context, client *http.Client, endpoint string) error {
    // 派生请求级超时；离开函数时释放定时器和子 context 引用。
    requestCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()

    // 用非 nil context 创建出站请求，构造阶段的 URL 错误单独返回。
    req, err := http.NewRequestWithContext(requestCtx, http.MethodGet, endpoint, nil)
    if err != nil {
        return fmt.Errorf("创建请求失败: %w", err)
    }

    // Do 返回成功响应时，调用方负责关闭 Body，避免资源长期占用。
    resp, err := client.Do(req)
    if err != nil {
        // 取消或超时优先看 context 状态，不解析错误字符串。
        if errors.Is(requestCtx.Err(), context.DeadlineExceeded) {
            return fmt.Errorf("请求超时: %w", requestCtx.Err())
        }
        if errors.Is(requestCtx.Err(), context.Canceled) {
            return fmt.Errorf("请求已取消: %w", requestCtx.Err())
        }
        return fmt.Errorf("发送请求失败: %w", err)
    }
    defer resp.Body.Close()

    // 非 2xx 仍可能有响应对象，状态判断要放在 err == nil 之后。
    if resp.StatusCode = http.StatusMultipleChoices {
        return fmt.Errorf("服务返回 HTTP %d", resp.StatusCode)
    }
    return nil
}

func main() {
    // 真实服务中把 Background 换成上游传入的请求 context。
    if err := fetch(context.Background(), http.DefaultClient, "https://example.com/health"); err != nil {
        fmt.Println(err)
    }
}

这里的 defer cancel() 即使请求提前成功也应该保留，它负责释放派生 context 关联的定时器。resp.Body.Close() 则只在拿到成功响应对象后执行；如果 Do 返回 error，通常没有可供调用方关闭的响应体。

区分构造错误与执行错误

把错误分成两层，排查会清楚很多：构造阶段关注 nil context、非法 URL 和请求体参数；执行阶段关注取消、超时、连接失败和服务返回的状态码。HTTP 非 2xx 本身并不等于 Client.Do 返回 error，所以不能只写“err == nil 就代表业务成功”。

如果调用方主动取消父 context，子 context 也会进入取消状态。判断时可使用 errors.Is(ctx.Err(), context.Canceled)；若是超时则检查 context.DeadlineExceeded。这些是稳定的错误值，适合程序分支和指标分类。

func newRequest(ctx context.Context, method, endpoint string) (*http.Request, error) {
    // 让调用方决定生命周期；本函数只负责构造，不偷偷创建全局超时。
    if ctx == nil {
        return nil, errors.New("请求 context 不能为 nil")
    }

    req, err := http.NewRequestWithContext(ctx, method, endpoint, nil)
    if err != nil {
        // 保留原始错误，调用方可以继续用 errors.Is 或 errors.As 判断。
        return nil, fmt.Errorf("构造 %s 请求失败: %w", method, err)
    }
    return req, nil
}

明确 WithContext 与测试请求的边界

Request.WithContext 会返回当前请求的浅复制版本，并替换 context；它适合已有请求需要换生命周期的情况，但新建出站请求时，直接调用 NewRequestWithContext 更容易让依赖关系一眼可见。若要深复制请求并更换 context，应考虑 Request.Clone，因为请求体字段仍有自己的复制语义。

另一个容易混淆的点是测试：NewRequestWithContext 面向交给客户端或传输层的出站请求；要构造传给服务端 Handler 的测试请求，应使用 httptest.NewRequest。两者都带 context，但它们表达的请求方向不同。

• 生命周期责任：派生 context 的函数负责调用 cancel，成功响应的调用方负责关闭 Body。
• 判断责任：取消和超时用 context 错误值判断，状态码单独判断，避免混在一个字符串分支里。
• 边界责任：请求级 context 解决单次调用的生命周期，不替代客户端全局超时、连接池策略或服务端业务超时。

相关问题

context.WithTimeout 和 Client.Timeout 要同时设置吗？不必为了形式同时设置。前者更适合表达单次调用的上下文关系，后者是客户端级策略；是否同时使用要看系统是否需要更外层的总保护。

请求超时后还要关闭 Body 吗？如果 Client.Do 已经返回了非 nil 响应，仍按正常路径关闭；如果只拿到 error，就不要假设有可用的响应体。

能用错误字符串判断“请求已取消”吗？不建议。优先检查 ctx.Err() 并使用 errors.Is，这样不会依赖传输实现的文案。