Go http.Server.Shutdown 退出时为什么连接还没断：Shutdown、ConnState 与超时顺序

线上发布切流后，日志里已经出现 http: Server closed，容器却还要过几十秒才退出，这个现象通常不是 Shutdown 失效。ListenAndServe 返回只代表监听入口关了；正在处理的请求、保持空闲的连接、HTTP/2 长流，以及被 hijack 的连接，收尾责任并不相同。

Shutdown 会停止接收新连接并等待普通活跃连接自然回到空闲，但不会替你中断业务处理，也不会等待 hijack 连接；要让进程按预算退出，必须同时安排请求超时、状态观测和长连接的独立关闭路径。

先把“监听已关”和“请求已结束”分开

一个常见的退出协程大概这样写：

func waitForSignal(srv *http.Server) {
    

收到信号后，Shutdown 会先关闭监听器，所以新的请求不会再进入；随后它会处理空闲连接，并等待活跃连接回到空闲。一个正在跑数据库查询或等待下游响应的 handler，不会因为调用了 Shutdown 就自动被打断。

因此 ListenAndServe 返回 http.ErrServerClosed 很正常。主函数若在这里直接退出，优雅收尾还没有机会完成；若主函数一直等，超过 20 秒仍未返回，就该把超时连接找出来，而不是盲目把超时数字改大。

用 ConnState 找到卡住的连接状态

ConnState 是判断“连接还没断”的第一条证据。它能把连接按 StateNew、StateActive、StateIdle 和 StateClosed 记录下来，重点是看 Shutdown 等待期间是否还有连接长期停在活跃状态。

var states sync.Map

srv := &http.Server{
    Addr: ":8080",
    Handler: mux,
    ConnState: func(conn net.Conn, state http.ConnState) {
        states.Store(conn, struct {
            state http.ConnState
            at    time.Time
        }{state, time.Now()})
        if state == http.StateClosed {
            states.Delete(conn)
        }
    },
}

生产环境不建议直接把 net.Conn 当作日志字段长期保存，可以给连接分配短 ID，记录状态、开始时间、请求路由和最后一次状态变化。若大量连接一直是 StateActive，优先查 handler、数据库和下游调用；若停在 StateIdle，则要核对服务器版本行为和关闭等待是否已经进入下一轮。

把 Shutdown 超时和业务请求超时配成一条链

只给 Shutdown 设 20 秒，而 handler 内部的下游请求可以无限等待，最终看到的就是优雅退出超时。更稳妥的做法是让业务请求拥有更短的上限，并为进程留下明确的收尾余量。

const (
    requestLimit = 12 * time.Second
    closeBudget  = 20 * time.Second
)

func handler(w http.ResponseWriter, r *http.Request) {
    ctx, cancel := context.WithTimeout(r.Context(), requestLimit)
    defer cancel()

    if err := loadData(ctx); err != nil {
        http.Error(w, "request stopped", http.StatusGatewayTimeout)
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

这里的关系是：请求截止时间先到，handler 有机会结束；Shutdown 的预算稍后到，用来等待剩余连接完成；进程管理器的强制终止时间还要再晚一些。三层时间没有错开，优雅退出就只能碰运气。

WebSocket 和 hijack 连接不能靠 Shutdown 收尾

HTTP 连接升级或被 hijack 后，连接的生命周期已经交给应用。Shutdown 不会主动关闭，也不会等待这类连接。若服务里有 WebSocket、长轮询升级或自定义协议，必须维护连接集合，并在关闭阶段广播通知、等待读写循环结束。

srv.RegisterOnShutdown(func() {
    hub.BeginClosing()
})

go func() {
    if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
        log.Printf("http serve: %v", err)
    }
}()

// 收到退出信号后：先通知 hub，再等待 srv.Shutdown 的结果。
// hub 的连接清理由它自己的 WaitGroup 负责。

RegisterOnShutdown 的回调应该启动协议侧的关闭通知，不要在回调里阻塞等待全部连接，否则可能把服务器自己的收尾路径卡住。连接管理器再用 WaitGroup 或关闭通道等待每个读写循环退出。

常见问题：优雅退出还要看哪些边界

Shutdown 返回 context deadline exceeded 是失败吗？

它说明给定的收尾预算耗尽，并不代表监听器没有关闭。应结合连接状态和业务日志确认谁还在等待，再决定缩短请求、关闭长连接或调整预算。

为什么 ListenAndServe 返回 ErrServerClosed 不能直接当异常？

调用 Shutdown 或 Close 后，这是 net/http 约定的返回值。只有其他错误才需要按启动失败或运行中断处理。

ConnState 能不能直接告诉我是哪条请求卡住？

不能。它提供连接级状态，不包含完整业务上下文。要把连接短 ID、请求开始时间、路由和下游调用日志关联起来。

有 WebSocket 时把 Shutdown 超时改大就够了吗？

不够。hijack 连接不由 Shutdown 管理，必须由 WebSocket 或协议连接管理器主动通知、关闭并等待。

发布前的最小验收清单

• 发送退出信号后，监听端口不再接受新请求，ErrServerClosed 被识别为正常退出。
• 慢请求在业务截止时间内结束，超过 Shutdown 预算时能打印剩余连接线索。
• ConnState 记录不泄露连接对象，关闭后能清理状态。
• WebSocket 或 hijack 连接有独立通知、关闭和等待路径。

把退出当成一条有预算的生命周期来验证，通常比把 Shutdown 当成“一键断开”更接近线上真实情况。