HTTP Server 的读超时、写超时和空闲超时分别保护什么

我第一次给 Go 的 HTTP 服务补超时时，最容易犯的错是把三个字段都理解成“一个请求最多活多久”。实际并不是这样：ReadTimeout 约束服务端读取整个请求（包括请求体）的时间，WriteTimeout 约束响应写入的时间，IdleTimeout 只约束启用 Keep-Alive 后等待下一次请求的空闲时间。

换句话说，慢上传主要看读边界，客户端迟迟收不走响应主要看写边界，连接复用后一直不再发请求才轮到空闲超时。它们都是连接层截止时间，不等于 Handler 的业务执行超时，也不能代替数据库、RPC 或外部 API 的每请求超时。

先把三个超时放回各自的连接阶段

官方 net/http.Server 文档对这几个字段的边界写得很明确。完整字段定义可以直接查 https://pkg.go.dev/net/http#Server。我在排查时通常先看请求停在哪一段，再决定该查哪个字段，而不是先把所有超时一起调大。

这里还有一个经常被忽略的字段：ReadHeaderTimeout 只限制读取请求头。官方文档甚至建议多数场景优先考虑它，因为请求头读完后，Handler 可以针对不同接口决定请求体是否允许更慢。对“普通 JSON 接口”和“大文件上传”一刀切使用很短的 ReadTimeout，通常会让后者误伤。

用一份最小 Server 配置建立基线

下面这份程序可以作为普通 API 服务的起点。数值只是实验基线，不是可以直接复制到所有生产环境的标准答案。真正上线时仍要结合请求体大小、响应体大小、反向代理超时和延迟分位数调整。

package main

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

func main() {
    mux := http.NewServeMux()

    mux.HandleFunc("GET /work", func(w http.ResponseWriter, r *http.Request) {
        // 业务超时单独设置，不把 WriteTimeout 当成业务取消信号。
        ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
        defer cancel()

        select {
        case 

运行后先确认正常路径，不要一开始就制造慢连接。这样做的好处是：如果后面的异常实验失败，可以明确是超时边界触发，而不是程序本身没有启动。

# 启动实验服务。
go run .

# 在另一个终端确认正常请求能在业务截止时间内完成。
curl -i http://127.0.0.1:8080/work

正常结果应包含 HTTP/1.1 200 OK 和 work finished。如果前面还有 Nginx、网关或负载均衡器，需要同时记录它们的读写超时；客户端看到的往往是最先到期的那一层。

分别观察读、写与空闲连接的保护边界

ReadTimeout 保护的是读取，不是 Handler 总耗时

ReadTimeout 从连接读取侧限制完整请求，包括请求体。慢速上传、持续不完整的请求体会消耗这一预算。它不会替你判断“这个上传接口允许 30 秒，那个 JSON 接口只允许 2 秒”，所以大多数服务还会设置较短的 ReadHeaderTimeout，再在上传 Handler 中用 http.MaxBytesReader、每请求读取截止时间或反向代理策略控制请求体。

一个实用判断是：如果日志里 Handler 甚至没有开始，优先检查请求头读取；如果 Handler 已经进入但读取 r.Body 报超时，再看请求体和 ReadTimeout。这两个现象不应该混在一起。

WriteTimeout 保护的是响应写出，不是自动停止业务

WriteTimeout 是响应写入截止时间，并在读到新请求头时重置。它能避免响应长期写不出去，但不能保证耗时 Handler 在截止点自动结束。即使写入最终失败，数据库查询、外部调用或后台计算也可能还在执行，因此业务代码仍要使用 context.WithTimeout，并把 Context 传到底层依赖。

对 SSE、分块下载和长时间流式响应，我不会机械地套一个很短的全局写超时。可以根据协议设计关闭全局 WriteTimeout，再使用 http.NewResponseController(w).SetWriteDeadline(...) 对单次写入设置更贴合的截止时间。官方定义位于 https://pkg.go.dev/net/http#ResponseController.SetWriteDeadline。

IdleTimeout 只管“下一次请求什么时候来”

一个请求已经处理完，TCP 连接因 Keep-Alive 保留下来，此时服务端等待同一连接上的下一个请求，才进入 IdleTimeout 的范围。它不会中断正在读取的请求体，也不会终止正在运行的 Handler。把它设得过大，会让大量空闲连接占用文件描述符和内存；设得过小，则会减少连接复用，增加握手成本。

把连接层截止时间与业务超时拆开

我后来最受用的做法，是把配置分成“连接层保护”和“每请求业务保护”两张清单。前者限制 socket 读写和连接状态，后者限制 Handler、下游调用与输入规模。这样看到 504、连接重置或 Context deadline exceeded 时，不会把完全不同的原因都归到 WriteTimeout。

• 连接层：ReadHeaderTimeout、ReadTimeout、WriteTimeout、IdleTimeout。
• 容量边界：MaxHeaderBytes 只限制请求头；请求体大小另用 http.MaxBytesReader。
• 业务层：Handler 用 Context 设定自己的截止时间，并把它传给数据库、RPC 与外部 HTTP 客户端。
• 统一响应：如果希望 Handler 超时后返回固定的 503，可以研究 http.TimeoutHandler；它不支持 Hijacker 和 Flusher，不适合流式响应。

TimeoutHandler 与 WriteTimeout 的差别尤其重要。前者给 Handler 一个时间上限，超时后返回 503，并让后续写入得到 ErrHandlerTimeout；后者是网络写截止时间。两者解决的问题不同，不能只看名字里的“Timeout”就互相替代。

按真实流量调整参数并检查副作用

我不会只凭经验拍出 2 秒、10 秒或 60 秒。更稳妥的做法，是把参数和流量特征一起记录：

1. 统计请求头大小、请求体大小、响应体大小以及端到端延迟的 p95、p99。
2. 区分普通 API、文件上传、文件下载、SSE 和 WebSocket，不把它们塞进同一套模板。
3. 让上游网关、Go Server、业务 Context 和下游客户端形成清晰的超时层级，并预留错误返回时间。
4. 观察超时错误、活跃连接、空闲连接、文件描述符和 goroutine 数量，而不是只看平均响应时间。

一个常见层级是：下游调用超时最短，Handler 业务截止时间略长，网关等待时间再稍长。连接层读写超时则按请求和响应的传输需求设置。这样底层先失败，Handler 还有时间把错误转换成稳定响应，网关也不会抢先生成一个缺少上下文的 504。

形成上线前的配置清单

• 显式创建 http.Server，不要只依赖没有超时字段的快捷启动写法。
• 优先为请求头设置明确的 ReadHeaderTimeout。
• 确认 ReadTimeout 是否会误伤上传或慢速合法客户端。
• 不要把 WriteTimeout 当作 Handler 业务超时或 goroutine 取消机制。
• 为 Keep-Alive 设置与连接规模相符的 IdleTimeout。
• 为 Handler、数据库和外部请求建立可传播的 Context 截止时间。
• 让代理、应用和下游的超时顺序可解释，并在监控中区分读、写、空闲与业务超时。

如果只记住一句话，可以记成：读超时管“请求还没读完”，写超时管“响应还没写完”，空闲超时管“连接在等下一个请求”。再把业务 Context 独立出来，Go HTTP 服务的超时配置就不再是一组靠猜的数字。

相关问题

只设置 ReadTimeout，不设置 ReadHeaderTimeout 可以吗？

可以，但零值的 ReadHeaderTimeout 会使用 ReadTimeout。如果不同接口的请求体差异很大，单独设置较短的请求头超时通常更容易兼顾慢请求头防护和大请求体上传。

WriteTimeout 到期后 Handler 会自动停止吗？

不会把它当作可靠的业务取消机制。它限制响应写入，业务工作是否停止仍取决于代码是否设置并传播 Context、是否响应取消信号。

IdleTimeout 会中断正在执行的请求吗？

不会。它面向 Keep-Alive 连接在两次请求之间的空闲等待，活动请求由读取、写入和业务截止时间分别约束。

流式响应应该把 WriteTimeout 设成多少？

没有统一答案。SSE、分块下载等长连接响应通常要按协议重新设计截止时间，可考虑不使用很短的全局值，而对单次写入调用 ResponseController.SetWriteDeadline，同时保留心跳和客户端断开处理。