Go / 系统课时
配置 HTTP Client 超时
配置 HTTP Client 超时
调用外部 HTTP 服务时,默认 http.Client 可能因为连接、响应头或响应体迟迟不结束而长期占用 goroutine。本篇会配置可复用 Client 的整体与分阶段超时,并把响应体关闭、大小限制和状态码检查一起做到位。
学习目标
- 区分
http.Client.Timeout与http.Transport各阶段超时的覆盖范围。 - 创建并复用带合理连接池参数的
http.Client。 - 正确读取并关闭响应体,并把非 2xx 状态当作业务失败处理。
把整体超时和阶段超时分开
http.Client.Timeout 是一次请求的总时限,覆盖连接、重定向、读取响应头以及读取响应体。比如设置为 800ms,即使响应头已经收到,只要读取响应体使总耗时超过 800ms,请求仍可能失败。
更细的限制通常放在 http.Transport 中。下面这组参数适合演示和内部服务的短请求,生产值应按真实延迟分布调整:
| 参数 | 示例值 | 限制的阶段 |
|---|---|---|
net.Dialer.Timeout |
200ms |
建立 TCP 连接 |
TLSHandshakeTimeout |
300ms |
TLS 握手 |
ResponseHeaderTimeout |
150ms |
请求写出后等待响应头 |
ExpectContinueTimeout |
100ms |
等待 100 Continue |
http.Client.Timeout |
800ms |
整个请求生命周期 |
IdleConnTimeout 不限制单次请求耗时,它只决定空闲 keep-alive 连接在池里最多保留多久。不要把它当作“请求超时”。

创建可复用 Client 并验证超时
下面程序用 httptest.Server 模拟正常响应、503 失败和慢响应头,因此不依赖外网。Transport 与 Client 都只创建一次;真实服务中也应长期复用,而不是每次请求重新 &http.Client{},否则连接池无法有效复用。
package main
import (
"bytes"
"errors"
"fmt"
"io"
"net"
"net/http"
"net/http/httptest"
"time"
)
func getText(client *http.Client, url string) (string, error) {
resp, err := client.Get(url)
if err != nil {
return "", err
}
defer resp.Body.Close()
const maxBody = 1 << 20 // 1 MiB
body, err := io.ReadAll(io.LimitReader(resp.Body, maxBody+1))
if err != nil {
return "", err
}
if len(body) > maxBody {
return "", fmt.Errorf("response body exceeds %d bytes", maxBody)
}
body = bytes.TrimSpace(body)
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return "", fmt.Errorf("unexpected status=%d body=%q", resp.StatusCode, body)
}
return string(body), nil
}
func main() {
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
switch r.URL.Path {
case "/ok":
fmt.Fprintln(w, "ok")
case "/error":
http.Error(w, "temporarily unavailable", http.StatusServiceUnavailable)
case "/slow-header":
time.Sleep(300 * time.Millisecond)
fmt.Fprintln(w, "late")
default:
http.NotFound(w, r)
}
}))
defer server.Close()
transport := &http.Transport{
DialContext: (&net.Dialer{
Timeout: 200 * time.Millisecond,
}).DialContext,
TLSHandshakeTimeout: 300 * time.Millisecond,
ResponseHeaderTimeout: 150 * time.Millisecond,
ExpectContinueTimeout: 100 * time.Millisecond,
IdleConnTimeout: 30 * time.Second,
MaxIdleConns: 100,
MaxIdleConnsPerHost: 10,
}
defer transport.CloseIdleConnections()
client := &http.Client{
Transport: transport,
Timeout: 800 * time.Millisecond,
}
for _, path := range []string{"/ok", "/error", "/slow-header"} {
body, err := getText(client, server.URL+path)
if err == nil {
fmt.Printf("%s: body=%q\n", path, body)
continue
}
var netErr net.Error
if errors.As(err, &netErr) && netErr.Timeout() {
fmt.Printf("%s: timeout=true\n", path)
continue
}
fmt.Printf("%s: %v\n", path, err)
}
}预期输出
/ok: body="ok"
/error: unexpected status=503 body="temporarily unavailable"
/slow-header: timeout=true慢接口在 300ms 后才写响应头,但 ResponseHeaderTimeout 只有 150ms,因此会先触发阶段超时。若把它改为 500ms,该请求可以继续执行,但仍受 Client.Timeout=800ms 的总时限约束。
读取响应体时同时限制资源占用
成功拿到 resp 后必须保证 resp.Body.Close() 被调用,否则连接可能无法及时回到连接池。示例把 defer resp.Body.Close() 放在确认 err == nil 之后,这是最常见且安全的位置。
对未知来源的响应体不要无上限 io.ReadAll。示例最多读取 1 MiB + 1 字节:多出的 1 字节用于判断响应是否超限;如果业务允许的 JSON 最大只有 64 KiB,可以把 maxBody 改成 64<<10。下载大文件时则不应整块读入内存,而应流式复制并按场景设置更长的总超时或请求级 context。
状态码也必须显式检查。http.Client 不会因为服务端返回 404、429 或 503 自动返回 Go error;这些响应在协议层仍然是成功收到的 HTTP 响应。常见做法是只接受 200 <= status < 300,同时截取有限长度的错误响应体用于日志。
给单次请求设置更短的截止时间
共享 Client 适合给出全局上限,单个调用还可以用 context.WithTimeout 设更短的预算。例如 Client 总超时是 2 秒,而某个鉴权查询只允许 300ms,就让请求 context 先到期;两者谁先到期,谁终止请求。
片段示例:下面代码需放在已经定义 client、url,且当前函数允许 return error 的调用上下文中。
ctx, cancel := context.WithTimeout(context.Background(), 300*time.Millisecond)
defer cancel()
req, err := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)
if err != nil {
return err
}
resp, err := client.Do(req)预期结果:该片段依赖已定义的 client、url 和返回 error 的调用函数;当服务端超过 300ms 仍未完成时,请求会因 context 截止时间先结束,即使共享 Client 的总超时更长。
实际项目先用监控得到 P95/P99 延迟,再为连接、响应头和总请求留出明确预算。这样超时失败发生在哪个阶段是可解释的,也避免默认无限等待把少量慢请求放大成连接和 goroutine 堆积。