Go http.Client 为什么只设置连接超时仍会卡在响应体

只设置 net.Dialer.Timeout，只限制新连接的建立，不限制连接建好后的响应体读取。http.Client.Do 成功返回，通常只是取得了响应头与可读取的 Body；后续 io.ReadAll 或解码操作仍可能等待服务器继续发送数据。

对需要完整读完的小型接口响应，可设置 http.Client.Timeout，或让带截止时间的请求 context 一直存活到正文读取结束。还要检查读取阶段的错误，不能只检查 Do 的 err。若请求本来就是持续的事件流，则需要另行设计流的存活与取消策略。

Go 官方地址：https://go.dev/

先确定卡在 Do 还是读取 Body

假设一个报表接口先返回 200 和响应头，正文只传了一部分就停住。应用记录“拿到响应”后进入 io.ReadAll，进度却不再变化。这种现象与“TCP 一直连不上”属于不同位置，调短 Dialer.Timeout 并不能处理后面的等待。

排查时分别记录请求开始、Do 返回、读取结束和关闭资源这几个位置。这里应关注位置及耗时，而不是仅凭错误字符串猜测原因。响应头里的成功状态也不能证明正文已完整接收，更不能替代业务解码检查。

把时间预算分配给正确范围

已有连接被复用时，新建连接的拨号逻辑可能根本不会执行，因此把 Dialer 的数值当成每个请求的总耗时尤其容易误判。IdleConnTimeout 管的是闲置连接，不是正在读取的响应体，也不能拿来替代读取限制。

建立可复用客户端，为有限响应设置总预算

下面示例面向最大 1 MiB 的有限响应。连接预算为 2 秒、响应头预算为 4 秒，客户端总预算为 10 秒，每次 fetch 再设 6 秒的业务截止时间。数值仅为演示，应按真实接口预算调整，不把它们直接相加成允许的总时长。

package main

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

func newClient() (*http.Client, *http.Transport) {
    // 复制默认传输配置，不修改全局共享的 DefaultTransport。
    tr := http.DefaultTransport.(*http.Transport).Clone()
    tr.DialContext = (&net.Dialer{
        Timeout: 2 * time.Second,
        KeepAlive: 30 * time.Second,
    }).DialContext
    tr.TLSHandshakeTimeout = 3 * time.Second
    tr.ResponseHeaderTimeout = 4 * time.Second
    return &http.Client{
        Transport: tr,
        Timeout: 10 * time.Second, // 覆盖本次请求及响应体读取的总预算。
    }, tr
}

func fetch(ctx context.Context, client *http.Client, rawURL string) ([]byte, error) {
    // 请求级预算必须持续到正文读取结束，不能在 Do 返回后立即取消。
    ctx, cancel := context.WithTimeout(ctx, 6*time.Second)
    defer cancel()

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, rawURL, nil)
    if err != nil {
        return nil, fmt.Errorf("构造请求: %w", err)
    }
    resp, err := client.Do(req)
    if err != nil {
        return nil, fmt.Errorf("等待响应: %w", err)
    }
    defer resp.Body.Close()

    if resp.StatusCode = 300 {
        // 不无限读取错误响应；关闭正文后可能无法复用该连接。
        return nil, fmt.Errorf("HTTP状态不符合预期: %s", resp.Status)
    }

    const maxBytes = 1  maxBytes {
        return nil, fmt.Errorf("响应体超过 %d 字节", maxBytes)
    }
    return data, nil
}

func main() {
    if len(os.Args) != 2 {
        fmt.Fprintln(os.Stderr, "请提供自己有权访问的有限响应 URL")
        os.Exit(2)
    }
    client, tr := newClient()
    // 示例程序退出前关闭闲置连接；服务中应长期复用客户端。
    defer tr.CloseIdleConnections()

    data, err := fetch(context.Background(), client, os.Args[1])
    if err != nil {
        if errors.Is(err, context.DeadlineExceeded) || os.IsTimeout(err) {
            fmt.Fprintln(os.Stderr, "请求超时:", err)
        } else {
            fmt.Fprintln(os.Stderr, "请求失败:", err)
        }
        return
    }
    fmt.Printf("完成读取：%d 字节\n", len(data))
}

把它保存为独立程序的 main.go，传入自己有权访问的接口 URL 即可自行尝试。本文没有执行网络示例，也没有虚构测试日志。正常情况应打印完整读取的字节数；正文阻塞超过有效预算时，应在“读取响应体”阶段返回错误；数据过大则得到单独的大小错误。

这里同时提供时间和字节数上限，是因为两者处理不同问题。LimitReader 限制读取量，却不能阻止服务器在很少数据后停止发送；超时也不能代替可接受响应大小的定义。读取出错时，代码丢弃部分数据，避免业务将截断内容当成完整成功结果。

读取结束前不要提前取消 context

示例把创建请求、Do 和读取 Body 放在同一个 fetch 中，cancel 在函数结束时执行。如果封装函数只返回 resp.Body，却用 defer cancel 在返回时取消请求，调用方拿到 Body 就可能遇到取消错误。

确实要返回流时，应明确谁拥有取消函数、谁关闭 Body，以及流可以存活多久。不要为了避免提前取消而永远不 cancel；也不要把读正文放进 goroutine 后只让外层超时返回，却留下后台读取继续占资源。标准客户端已经支持通过请求取消来中断相关网络操作，应优先使用这条路径。

按错误阶段决定下一步动作

代码使用 %w 保留原始错误链，再用 errors.Is 与超时判断辅助分类。不要依赖某个完整英文报错字符串长期不变。context 更短时可能先结束请求，客户端总预算更短时也可能先触发；它们是同时存在的约束，不是依次排队。

记录等待响应与读取响应体这两类错误，才能判断问题主要位于响应头之前还是正文中途。增加重试之前，还要确认请求是否允许重复执行，以及上一次是否已被服务端处理；超时只说明调用方未及时拿到完整结果，不等于服务端什么都没做。

Body 应由使用方及时关闭。为了连接复用而无上限排空一个已经卡住的响应体，会重新引入等待问题。示例在状态异常或大小超限时选择直接关闭，并接受连接可能无法复用的代价；客户端本身应长期复用，而非每次创建一套传输连接池。

长连接和慢速下载需要另一套预算

Client.Timeout 是总时间，不会因为每次收到一小块数据就自动重新计时。对持续事件流，固定十秒可能会定期切断本来健康的连接；对大文件，完整下载预算也应与文件大小和业务期限匹配。

如果业务需要“连续多久没有数据才取消”，应在流消费层明确记录进度、心跳与取消条件，并考虑协议和连接复用方式。不要直接给共享底层连接设置读截止时间后假定它只影响当前请求，尤其不能忽略多路复用协议。本文的完整读入内存方案适合有限响应，不适合作为无限流消费模板。

ResponseHeaderTimeout 设置了，为什么正文还会慢？

它的范围不包括读取响应体。要限制完整响应时间，应使用总预算或请求截止时间。

Do 没有报错，为什么 ReadAll 仍然超时？

Do 与 Body 读取是两个阶段。计时可以延续到 Do 返回之后，调用方必须处理读取错误。

默认 Client 能直接用于必须按时完成的请求吗？

默认 Client 的 Timeout 为零。如果调用方没有提供其他有效截止时间，就没有客户端总预算。应按请求类型明确配置，而不是把默认值当成业务超时策略。

配置语义参见 http.Client 文档、http.Transport 文档及 net.Dialer 文档。