Go net/http 怎样给客户端请求设置总超时

Go 中给客户端请求设置总超时，直接使用 http.Client.Timeout。例如把它设为 5*time.Second，一次请求从建立连接到读取响应体都不能超过这段时间；超时后 Do 会返回错误。这个字段适合做服务调用的总预算，避免某个慢接口长期占住 goroutine。

如果你的目标是“整个 HTTP 客户端请求最多运行多久”，优先配置可复用的 http.Client{Timeout: ...}；如果只想让某一条请求更早结束，再给这条请求附加 context.WithTimeout。两者同时使用时，较早触发的截止时间会先结束请求。

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

项目目标：做一个有总预算的 HTTP 客户端

下面用一个小型命令行程序串起完整链路：创建客户端、构造请求、发送请求、读取响应、判断错误并关闭响应体。示例只讨论客户端侧的总超时，不把服务端的 ReadTimeout、WriteTimeout 混进来。

先弄清 http.Client.Timeout 覆盖什么

http.Client.Timeout 是一次客户端请求的总时间限制，覆盖连接建立、重定向、发送请求、等待响应头以及读取响应体。值为零表示不设置这个总超时。

这意味着它和“只等待响应头”的参数不是一回事：如果服务很快返回响应头，却持续很慢地输出响应体，Client.Timeout 仍然会继续计时。下面这张结构图把总预算放在整个生命周期外侧，便于先确定配置位置。

创建并复用带总超时的客户端

把客户端当作长期复用的依赖，而不是每次调用都重新创建。http.Client 及其传输层会维护连接状态，重复创建会损失连接复用，也让超时策略分散在业务代码里。

package main

import (
	"fmt"
	"io"
	"log"
	"net/http"
	"time"
)

func main() {
	// 这个客户端给每次请求设置五秒总预算，覆盖响应体读取。
	client := &http.Client{Timeout: 5 * time.Second}

	// 使用显式请求对象，后续可以继续添加请求头或请求级 context。
	req, err := http.NewRequest(http.MethodGet, "https://example.com", nil)
	if err != nil {
		log.Fatalf("创建请求失败: %v", err)
	}

	start := time.Now()
	resp, err := client.Do(req)
	if err != nil {
		log.Fatalf("请求失败，耗时=%s: %v", time.Since(start).Round(time.Millisecond), err)
	}
	// 无论后面的读取是否成功，都要释放响应体和连接资源。
	defer resp.Body.Close()

	body, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatalf("读取响应体失败: %v", err)
	}

	fmt.Printf("status=%s bytes=%d elapsed=%s\n", resp.Status, len(body), time.Since(start).Round(time.Millisecond))
}

示例里最关键的一行是 Timeout: 5 * time.Second。请求对象本身没有单独的总时长字段，预算属于客户端；因此同一个客户端发出的调用可以共享默认预算。

识别超时，不要把所有错误都当成超时

网络失败可能来自 DNS、连接被拒绝、TLS、服务端返回异常或读取中断。业务层通常要区分“应该重试的超时”和“需要换地址或修配置的错误”。可以用 errors.As 找到 net.Error，再调用它的 Timeout 方法。

package main

import (
	"errors"
	"fmt"
	"net"
	"net/http"
	"time"
)

func fetch(client *http.Client, url string) error {
	// 请求复用调用方传入的客户端，保持统一的总超时策略。
	resp, err := client.Get(url)
	if err != nil {
		var netErr net.Error
		// url.Error 通常会包住底层错误，errors.As 可以继续向内查找。
		if errors.As(err, &netErr) && netErr.Timeout() {
			return fmt.Errorf("请求超时: %w", err)
		}
		return fmt.Errorf("请求失败: %w", err)
	}
	// 成功拿到响应后仍需关闭 Body，避免连接无法回收到连接池。
	defer resp.Body.Close()
	return nil
}

func main() {
	// 五秒是示例预算，生产环境应按接口 SLA 和响应体大小调整。
	client := &http.Client{Timeout: 5 * time.Second}
	if err := fetch(client, "https://example.com"); err != nil {
		fmt.Println(err)
	}
	_ = time.Second // 保留 time 包示例导入时的可读性
}

如果只需要展示错误信息，也可以检查返回错误是否实现了 Timeout() bool。不要用错误字符串包含某个英文单词作为唯一判断依据，因为包装层和底层传输实现都可能改变文本。

单次请求更短：使用 context.WithTimeout

客户端总预算适合统一默认值，但某个关键接口可能只允许两秒。此时给请求附加一个更短的 context，不必复制一个新客户端。

ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel() // 及时释放计时器，避免请求结束后继续占用资源

req, err := http.NewRequestWithContext(ctx, http.MethodGet, "https://example.com", nil)
if err != nil {
	return err
}

resp, err := client.Do(req)
if err != nil {
	return err
}
defer resp.Body.Close() // 读取完成后归还连接

http.Client.Timeout 表达“这个客户端调用通常最多多久”，context.WithTimeout 表达“这一条请求由调用方最多允许多久”。两者叠加时，实际请求会在先到的截止时间取消；因此要避免误把较短的请求级预算当成客户端配置失效。

什么时候要配置 Transport 的分阶段超时

http.Transport 还提供更细的参数，例如 TLSHandshakeTimeout、ResponseHeaderTimeout 和 ExpectContinueTimeout。这些参数适合定位某个阶段的 SLA，而不是替换客户端总超时。

如果只配置 ResponseHeaderTimeout，服务端仍可能在响应头到达后慢慢发送很大的响应体；如果业务要求的是端到端上限，仍然需要客户端总超时或请求级 context。

集成到项目时的验收清单

1. 客户端是否集中创建并复用，而不是在每个函数里临时构造？
2. 总预算是否覆盖了业务真正关心的响应体读取阶段？
3. 错误处理是否能区分 net.Error.Timeout() 与普通网络错误？
4. 每个成功响应是否都执行了 defer resp.Body.Close()？
5. 需要更短预算的调用是否通过请求级 context 表达，而不是复制一套客户端配置？
6. 如果使用 Transport 分阶段参数，是否同时保留了端到端总预算？

这样配置后，Go 客户端有一条清晰的时间边界：默认由 http.Client.Timeout 保护整次调用，特殊请求由 context 收紧预算，Transport 参数只负责需要单独观测的阶段。

常见问题

http.Client.Timeout 不设置会怎样？

它的零值表示没有客户端级总超时。若调用链也没有请求级 context，慢连接或慢响应体可能长期占用资源。

设置了 ResponseHeaderTimeout 还需要 Client.Timeout 吗？

如果目标是限制整次调用，仍然需要。ResponseHeaderTimeout 只等待响应头，不覆盖响应体读取。

为什么超时错误看起来像 url.Error？

高层客户端会包装底层错误。用 errors.As 继续查找 net.Error，再调用 Timeout()，比直接比较错误文本更稳妥。