Go http.Server RegisterOnShutdown 怎样安排异步清理

我在给 Go HTTP 服务接入长连接退出流程时，最容易写错的地方不是调用 Shutdown，而是把所有清理动作都塞进 RegisterOnShutdown 的回调里，然后在回调中同步等待。这样一来，通知协议连接开始退出和等待清理完成就纠缠在了一起。

更稳妥的安排是：回调只负责快速广播“开始关闭”，清理协程自行收尾；主 goroutine 负责调用 Shutdown，最后再用 WaitGroup 和超时上下文统一等待。官方文档也明确要求注册函数启动协议级优雅关闭，但不要等待关闭完成。

为什么回调里不能一直等

RegisterOnShutdown 的定位是通知钩子，适合唤醒 WebSocket、ALPN 升级连接或被劫持连接的协议处理器。它不是一个“把所有清理函数执行完再返回”的任务组。若回调直接执行网络收尾、等待远端确认或等待某个 goroutine 退出，服务器关闭流程就会被一个不可控的外部动作拖住。

这里还要区分两个事实：Shutdown 会关闭监听器、关闭空闲连接，并等待活动连接回到空闲状态；它不会替你关闭或等待被劫持的连接。后者需要调用方自行通知并等待。因此，回调要“发信号”，而不是“包办等待”。

一套可控的异步清理写法

下面的示例把长连接管理器简化成一个后台清理任务。RegisterOnShutdown 只关闭一次通知 channel；真正的清理逻辑在独立 goroutine 中运行，完成后通过 WaitGroup 让主流程知道。

package main

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

type connectionManager struct {
    once sync.Once
    stop chan struct{}
    done chan struct{}
}

func newConnectionManager() *connectionManager {
    return &connectionManager{
        stop: make(chan struct{}),
        done: make(chan struct{}),
    }
}

func (m *connectionManager) start() {
    go func() {
        defer close(m.done)
        

这个例子刻意把“触发”和“等待”拆开：回调里没有网络等待，也没有调用 Wait；Shutdown 返回后，主流程继续等待管理器完成。真实项目中可以把 done 换成多个资源管理器共享的 sync.WaitGroup，但仍要让每个任务有明确的退出信号。

服务器关闭和资源等待怎样排顺序

我更推荐下面这个顺序：先让服务器进入关闭流程，再等待自定义资源。因为 Shutdown 会先停止接收新连接，普通 HTTP 请求也有机会自然返回；此时异步清理任务收到通知，正在运行的协议连接可以和普通请求并行收尾。

重复关闭、超时和清理结果怎么处理

生产代码至少要处理三个边界。第一，信号处理、管理接口和测试代码可能同时触发关闭，所以通知 channel 要用 sync.Once 保护。第二，清理必须绑定有限的 context，否则某个远端连接失联会让进程永远停不下来。第三，超时后要记录哪些资源没有完成，并根据服务的退出策略决定返回错误还是继续退出。

func closeWithDeadline(manager *connectionManager) error {
    ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
    defer cancel()

    manager.notifyShutdown()
    if err := manager.wait(ctx); err != nil {
        // 把超时作为可观测事件记录，方便区分正常退出与强制退出。
        return fmt.Errorf("等待连接管理器结束：%w", err)
    }
    return nil
}

如果使用上面的辅助函数，需要在导入列表中加入 fmt。示例中的重点不是某个固定超时时间，而是把超时边界放在等待层，并保留原始错误，便于日志、指标或退出码继续判断。

这套方式适合什么场景

它适合 WebSocket、HTTP/2 升级后的协议连接、消息订阅、后台消费者和需要 flush 的审计管道。若应用只有普通短请求，直接使用 Shutdown 的上下文通常已经足够，不必为了形式再加一层管理器。

我自己的取舍是：所有“开始清理”的动作都允许异步，但所有“进程是否可以退出”的判断都集中在主流程。这样既不会让回调承担不可控的等待，也不会因为主 goroutine 过早返回而丢掉最后的清理机会。

相关问题

• RegisterOnShutdown 会等待回调执行完吗？ 不应把它当作等待机制；回调应该快速启动协议级关闭并返回。
• Shutdown 能关闭 WebSocket 吗？ 它不会主动关闭或等待被劫持的连接，需要应用自行通知并等待。
• 多个退出入口可以重复调用通知吗？ 可以统一调用，但通知 channel 应用 sync.Once 保证只关闭一次。
• 超时后还要继续等吗？ 通常不应无限等待，应记录未完成资源，再按服务的退出策略结束进程。

一句话总结：RegisterOnShutdown 负责“告诉资源该收尾了”，Shutdown 负责 HTTP 服务本身的优雅关闭，主流程再负责有限等待和结果决策。把三个职责分开，异步清理才不会反过来卡住服务退出。