HTTP 超时边界

Go 里把 http.Client.Timeout 设成 5 秒，并不等于“服务器 5 秒内返回响应头”。它更像整条客户端调用的总预算：连接、重定向、发送请求以及读取响应体都可能消耗这段时间；即使 Do 已经返回，继续读取 Response.Body 时计时器仍可能中断读取。Request.Context 表达的是这一次调用的生命周期和取消来源，Transport.ResponseHeaderTimeout 才是只盯响应头的阶段参数。

先把 HTTP 超时拆成四个边界

一次出站请求至少要经过建立连接、发送请求、等待响应头、读取响应体。下面的配置关系足够用于第一轮排查：

如果 Context 截止时间和 Client.Timeout 同时存在，实际结束时间取更早者。一个是请求级信号，一个是客户端兜底预算，它们不是互相替代的两套计时器。

用 Context 把调用者的截止时间传下去

业务函数应接收 ctx，然后使用 http.NewRequestWithContext 创建请求。这样，上游请求结束、用户主动取消或更早的 deadline 到来时，HTTP 传输会收到同一个取消信号。不要在函数内部重新使用 context.Background()，那会切断调用链。

func fetch(ctx context.Context, client *http.Client, endpoint string) ([]byte, error) {
    // 这里给单次调用设置更细的预算，但不会突破上游更早的截止时间。
    ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
    defer cancel() // 释放定时器，避免短请求留下无用资源

    req, err := http.NewRequestWithContext(ctx, http.MethodGet, endpoint, nil)
    if err != nil {
        return nil, err
    }
    resp, err := client.Do(req)
    if err != nil {
        // Timeout 方法适合区分网络超时；ctx.Err 可识别调用者的截止原因。
        var urlErr *url.Error
        if errors.As(err, &urlErr) && urlErr.Timeout() {
            return nil, fmt.Errorf("HTTP 调用超时: %w", err)
        }
        return nil, err
    }
    defer resp.Body.Close() // 无论读取是否成功都关闭响应体
    return io.ReadAll(resp.Body)
}

这段代码的关键不在于把秒数调大，而在于保留父 Context。若上游只剩 500 毫秒，即使这里写了 3 秒，也只能使用剩余的 500 毫秒。读取响应体时同样属于这次请求，不能因为已经拿到状态码就认为超时边界结束。

响应头慢和响应体慢要分开判断

ResponseHeaderTimeout 只在请求已经写完后等待响应头，它不会限制后续响应体读取。如果服务端很快返回响应头，却用流式方式慢慢发送正文，这个参数不会解决问题；此时应检查 Client.Timeout、请求 Context 和响应体读取耗时。

反过来，连接建立慢、TLS 握手慢或重定向过多，也不应该只调大 ResponseHeaderTimeout。先记录阶段，再决定参数：连接前就失败看拨号与总预算；已发出请求但没有响应头看响应头等待；有状态码但 Body.Read 卡住看总预算、服务端流式行为和读取策略。

一份可执行的排查清单

• 为每个请求记录 URL 主机、开始时间、是否拿到响应头、Body.Read 是否完成以及最终错误。
• 统一复用一个配置好的 http.Client，不要每次调用都新建客户端。
• 在错误处理里同时保留 errors.Is(err, context.DeadlineExceeded)、errors.Is(err, context.Canceled) 和 *url.Error 的信息。
• 成功拿到响应后始终关闭 Body；需要复用连接时，按业务决定是否读完正文。

这样判断“HTTP 超时边界”就不会停留在一个模糊的 5 秒参数上：Client.Timeout 负责兜底，Context 负责传播意图，Transport 的阶段参数负责缩小定位范围。

相关问题

Client.Timeout 为零是不是没有任何限制？

它只表示 Client 层不设置总时限；如果请求 Context 或 Transport 的阶段参数设置了限制，仍然可能提前结束。

拿到响应头后还会发生超时吗？

会。Client.Timeout 的计时仍在继续，读取慢响应体时仍可能返回超时错误。

应该只用 Context 还是只用 Client.Timeout？

通常两者都保留：Context 传递调用者边界，Client.Timeout 给未正确传递 Context 的路径提供最后一道总预算。