http.Client 超时后为什么响应体仍可能可读

http.Client.Timeout 限制的不是“等到响应头就结束”，而是一次 HTTP 交换的总时长，其中也包括读取 Response.Body。因此，服务端已经发出响应头、Client.Do 已经返回 resp 后，客户端仍可能从响应体读到一部分已经到达的数据；当总时限真正到点，后续的 Read 才返回超时错误。可读不等于完整，也不等于这次请求成功消费完毕。

官方文档：https://pkg.go.dev/net/http

判断这类问题时要把“拿到响应头”和“读完响应体”拆成两个阶段：Do 负责得到响应对象，Body.Read 负责继续取数据。阶段不同，超时的表现和处理方式也不同。

为什么 Do 返回后计时器还没有结束

Client.Timeout 的语义是覆盖连接建立、重定向和响应体读取的端到端上限。它不是只作用于请求发送前，也不是收到状态码后自动停止。响应头到达时，网络交换仍然可能没有完成，body 里的数据还在后续传输。

所以常见的两种结果并不矛盾：

• 响应头尚未拿到：Do 通常返回 resp == nil 和错误。
• 响应头已经拿到：Do 可能返回非空 resp，读取 body 时先得到部分字节，之后在某次 Read 中得到超时错误。

具体错误包装会随读取阶段和底层传输实现变化，代码不应只用错误字符串判断。更稳妥的做法是同时保存已经读取的字节数，并使用 errors.Is、net.Error 等方式判断是否属于超时。

用分段响应看清部分读取

下面的例子用 httptest 构造一个先写入首段、再延迟写入下一段的服务端。它只用于说明控制流：服务端实现了响应头和首段数据后，客户端可能已经拿到可读的 body；总时限到达后，后续读取会结束并携带错误。

package main

import (
    "errors"
    "fmt"
    "io"
    "net"
    "net/http"
    "net/http/httptest"
    "strings"
    "time"
)

func main() {
    server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 先提交响应头和首段内容，让客户端有机会拿到部分 body。
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        flusher, _ := w.(http.Flusher)
        _, _ = io.WriteString(w, "第一段数据\n")
        if flusher != nil {
            // Flush 只负责尽快把当前缓冲交给传输层，不保证网络已读完。
            flusher.Flush()
        }
        time.Sleep(300 * time.Millisecond)
        // 第二段故意放慢，用来触发客户端的总时限。
        _, _ = io.WriteString(w, "第二段数据\n")
    }))
    defer server.Close()

    client := &http.Client{Timeout: 120 * time.Millisecond} // 总时限也覆盖 body 读取。
    resp, err := client.Get(server.URL)
    if err != nil {
        fmt.Println("Do 阶段失败:", err)
        return
    }
    defer resp.Body.Close() // 无论部分读取还是完整读取，都要释放响应体。

    data, readErr := io.ReadAll(resp.Body)
    fmt.Printf("状态=%s，已读=%q，读取错误=%v\n", resp.Status, strings.TrimSpace(string(data)), readErr)
    if readErr != nil {
        var timeoutErr net.Error
        // 真实项目中应保留部分数据，并把超时当成不完整结果处理。
        if errors.As(readErr, &timeoutErr) && timeoutErr.Timeout() {
            fmt.Println("响应头已到达，但 body 没有在总时限内读完")
        }
    }
}

上面示例中的类型声明还需要导入 net：为保持代码片段聚焦，导入列表已经展示了主要依赖，但实际复制时应把 "net" 加入 import。更直接的写法是先用 errors.Is 判断项目统一的超时哨兵，再结合 net.Error.Timeout() 处理底层包装差异。

这个例子最重要的不是固定能读到多少字节，而是结果的组合：resp 已存在、data 可能非空、readErr 仍可能非空。调用方不能因为拿到了首段内容就把它当作完整文档、完整 JSON 或完整文件。

四种超时控制分别解决什么问题

把所有超时都写成一个 Client.Timeout 很方便，但不适合每一种接口。下面按控制目标比较常用方案。

这几个控制可以组合，但要先写清楚预算。例如普通 JSON 接口可以用请求上下文控制调用链，再用 Client.Timeout 作为最后的总时限；大文件下载则通常要避免一个过短的总时限误杀正常读取，同时保留响应头等待和分块空闲控制。

部分响应应该怎样处理

首先，无论读取是否完整，都要关闭 resp.Body。其次，把“拿到了一些字节”和“业务对象解析成功”分开：JSON、压缩包、图片或文件通常只有在完整读取并通过格式解析后，才能进入成功路径。

func readJSON(client *http.Client, req *http.Request, dst any) error {
    resp, err := client.Do(req)
    if err != nil {
        // 响应头都没拿到时，通常只能记录请求错误。
        return fmt.Errorf("请求失败: %w", err)
    }
    defer resp.Body.Close() // 读取结束后归还或关闭底层连接。

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        // 部分 body 不能当作完整业务结果交给后续逻辑。
        return fmt.Errorf("响应体未读完，已收到 %d 字节: %w", len(body), err)
    }
    if resp.StatusCode = 300 {
        // HTTP 状态与网络读取成功是两件事，必须分别判断。
        return fmt.Errorf("服务返回状态 %s", resp.Status)
    }
    if err := json.Unmarshal(body, dst); err != nil {
        // 只有完整读取后再做业务格式解析，避免误用截断 JSON。
        return fmt.Errorf("响应不是有效 JSON: %w", err)
    }
    return nil
}

这个片段还需要在文件的 import 中加入 encoding/json、fmt 和 io。如果业务确实支持断点续传或增量消费，就不要把部分数据简单丢弃，而应设计明确的偏移、校验和重试协议；对普通 JSON 接口，截断内容通常应该视为失败。

按接口类型选择超时策略

选型时先回答“我要限制什么”，再填写参数，而不是看到超时就把 Client.Timeout 调大。

• 小型 JSON/RPC：用请求上下文表达调用链截止时间，用 Client.Timeout 做总时长兜底；读取错误不能因为 body 非空而忽略。
• 大文件下载：确认是否需要较长总时长，重点考虑响应头等待、每个数据块的空闲时间和断点续传，而不是只给一个很小的 Client.Timeout。
• SSE 或长轮询：总时长和“多久没有新数据”是两个问题，通常要让连接生命周期由上下文控制，再在读取层处理空闲策略。
• 上游服务慢但最终会返回：先区分是迟迟没有响应头，还是响应头已到但 body 产生慢；前者看 ResponseHeaderTimeout，后者看读取预算。

可以用下面的速查表做最后判断：

常见误区

Do 返回 resp 就说明响应完整了吗？

不是。它通常只说明响应头已经可用，body 仍可能需要继续读取；是否完整要看读取是否返回错误以及业务格式是否解析成功。

读到了部分内容还能重试吗？

能不能重试取决于请求是否幂等、服务端是否支持范围请求或游标续传。普通 POST 不应因为读超时就无条件重放，避免重复副作用。

把 Client.Timeout 调大就能解决所有超时吗？

不能。它只能改变整次交换的上限，不能替代响应头等待、分块空闲、上游取消和业务完整性判断。

记住这一条即可：resp != nil 表示响应头阶段可能已经完成，io.ReadAll(resp.Body) 成功才说明读取阶段完成；两者之间出现部分数据和超时错误，是 http.Client 端到端计时语义下的正常边界。