Go HTTP 服务端 ReadHeaderTimeout 和 ReadTimeout 怎么选

我在把一个 Go HTTP 服务从“所有请求共用一个读取超时”改成分层配置时，最容易混淆的就是 ReadHeaderTimeout 和 ReadTimeout。实际选择可以先记成一句话：只想限制客户端慢慢发请求头，用 ReadHeaderTimeout；需要给请求头加请求体设一个统一上限，才考虑 ReadTimeout。多数 API 服务更适合前者，上传接口则要结合 handler 自己的读取策略。

先看清两个字段到底计时什么

Go 官方 net/http.Server 的定义把范围分得很清楚：ReadTimeout 是读取整个请求的最长时间，包含请求体；ReadHeaderTimeout 只给请求头留时间，头部读完后，handler 可以决定请求体允许多慢。若前者设置为零，后者会回退使用前者的值。

这意味着把两者都写成同一个数字，并不等于“多一层保护”。请求头阶段最终会取一个有效值，而请求体是否继续受整请求截止时间影响，取决于你是否启用了 ReadTimeout。下面这张时间线是操作示意，不是真实抓包截图。

从 ReadTimeout 迁移时，先保护慢客户端

如果原配置只有 ReadTimeout: 10 * time.Second，它会把大 body、慢网络和慢发请求头放进同一只计时器。迁移时我通常先保留一个较短的头部预算，再把 body 的限制放到具体接口中处理：

srv := &http.Server{
	ReadHeaderTimeout: 5 * time.Second,  // 先限制客户端发送请求头的时间
	IdleTimeout:       60 * time.Second, // 限制 keep-alive 等待下一次请求
	WriteTimeout:      15 * time.Second, // 限制响应写出，按业务响应大小调整
}

// 大文件接口按请求体大小和业务耗时单独设计，不用一个全局 ReadTimeout 误杀上传。

这里不是说 ReadTimeout 永远不能用。内部小型 JSON API、请求体很小且希望“从开始读取到 body 结束必须在总预算内完成”时，它仍然直观。关键是先确认所有接口是否真的共享同一个 body 时限。

按接口类型做选择，不要整站只抄一个数

如果 handler 需要对 body 做更细的控制，可以在读取前基于业务上下文设置截止时间，或者用 http.MaxBytesReader 控制体积。不要把“允许上传更久”简单理解成把全局 ReadTimeout 调到几分钟，因为这也会给慢发请求头留下更长的占用窗口。

四个边界要在回归时实际走一遍

1. 让客户端故意每隔一段时间才发送一个 header 字节，确认超过 ReadHeaderTimeout 后连接会结束。
2. 用小 body 和大 body 分别请求 JSON 接口，观察启用 ReadTimeout 后的超时位置。
3. 模拟慢速上传，确认 handler 的 body 读取策略与全局 deadline 没有冲突。
4. 保持连接不发下一次请求，单独检查 IdleTimeout；再用大响应检查 WriteTimeout。

排查日志时不要只记录“request timeout”。至少把阶段、请求方法、路径和是否已读完 headers 记录下来，否则同一个错误文本很难区分是慢客户端、慢上传还是响应写出超时。

发布前的迁移清单

• 确认 ReadHeaderTimeout 不为零时的实际值，并明确是否依赖 ReadTimeout 回退。
• 按接口记录 body 大小、允许时长和取消策略，上传接口不要盲目沿用 API 的总预算。
• 为 keep-alive 配置单独的 IdleTimeout，不要把它和请求体阶段混为一谈。
• 同时检查 WriteTimeout，否则只收紧读取端仍可能留下响应写出占用。
• 用慢 header、慢 body、空闲连接三类回归请求确认超时日志和客户端错误符合预期。

常见问题

ReadHeaderTimeout 和 ReadTimeout 可以同时设置吗？

可以。前者约束读请求头的阶段，后者继续约束整个请求读取；但要意识到 body 仍会受到 ReadTimeout 的影响。

ReadHeaderTimeout 设置为零是不是没有超时？

不一定。若 ReadTimeout 是正数，ReadHeaderTimeout 会使用它；只有两者都为零或负数时，读取阶段才没有这组超时。

上传接口是不是应该关闭所有超时？

不建议。通常保留头部超时，再按体积、速率和业务上下文设计 body 读取规则，同时保留连接空闲和响应写出保护。

官方参考：Go net/http Server 源码与字段注释、net/http 包文档。