Go的http.Client必须显式配置三阶段超时：DialContext.Timeout控制连接建立，TLSHandshakeTimeout控制TLS握手，ResponseHeaderTimeout控制响应头读取；流式读取还需为resp.Body.Read()单独设context超时。
Go 的 http.Client 默认不设超时，直接用容易卡死或拖垮服务。必须显式配置超时，且要分清连接、读、写三个阶段——漏掉任何一个都可能出问题。
为什么只设 Timeout 不够
Go 1.3+ 起，http.Client.Timeout 确实会同时作用于连接、请求头读取和响应体读取，但它无法覆盖「流式响应中单次 Read() 阻塞」的场景（比如大文件下载中途卡住）。更关键的是：它不能单独控制连接建立时间，而 DNS 解析慢或目标服务器 SYN 无响应时，就靠 net.Dialer.Timeout 拉回来。
-
Client.Timeout是“整个请求生命周期”的兜底，但不精确 - 真正可控、推荐的方式是用
Transport+ 自定义DialContext - HTTP/2 下还涉及
IdleConnTimeout和KeepAlive，但日常调用一般不用动
正确设置三阶段超时的完整写法
下面这段代码把连接、读、写全部独立控制，兼容 HTTP/1.1 和 HTTP/2，也适配代理、TLS 等常见场景：
client := &http.Client{
Transport: &http.Transport{
DialContext: (&net.Dialer{
Timeout: 5 * time.Second,
KeepAlive: 30 * time.Second,
}).DialContext,
TLSHandshakeTimeout: 5 * time.Second,
ResponseHeaderTimeout: 10 * time.Second,
ExpectContinueTimeout: 1 * time.Second,
},
}-
DialContext.Timeout：DNS 查询 + TCP 连接建立总耗时上限 -
TLSHandshakeTimeout：仅 HTTPS，TLS 握手超时（HTTP/1.1 必设，HTTP/2 可选） -
ResponseHeaderTimeout：从发出请求到收到响应头（status line + headers）的时间 -
ExpectContinueTimeout：客户端发了Expect: 100-continue后等待服务端许可的等待时间（少见，但设个 1s 防卡）
流式响应（如 io.Copy）怎么防卡死
如果用 resp.Body 做长连接、SSE 或大文件下载，ResponseHeaderTimeout 不管用——因为 header 已收完，后续 Read() 可能无限挂起。这时得用带超时的 context 包裹 Read() 操作：
立即学习“go语言免费学习笔记（深入）”；
ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second) defer cancel()// 注意：不是给 client.Do() 用这个 ctx（那是控制整个请求），而是给 Body.Read() // 实际使用时建议封装成带超时的 io.Reader bodyReader := &timeoutReader{ Reader: resp.Body, ctx: ctx, }
io.Copy(dst, bodyReader)
其中 timeoutReader 需自己实现 Read(p []byte)，每次调用前检查 ctx.Err()；或者直接用 io.LimitReader + time.AfterFunc 组合，但注意别忽略 cancel() 导致 goroutine 泄漏。
常见错误现象和对应修复
遇到这些表现，基本就是超时没配对：
- 程序偶尔卡在
client.Do()几分钟才返回 → 没设DialContext.Timeout或Client.Timeout - HTTPS 请求在内网稳定、外网超时 → 忘了
TLSHandshakeTimeout，尤其用了自签名证书或弱密码套件 - 接口返回 200 但 body 读不完、日志停在
io.Copy→ 缺少对resp.Body.Read()的单次读超时控制 - 并发高时大量
net/http: request canceled (Client.Timeout exceeded while awaiting headers)→ResponseHeaderTimeout太小，或后端响应慢，需协同排查
超时值不是越小越好：设太短会导致正常慢请求被误杀；也不是越大越稳：设太大会让故障扩散。建议先从 5s / 10s / 30s（连/读header/读body）起步，再根据监控的 P95/P99 延迟调整。
