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 连接在池里最多保留多久。不要把它当作“请求超时”。

HTTP Client 整体超时与分阶段超时的覆盖关系

创建可复用 Client 并验证超时

下面程序用 httptest.Server 模拟正常响应、503 失败和慢响应头,因此不依赖外网。Transport 与 Client 都只创建一次;真实服务中也应长期复用,而不是每次请求重新 &http.Client{},否则连接池无法有效复用。

go
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)
	}
}

预期输出

text
/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 的调用上下文中。

go
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 堆积。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

配置 HTTP Client 超时

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通