Go 请求超时为什么无法取消底层连接

我排查 Go HTTP 慢请求时，最容易被一句话带偏：“超时了，为什么底层 TCP 连接还在？”后来把链路拆开才发现，请求是否已经取消、连接是否还在连接池里、服务端的计算是否停止，本来就是三个不同问题。

结论先说清楚：标准库的 net/http 会把 Request.Context 的取消信号交给 Transport。若你使用了 context.WithTimeout 却仍看见连接，优先检查自定义 RoundTripper 是否新建了没有上下文的请求；如果请求已经结束但仍有连接，则再区分 keep-alive 空闲连接和操作系统的关闭收尾状态。

先把请求超时和连接未消失分开

排查时我会先记下三个观察对象，而不是马上调用关闭连接的方法：

context.WithTimeout 只创建一个带截止时间的派生 Context。它能发出取消信号，但取消函数本身不等待所有工作停止；标准 Transport 是否能把信号落实到连接，要看请求是否带着这个 Context 进入传输层。

让 Request.Context 贯穿请求生命周期

最稳妥的起点是用 http.NewRequestWithContext 建请求，把超时绑定到请求对象，而不是只在外面用一个计时器包住 client.Do：

package main

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

func fetch(ctx context.Context, client *http.Client, url string) error {
    // 派生请求级截止时间，函数结束时释放定时器和上下文资源。
    reqCtx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel()

    // 把同一个 Context 放进 Request，Transport 才能看到取消信号。
    req, err := http.NewRequestWithContext(reqCtx, http.MethodGet, url, nil)
    if err != nil {
        return err
    }

    resp, err := client.Do(req)
    if err != nil {
        // url.Error 会保留底层错误，便于区分超时和普通网络失败。
        if errors.Is(err, context.DeadlineExceeded) {
            return fmt.Errorf("请求超过截止时间: %w", err)
        }
        return err
    }
    // Do 成功后必须关闭响应体，避免连接无法回到可复用状态。
    defer resp.Body.Close()
    return nil
}

这里的 cancel 不是“强制拔掉所有网线”的按钮，而是停止这个派生 Context 的信号。标准 http.Client 会把请求上下文用于建立连接、发送请求、读取响应头和读取响应体。

检查自定义 Transport 是否丢掉了 ctx

真正让我踩过坑的是包装传输层：日志、重试或代理代码为了“重新创建请求”，把原来的 Context 丢掉了。一个包装器应该把原 *http.Request 原样传给下一个 RoundTripper：

type traceTransport struct {
    next http.RoundTripper
}

func (t traceTransport) RoundTrip(req *http.Request) (*http.Response, error) {
    // 只读取请求信息做日志，不要用 http.NewRequest 重建一个无 ctx 的请求。
    fmt.Println(req.Method, req.URL.String())
    return t.next.RoundTrip(req)
}

func newClient() *http.Client {
    dialer := &net.Dialer{Timeout: 2 * time.Second}
    transport := &http.Transport{
        // 拨号阶段也必须接收 Request.Context 的取消信号。
        DialContext: func(ctx context.Context, network, addr string) (net.Conn, error) {
            return dialer.DialContext(ctx, network, addr)
        },
    }
    return &http.Client{
        // 这是整个请求的上限，包含连接、重定向和响应体读取。
        Timeout:   8 * time.Second,
        Transport: traceTransport{next: transport},
    }
}

上面的示例需要额外导入 net。关键不在于日志本身，而在于两条链：RoundTrip(req) 要保留原请求，DialContext 要把收到的 ctx 传给真正的拨号器。只要其中一层改用 context.Background()，取消就会在那一层断掉。

另外，不要再把已废弃的 Transport.CancelRequest 当作首选方案。新代码应使用请求 Context；如果是自定义 RoundTripper，则必须实现对请求 Context 的尊重。

理解连接池与服务端的独立边界

请求超时后仍看到连接，通常可以按下面的边界判断：

• 活动请求：标准 Transport 会因请求 Context 结束而停止该请求；错误返回是客户端视角的取消结果。
• 空闲 keep-alive：连接已经不承载当前请求，只是留在连接池里等待复用。需要清理空闲连接时才调用 CloseIdleConnections，它不等于取消活动请求。
• 服务端工作：客户端停止等待不代表服务端业务函数必然立即退出。服务端也要把自己的 r.Context() 传到数据库、下游 HTTP 或耗时计算中。
• 操作系统状态：FIN_WAIT、TIME_WAIT 等是 TCP 收尾状态，不能只凭连接列表判断业务请求是否仍在执行。

如果只是希望长时间运行的客户端不再复用空闲连接，可以在确认没有并发请求后调用 CloseIdleConnections；如果问题是自定义传输层没有响应取消，则应先修复 Context 传播，不能靠清空连接池掩盖根因。

按工作流落地超时和取消

我现在会按这五步处理类似问题：

1. 先给每次请求设置明确的 Context 截止时间，并确保调用 defer cancel()。
2. 再设置 http.Client.Timeout 作为整个客户端请求的总上限，避免只限制连接建立阶段。
3. 检查所有自定义 RoundTripper、重试器、代理和 DialContext，确认没有替换或忽略请求 Context。
4. 把响应体读完并关闭；若只想处理响应头，也要明确取消后续读取的策略。
5. 最后分别查看活动请求、连接池空闲状态和服务端日志，不把它们合并成一个“连接还在”的结论。

这样处理后，超时问题会从“连接怎么还没消失”变成可定位的问题：是请求上下文没有传进去、Transport 没有实现取消、连接只是空闲复用，还是服务端没有自己的取消链。

常见问题

只设置 Client.Timeout，还需要 WithTimeout 吗？

两者可以同时使用。Client.Timeout 是客户端整体上限，请求级 Context 更适合表达业务截止时间；真正生效的是更早到达的那个边界。

调用 cancel 后为什么连接列表还会保留一会儿？

可能是连接池中的空闲 keep-alive，也可能是 TCP 收尾状态。先看请求是否已返回取消错误，再判断是否需要清理空闲连接。

客户端取消后，服务端一定停止了吗？

不一定。服务端必须检查并传播自己的 Request.Context；客户端取消只能让客户端停止等待，不能替代服务端的协作式取消。

把“请求生命周期”和“TCP 连接生命周期”分开后，Go 请求超时无法取消底层连接这个现象就不再神秘：先保证 Context 进入标准 Transport，再分别处理连接池、TCP 收尾和服务端任务。