Go 超时处理完全指南
Go 超时处理全场景：context.WithTimeout 一脉贯穿 HTTP 客户端、数据库查询、Web 服务端，select+timer 手写模式、resty 重试、常见错误与测试方法。让慢依赖不再拖垮整个系统。
本文依据官方文档整理，未执行运行验证或性能基准。代码片段展示局部用法，业务函数、数据和环境需按项目补齐；版本与配置以所引文档为准。
直接回答：Go 超时体系的核心是 context 包——context.WithTimeout/WithDeadline 创建带截止时间的上下文，沿调用链传递，HTTP 客户端及支持取消的数据库驱动可以使用它。HTTP 客户端另需配置 Transport 层细粒度超时；服务端用 http.TimeoutHandler 或中间件兜底。
超时的基本模式
Go 的并发原语组合出超时范式：
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
result, err := slowOperation(ctx) // 2 秒后 ctx 自动取消
纪律三条：cancel 必须 defer 调用（防 context 泄漏）；超时只是"不再等"，goroutine 内的操作要能响应取消；超时值沿调用链只能缩短不能放宽。
HTTP 客户端：分层超时
client := &http.Client{
Timeout: 10 * time.Second, // 整个请求的总时限
Transport: &http.Transport{
DialContext: (&net.Dialer{Timeout: 3 * time.Second}).DialContext, // 建连
TLSHandshakeTimeout: 3 * time.Second,
ResponseHeaderTimeout: 5 * time.Second, // 等响应头
IdleConnTimeout: 90 * time.Second,
},
}
Client.Timeout 已包含建连、重定向和读取响应体的总预算，不会因响应头慢就无限等待。Transport 的细分超时可更早终止某个阶段；IdleConnTimeout 管空闲连接，不是请求超时。复用 Client/Transport，并及时读取或关闭响应体；也可 clone http.DefaultTransport 保留默认代理与协议配置。
数据库查询
ctx, cancel := context.WithTimeout(ctx, 3*time.Second)
defer cancel()
row := db.QueryRowContext(ctx, "SELECT ...")
Context 方法可以传递请求取消和截止时间，能否及时取消取决于驱动；旧方法仍可能受驱动或数据库侧超时控制。QueryRowContext 的查询错误需通过 Scan 获取。慢查询要有数据库侧的 statement_timeout 双保险。
Web 服务端
http.TimeoutHandler 超时后返回 503，并取消传给 handler 的上下文，但不会强杀 handler goroutine；它不支持 Flusher/Hijacker，不适合直接包流式响应或 WebSocket。http.Server 的 ReadHeaderTimeout/ReadTimeout/WriteTimeout/IdleTimeout 防慢速攻击与连接泄漏。中间件里从 request.Context() 派生子超时传给下游调用。
resty 与重试
go-resty 这类封装库把超时+重试+退避打包：SetTimeout + SetRetryCount + SetRetryWaitTime。注意重试放大问题——超时紧+重试多的组合在下游故障时会制造流量雪崩，重试应有总预算、退避与抖动；仅重试幂等操作，或使用经服务端支持的幂等键，避免重复扣款。按 resty 主版本核对 API。
常见错误
- 超时设了但下游操作不认 context（白设）
- goroutine 泄漏：超时返回了，后台 goroutine 还在跑且永不退出
- 超时值拍脑袋：应该按依赖的 P99 延迟加余量设定
常见问题（FAQ）
Q：超时时间怎么定？
A：看依赖的延迟分布：为下游调用记录耗时、超时类型与重试次数，再结合业务截止时间、网络余量和重试预算设定，没有通用 P99 倍数。下游有效截止时间不应超过剩余的上游预算。
Q：context 取消后 goroutine 一定会停吗？
A：不一定。取消只是发信号，goroutine 里的代码要主动检查 ctx.Done() 或用支持 context 的库——纯计算循环要手动插检查点。
Q：测试超时逻辑有什么好办法？
A：Go 1.24 的 testing/synctest 需 GOEXPERIMENT=synctest；Go 1.25 起使用稳定 API。它推进可控并发环境中的虚拟时间，不能替代真实网络超时集成测试。
官方参考
资料核对日期：2026-09-29。
