Go Server ReadHeaderTimeout 和 WriteTimeout 怎么区分

这两个字段都写在 http.Server 里，却保护着请求的不同阶段：ReadHeaderTimeout 管客户端把请求头送完的时间，WriteTimeout 管服务端开始处理后把响应写出去的时间。连接复用后的“等下一次请求”则属于 IdleTimeout，不能拿它替代前两者。

最小判断口诀是：请求头迟迟不完整看 ReadHeaderTimeout，响应写不出去看 WriteTimeout，keep-alive 连接长时间等不到下一次请求看 IdleTimeout。配置为零时还要留意它们与 ReadTimeout 的回退关系。

ReadHeaderTimeout 和 WriteTimeout 的边界不在同一侧

可以把一次 HTTP/1.x 请求粗略拆成“请求头到达—请求体被处理—响应写回—连接等待下一请求”四段。三个字段分别落在这条边界的不同位置：

ReadHeaderTimeout 到期时，请求头还没有读完，连接就会被判定为读得太慢。请求头读完后，连接的读期限会重置，Handler 可以再决定如何限制请求体；这正是它比“一把梭”的 ReadTimeout 更适合普通服务端的原因。

为什么同样是超时，重置时机也不同

官方文档对 WriteTimeout 的表述很关键：它限制响应写入，并且在读取一个新请求的请求头时重置。因此在启用 keep-alive 的连接上，下一请求开始时会重新获得一段写回预算；它不是从 TCP 连接建立后永久倒计时。

但这不等于 Handler 内部每个慢操作都有独立的写超时。WriteTimeout 是 Server 层的连接写期限，不能替代数据库查询的 context，也不能精确表达“业务处理最多 2 秒”。如果某个下游调用需要更细的截止时间，应在 Handler 内使用带 deadline 的 context，并处理取消。

ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
defer cancel() // 无论查询成功或失败，都释放定时器资源

result, err := queryBackend(ctx, r.URL.Query().Get("id"))
if err != nil {
    http.Error(w, "backend timeout", http.StatusGatewayTimeout) // 把下游失败转成明确的 HTTP 结果
    return
}
fmt.Fprintln(w, result) // 业务结果准备好后，再交给 Server 写回

这里的 context 只描述一次业务调用的截止时间，不能据此推断 WriteTimeout 的具体剩余时间。两者要分别设置、分别记录。

按请求阶段组合 Server 超时配置

普通 JSON 接口可以先把三个阶段拆开配置。下面是一组示意值，重点是字段职责，不是所有服务都应照抄 10 秒或 30 秒：

srv := &http.Server{
    Addr:              ":8080", // 监听地址，示例服务使用 8080 端口
    Handler:           mux,
    ReadHeaderTimeout: 5 * time.Second,  // 给请求头一个短而明确的窗口
    WriteTimeout:      15 * time.Second, // 覆盖普通 Handler 的响应写回
    IdleTimeout:       60 * time.Second, // keep-alive 空闲连接等待下一请求
    MaxHeaderBytes:    1 

如果服务接收大文件或慢速请求体，不要为了“让上传成功”盲目把 ReadHeaderTimeout 调到几分钟。它只保护请求头；请求体应使用大小限制、业务 context 或流式处理策略。若把 ReadHeaderTimeout 留为零，官方语义是使用 ReadTimeout；IdleTimeout 也会在零值时回退到 ReadTimeout，所以审配置时要一起看。

看到超时日志后怎么反查字段

排查时先问“哪一段没有完成”，不要看到 timeout 就直接把所有值加大：

• 请求刚连上，Header 长时间不完整：优先检查 ReadHeaderTimeout，同时看反向代理是否也有请求头超时。
• Handler 已经拿到请求，但响应迟迟写不出：检查下游调用、响应体大小和 WriteTimeout；先区分业务处理慢还是客户端读取慢。
• 请求完成后，复用连接空闲一段时间被关闭：检查 IdleTimeout 与客户端连接复用策略，这通常不是当前请求失败。

记录请求阶段、连接协议、Handler 是否开始、响应头是否写出和下游调用耗时，证据会比单条“i/o timeout”更有用。尤其要记住：调大 WriteTimeout 只能增加写回容忍度，不能修复数据库慢查询；调大 IdleTimeout 也不能让慢上传变快。

常见问题

ReadHeaderTimeout 和 ReadTimeout 能同时设置吗？

可以。设置了 ReadHeaderTimeout 后，请求头阶段使用它；请求体是否受整体 ReadTimeout 影响，还要结合 Server 的读取语义和业务处理方式判断。普通服务更适合先明确请求头保护，再为上传路径单独设计。

WriteTimeout 为零是不是更安全？

不是。零或负值表示不限制写超时，慢客户端或异常下游可能让连接长期占用资源。应结合响应大小、业务最长耗时和客户端网络条件设定，而不是把零值当成默认安全选项。

IdleTimeout 会限制 Handler 执行时间吗？

不会。它针对启用 keep-alive 时等待下一请求的空闲连接；当前请求正在 Handler 中处理时，应看业务 context、请求读取策略和响应写回策略。