Go HTTP Server IdleTimeout 为什么仍有慢连接

很多 Go 服务把 IdleTimeout 当成“连接最多只能慢这么久”，于是配置了 30 秒，仍然能看到慢连接持续占用。原因通常不是字段失效，而是连接还没有进入 keep-alive 等待下一次请求 这个阶段。

官方地址：https://pkg.go.dev/net/http

判断方法很简单：如果请求已经完整处理完，只是在等同一条连接上的下一次请求，才看 IdleTimeout；如果客户端还在慢慢发请求头、请求体，或者服务端正在慢慢写响应，就要看另外三个超时字段。

先把四种超时职责分开

http.Server 的四个时间字段作用阶段不同。IdleTimeout 控制 keep-alive 连接等待下一次请求的时间；ReadHeaderTimeout 控制读取请求头；ReadTimeout 控制读取整个请求，包括请求体；WriteTimeout 控制写响应的最长时间。

这里有一个容易忽略的回退规则：IdleTimeout 为零时，会使用 ReadTimeout 的值；如果两者都为零或为负，则没有这段超时。也就是说，下面这个配置并不是“IdleTimeout 没生效”，而是它根本没有单独的值：

server := &http.Server{
    // 只配置 ReadTimeout 时，IdleTimeout=0 会沿用它的值。
    ReadTimeout: 30 * time.Second,
}

从零写一个能看懂的配置

先做一个小型服务，把每个字段都写出来。示例不追求复杂业务，只让配置职责清晰，方便后续把慢连接归类。

package main

import (
    "log"
    "net/http"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        // 健康检查只返回固定文本，便于观察请求是否已经进入 Handler。
        w.Header().Set("Content-Type", "text/plain; charset=utf-8")
        _, _ = w.Write([]byte("ok\n"))
    })

    server := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,
        ReadTimeout:       20 * time.Second,
        WriteTimeout:      15 * time.Second,
        IdleTimeout:       30 * time.Second,
    }

    // ListenAndServe 返回的错误通常表示服务停止或监听失败。
    log.Fatal(server.ListenAndServe())
}

这组值表达的是四个独立意图：请求头不能无限慢，请求体有一个总读取上限，响应写入不能一直阻塞，处理完请求后的 keep-alive 空闲连接也不能无限保留。生产环境应根据请求体大小、上游代理和业务响应时间调整，不要机械复制秒数。

为什么 IdleTimeout 看起来没有关闭慢连接

最常见的误判是把“连接还活着”直接等同于“连接处于 idle”。实际上，至少有下面四种状态：

因此，一个客户端如果只发出请求头的一部分，就会停留在请求读取阶段；它没有进入 keep-alive 空闲等待，调小 IdleTimeout 不会改变这个现象。反过来，客户端已经拿到完整响应，连接只是保持复用，那么才应观察 IdleTimeout。

用客户端行为判断慢连接属于哪一类

排查时不要先改四个数字。先问“服务端有没有收到完整请求头”“Handler 有没有开始执行”“响应有没有开始写”，三个问题基本能把范围缩小。

1. 请求头阶段没有进入 Handler：优先看 ReadHeaderTimeout。它适合限制客户端迟迟不发完整请求头的情况。
2. 请求头已到达，但请求体很慢：看 ReadTimeout。它覆盖整个请求读取，不能把它理解成只限制请求头。
3. Handler 已处理，响应写不出去：看 WriteTimeout。这类连接可能是客户端读取速度很慢，或者网络路径阻塞。
4. 请求和响应都结束，只保留连接：看 IdleTimeout。此时它限制的是等待下一次请求的 keep-alive 空闲时间。

可以给 Handler 加一条轻量日志，确认请求是否真的进入业务代码。示例只记录方法和路径，不把请求头、Cookie 或令牌写入日志：

func logHandler(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // 进入 Handler 说明请求头已经被服务端解析到足够继续处理。
        log.Printf("handler method=%s path=%s", r.Method, r.URL.Path)
        next.ServeHTTP(w, r)
    })
}

本地运行和验收时看什么

把上面的 Handler 包在 logHandler 外层后启动服务，再从客户端分别制造“完整请求后等待”和“请求头迟迟不完整”两种行为。命令只用于观察配置边界，不能把客户端输出当成服务端源码的证明。

# 启动示例服务，观察 /health 是否能正常返回。
go run .

# 发送一个普通请求，确认 Handler 已进入并返回固定文本。
curl -i http://127.0.0.1:8080/health

验收重点不是“所有连接都在 30 秒后消失”，而是：

• 普通请求能在 WriteTimeout 允许的范围内完成；
• 请求头迟迟不完整时，由 ReadHeaderTimeout 覆盖；
• 请求体持续读取时，不超过 ReadTimeout 的总窗口；
• 响应结束后的 keep-alive 连接，在 IdleTimeout 到期后不再无限保留。

反向代理和长连接场景要额外留意

如果 Go 服务前面还有反向代理、网关或负载均衡，客户端看到的连接可能先被外层组件持有。此时需要分别对照外层的请求头、请求体、响应和 keep-alive 配置，再与 Go 的四个字段比较。外层连接更早关闭时，Go 的字段不会延长它；外层连接更晚关闭时，Go 的字段也不会替它管理代理到客户端的那一段连接。

WebSocket 等被升级或劫持的长连接也不能简单套用普通 keep-alive 的结论。应用接管连接后，应由应用自己设计读写截止时间和关闭策略；不要只调大 IdleTimeout 来“修复”所有长连接。

一张表记住配置边界

结论是：IdleTimeout 没有失效，通常只是连接还没有进入它负责的阶段。先确认连接位于读取、处理、写响应还是 keep-alive 等待，再选择字段，排查会比不断调小一个数字更快。

相关问题

IdleTimeout 为零是不是永不超时？

不一定。它为零时会回退到 ReadTimeout；只有两者都没有正数值时，keep-alive 空闲等待才没有这个超时。

ReadHeaderTimeout 和 ReadTimeout 可以同时设置吗？

可以。前者先约束请求头读取，后者覆盖整个请求读取；把两者分开写能让配置意图更清楚。

为什么设置 IdleTimeout 后请求体上传仍然很慢？

上传发生在请求读取阶段，不是 keep-alive 空闲阶段。应根据请求体大小和业务容忍度调整 ReadTimeout，必要时在 Handler 内对请求体处理做更细的边界控制。

参考资料：https://pkg.go.dev/net/http；https://go.dev/src/net/http/server.go