Go http.Server ConnState 怎样判断连接为何长期停在 StateIdle

如果你在 http.Server.ConnState 的日志里看到连接长时间停在 StateIdle，先别把它直接判定为连接泄漏。StateIdle 的官方含义是：连接已经处理完一个请求，处于 keep-alive 状态，等待下一个请求；它之后可以回到 StateActive，也可以进入 StateClosed。

官方文档：https://pkg.go.dev/net/http#ConnState

真正要判断的是“等待是否符合配置和业务预期”。记录进入空闲状态的时间、同一连接处理过的请求次数，再对照 Server.IdleTimeout 和最终是否收到 StateClosed，通常就能把正常 keep-alive 与异常资源滞留分开。

StateIdle 到底表示什么

ConnState 是连接级回调，不是每个 HTTP 请求的生命周期钩子。HTTP/1.x 中，一个请求处理完后连接可能进入 StateIdle；HTTP/2 中，StateActive 反映的是连接上是否存在活跃请求，不能拿它精确统计每个流。

因此，“长期 StateIdle”首先说明客户端没有在这个连接上发来下一个请求，或者服务端正在保留连接等待复用。只要连接最终关闭，且数量没有持续无界增长，这个状态本身不构成故障。

先用 ConnState 记录可判断的证据

不要只打印状态字符串。给每条连接分配一个轻量记录，保存进入状态的时间、最近状态和处理次数，才能回答“它空闲了多久”“是否曾经活跃过”“最后有没有收口”。下面的示例只展示观测结构，日志内容是格式示意。

package main

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

type connMark struct {
    last  http.ConnState // 记录最近一次连接状态
    since time.Time      // 记录进入该状态的时间
    hits  int            // 只统计经过该连接的请求轮次
}

func newConnObserver() func(net.Conn, http.ConnState) {
    var mu sync.Mutex // ConnState 可能从多个服务协程并发回调
    marks := make(map[net.Conn]*connMark)

    return func(conn net.Conn, state http.ConnState) {
        mu.Lock()
        defer mu.Unlock() // 先释放锁，再让后续业务读取快照

        now := time.Now()
        mark := marks[conn]
        if mark == nil {
            mark = &connMark{since: now}
            marks[conn] = mark
        }
        mark.last = state
        mark.since = now
        if state == http.StateActive {
            mark.hits++ // StateActive 是连接级变化，不等于单个 HTTP/2 请求
        }

        log.Printf("conn=%p state=%s since=%s hits=%d", conn, state, now.Format(time.RFC3339), mark.hits)
        if state == http.StateClosed || state == http.StateHijacked {
            delete(marks, conn) // 终态到达后清理观测记录，避免 map 自身泄漏
        }
    }
}

func main() {
    srv := &http.Server{
        Addr:        ":8080",
        IdleTimeout: 30 * time.Second, // keep-alive 等待超过该值后关闭空闲连接
        ConnState:   newConnObserver(),
    }
    log.Fatal(srv.ListenAndServe()) // 示例只关注服务启动和连接观测
}

这里最重要的不是计数器，而是终态清理。若你的观测 map 只增不删，即使 net/http 已经正确关闭连接，监控代码也会制造一个“连接泄漏”的假象。生产代码还应按需要把连接标识替换成不可暴露的内部 ID，不要把远端地址、Token 或请求内容写进日志。

用时间和终态判断是否异常

Server.IdleTimeout 表示 keep-alive 开启时等待下一个请求的最长时间；为零时会回退到 ReadTimeout，若相关值仍未提供，则没有空闲超时。对照这条配置，排查可以按下面的判断表进行：

“没有马上关闭”不等于“没有按预期结束”。连接是否应当保持，取决于 keep-alive 配置、客户端行为和协议。排查时要看同一个连接的完整状态序列，而不是只看某一条 StateIdle 日志。

三个容易误判的边界

第一，别把 ConnState 当请求监控。HTTP/2 的一个连接可以承载多个并发流，StateActive 只在活跃请求数从零变为一时出现，回到 idle 也要等所有活跃请求结束。逐请求耗时应放在 Handler、中间件或请求上下文中记录。

第二，别用 Shutdown 推断普通空闲超时。Server.Shutdown 会先关闭监听器和 idle 连接，再等待活跃连接回到 idle；这是服务退出流程，不是 IdleTimeout 的替代品。若需要优雅退出，应单独记录 shutdown 的开始、上下文截止时间和返回错误。

第三，别忘记 Hijacked。被接管的连接不会再按普通 HTTP 连接走到 StateClosed，资源释放责任已经转移到接管方。把这类连接和 keep-alive 连接混在一个“未关闭”指标里，结论一定会失真。

常见问题

StateIdle 是否代表请求卡住？不是。它代表请求处理完成后的等待状态；请求卡住更应通过 Handler 的耗时、请求上下文和服务端超时指标判断。

应该把 IdleTimeout 设得越小越好吗？不一定。过小会降低长连接复用，过大则会保留更多空闲连接。应结合客户端、反向代理和服务端的 keep-alive 约定选择。

为什么 map 里连接数一直涨？先确认是否在 StateClosed 和 StateHijacked 分支删除记录，再确认是否把 net.Conn 作为 map key 长期保存。观测代码本身的生命周期必须和连接生命周期一致。

结论可以压缩成一句话：StateIdle 是正常的连接等待状态，只有把“进入时间、IdleTimeout、后续状态和资源清理”放在一起看，才能判断它是否真的长期异常；HTTP/2 和 Hijacked 连接则必须单独解释。