Go http.Server.ConnState 怎么在连接关闭时清理会话资源

长连接服务里，连接通常会比一次请求活得更久。若把会话缓冲区、订阅句柄或连接级限流对象挂在 net.Conn 上，就需要在连接真正结束时释放它们。Go 的 http.Server.ConnState 会在客户端连接状态变化时回调，最稳妥的做法是只在 StateClosed 和 StateHijacked 两个终态清理，并让清理过程具备幂等性。

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

结论先说：普通 HTTP 连接走到 StateClosed 时清理；升级或劫持后的连接走到 StateHijacked 时清理。StateIdle 只是 Keep-Alive 等待下一次请求，不能释放连接级资源；HTTP/2 的 StateActive 也不是某一个请求的开始和结束信号。

先把“连接结束”和“请求结束”分开

ConnState 的参数是底层连接和一个连接状态，它描述的是连接整体，而不是单个请求。状态通常从 StateNew 进入 StateActive，请求处理完后可能回到 StateIdle，也可能进入 StateClosed 或 StateHijacked。因此，连接进入空闲并不代表会话资源已经没有用处。

这一区分直接决定清理点：StateIdle 时仍可能收到后续请求，继续保留资源；StateClosed 是普通连接的终态；StateHijacked 也是终态，并且不会再转成 StateClosed。如果只监听 Closed，WebSocket 或其他升级连接就容易留下资源。

资源表要由谁拥有、谁负责并发保护

把连接级资源放进一个表时，至少要回答三个问题：连接何时登记、哪个状态触发摘除、清理动作是否会与其他状态回调并发发生。ConnState 回调不应假设所有连接状态都按单线程串行到达，所以资源表应由一个明确的 owner 管理，并用互斥锁保护。

下面的示例用一个小型会话对象表示连接级资源。示例只把资源生命周期绑定到连接，不把请求指标塞进这个回调；真正业务里的 Session.Close 应该自己保证关闭底层文件、订阅或缓冲对象的顺序。

package main

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

type session struct {
    // 这里代表需要随连接结束而释放的连接级资源。
    closeOnce sync.Once
    done      chan struct{}
}

func (s *session) Close() {
    s.closeOnce.Do(func() {
        // 先通知关联 goroutine 停止，再释放其它会话资源。
        close(s.done)
    })
}

type sessionRegistry struct {
    mu       sync.Mutex
    sessions map[net.Conn]*session
}

func newSessionRegistry() *sessionRegistry {
    return &sessionRegistry{sessions: make(map[net.Conn]*session)}
}

func (r *sessionRegistry) onConnState(conn net.Conn, state http.ConnState) {
    switch state {
    case http.StateNew:
        r.mu.Lock()
        // New 只登记一次；后续 Active/Idle 状态继续复用同一会话。
        if _, exists := r.sessions[conn]; !exists {
            r.sessions[conn] = &session{done: make(chan struct{})}
        }
        r.mu.Unlock()
    case http.StateClosed, http.StateHijacked:
        r.release(conn)
    }
}

func (r *sessionRegistry) release(conn net.Conn) {
    r.mu.Lock()
    current, exists := r.sessions[conn]
    if exists {
        // 先摘除映射，再在锁外关闭，避免回调重入或阻塞其它连接。
        delete(r.sessions, conn)
    }
    r.mu.Unlock()

    if exists {
        current.Close()
    }
}

关键点是“摘除”和“关闭”分成两步：锁内只完成映射变更，锁外执行可能触发其他逻辑的 Close。这样第二次收到同一个终态回调时查不到表项，自然不会重复关闭；sync.Once 则为资源对象本身再加一道保险。

把回调接到 Server，而不是 Handler 里猜时机

创建 http.Server 时，将注册表的回调绑定给 ConnState。Handler 只负责请求处理；它不需要知道连接何时进入 Keep-Alive，也不应该在每次请求结束时误删仍会复用的连接资源。

func newServer() *http.Server {
    registry := newSessionRegistry()
    mux := http.NewServeMux()

    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        // Handler 只处理请求，不在这里关闭连接级会话。
        w.WriteHeader(http.StatusNoContent)
    })

    return &http.Server{
        Addr:    ":8080",
        Handler: mux,
        ConnState: func(conn net.Conn, state http.ConnState) {
            // 连接进入 Closed 或 Hijacked 时，注册表负责释放关联资源。
            registry.onConnState(conn, state)
        },
    }
}

如果连接级资源还需要在建立连接前准备，也可以在 StateNew 登记；若只有第一次业务请求才能确定会话内容，可以在 Handler 中创建资源，但仍建议把最终释放统一交给注册表，避免散落多个退出路径。

为什么 StateIdle 不能作为清理点

Keep-Alive 连接在一个请求完成后会进入 StateIdle，它只是“暂时没有活跃请求”。如果此时删除会话，下一次请求到来时就会重新创建对象，可能造成订阅重复、缓存抖动或连接级状态丢失。

另外，HTTP/2 下 StateActive 表示连接从没有活跃请求变为至少有一个活跃请求，只有全部活跃请求完成后才会离开这个状态。它不能用来做“每个请求一次”的资源管理。请求级资源应跟随 Request.Context 或 Handler 自己的生命周期处理。

Hijacked 连接要单独设计关闭责任

劫持以后，连接不再由普通 HTTP Server 的请求循环管理。官方状态定义明确指出，劫持连接不会继续转到 StateClosed，所以注册表必须在 StateHijacked 分支完成摘除。至于底层连接什么时候真正 Close，要由接管它的协议实现负责；这里清理的是本服务关联的会话资源。

一个常见误区是：在 StateHijacked 回调里直接把底层连接关闭，然后又让 WebSocket 层关闭一次。更稳妥的边界是，回调只负责删除连接级会话、取消关联任务或发出停止信号；谁接管了底层连接，谁负责按协议完成最终关闭。

优雅停机时如何避免资源表成为旁路

Server.Shutdown 会停止接收新连接、关闭空闲连接并等待活跃连接回到可关闭状态，但你的自定义会话表仍然是应用自己的资源。正常情况下，连接状态终态会逐步触发释放；如果某个协议已经劫持连接，则它不一定走普通服务器的关闭路径，应用仍需在协议关闭流程中调用同一套资源释放函数。

因此可以把停机策略拆成两层：让 ConnState 处理单连接生命周期，让协议层或服务级 shutdown 处理已劫持连接与长期后台任务。两层都调用幂等的 release，就不必依赖“某一个回调一定最后到达”。

func closeAll(registry *sessionRegistry) {
    registry.mu.Lock()
    pending := make([]*session, 0, len(registry.sessions))
    for conn, current := range registry.sessions {
        // 先清空表，避免停机期间的新旧路径重复持有同一资源。
        delete(registry.sessions, conn)
        pending = append(pending, current)
    }
    registry.mu.Unlock()

    for _, current := range pending {
        // 在锁外执行幂等 Close，避免一个慢资源阻塞状态回调。
        current.Close()
    }
}

接入前后的排查清单

1. 确认普通连接最终能到达 StateClosed，且释放逻辑只从注册表摘除一次。
2. 确认升级连接在 StateHijacked 时已经释放应用侧会话，不等待 Closed。
3. 确认 StateIdle 不会触发资源删除，Keep-Alive 的下一次请求仍能找到同一连接资源。
4. 确认资源表的读写都受同一把 mutex 保护，关闭动作在锁外执行。
5. 确认 HTTP/2 的请求级数据没有放进 ConnState，而是放进请求上下文或 Handler 生命周期。
6. 确认服务级 shutdown 能覆盖被协议层接管的连接和不再由 Server 管理的后台任务。

常见问题

StateIdle 时能不能释放内存较大的会话对象？

只有在你明确接受下一次请求重新创建对象时才可以。若对象表达的是连接级会话，应保持到 Closed 或 Hijacked；若只是可重建的缓存，才适合另行设计空闲淘汰策略。

只监听 StateClosed 为什么 WebSocket 资源没有释放？

劫持连接是终态，不会再转成 StateClosed。应在 StateHijacked 分支摘除应用侧资源，并由接管连接的协议实现负责底层关闭。

ConnState 能不能统计每个 HTTP/2 请求的结束？

不能。HTTP/2 的 ConnState 描述连接整体活跃状态，不是请求级事件。请求级清理应使用请求上下文、Handler 返回路径或协议提供的请求钩子。

清理回调里要不要直接关闭 net.Conn？

通常不要把连接关闭责任一并塞进通用回调，尤其是 Hijacked 连接。回调负责释放应用拥有的关联资源，底层连接由当前协议或服务器生命周期的 owner 关闭。

总结

用 http.Server.ConnState 管理连接级会话资源时，先按状态语义划清边界：StateIdle 是等待，不是结束；StateClosed 和 StateHijacked 才是两个需要清理的终态。把资源表集中管理、在锁内先摘除、在锁外幂等关闭，就能同时覆盖普通 Keep-Alive、HTTP/2 和升级连接，避免泄漏与重复释放。