Go 服务为什么优雅关闭仍超时

Go 服务调用 Server.Shutdown(ctx) 后仍然超时，通常不是“优雅关闭没有生效”，而是它确实还在等待活动连接回到空闲状态。最常见的根因是：处理函数没有返回、上游调用没有跟随请求取消、给 Shutdown 的时间预算过短，或者 WebSocket 等被接管的连接没有单独收尾。

先记住一个判断式：Shutdown 超时 = 关闭期限到达时，仍有连接或收尾工作没有结束。ListenAndServe 返回 http.ErrServerClosed 本身不是故障；真正需要追的是 Shutdown 返回的上下文错误，以及哪一类工作占用了剩余时间。

先看 Shutdown 真正在等待什么

官方语义是：Shutdown 先关闭监听器，再关闭空闲连接，然后等待活动连接回到空闲状态；传入的上下文到期时，它返回上下文错误。也就是说，停止接收新请求和进程真正退出是两个时刻。

最小的服务侧编排可以这样写。示例只表达关闭关系，不代表已经在本机运行过：

package main

import (
    "context"
    "errors"
    "log"
    "net/http"
    "os"
    "os/signal"
    "syscall"
    "time"
)

func main() {
    srv := &http.Server{Addr: ":8080", Handler: http.DefaultServeMux}

    // 信号协程只负责触发 Shutdown，主流程继续等待关闭结果。
    stop := make(chan os.Signal, 1)
    signal.Notify(stop, syscall.SIGINT, syscall.SIGTERM)

    go func() {
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            // 监听器异常要保留，正常 Shutdown 返回 ErrServerClosed 不应当报警。
            log.Printf("listen failed: %v", err)
        }
    }()

    

如果这里返回 context deadline exceeded，不要把 ErrServerClosed 当成原因。前者说明等待预算耗尽，后者只是监听循环知道服务正在关闭。

按负载和约束选择时间预算

关闭超时不能脱离业务负载单独设置。短请求服务通常只需要覆盖请求尾部和日志落盘；上传、导出、批处理接口则可能需要更长窗口；包含 WebSocket 的服务还要另算长连接通知时间。先把预算拆成三部分：

如果某个处理函数内部使用了独立的 context.Background()，或者启动 goroutine 后没有监听原请求的 Request.Context()，服务层已经停止接收请求，但业务仍可能继续占住活动连接。此时单纯把 20 秒改成 60 秒，只是延后暴露问题。

func handler(w http.ResponseWriter, r *http.Request) {
    // 把请求上下文传给下游，让客户端断开或服务收尾能够传递取消信号。
    result, err := loadReport(r.Context())
    if err != nil {
        // 取消、超时和业务错误应分别记录，便于判断是否拖住 Shutdown。
        http.Error(w, err.Error(), http.StatusGatewayTimeout)
        return
    }
    _, _ = w.Write([]byte(result))
}

func loadReport(ctx context.Context) (string, error) {
    // 下游调用必须接收同一个 ctx，不能在这里重新创建无限期上下文。
    select {
    case 

补齐服务、业务和长连接三层收尾

短请求场景只需要让 handler 尊重上下文，长连接则不同。官方文档明确指出，Shutdown 不会尝试关闭或等待被 hijack 的连接，例如 WebSocket；这类协议必须由应用自行通知、关闭并等待。

RegisterOnShutdown 适合发出协议级关闭通知，但回调本身不应阻塞等待全部连接结束。等待动作应由应用自己的管理器完成，否则回调阻塞会让关闭路径变得难以判断。

func registerShutdown(srv *http.Server, closeSockets func()) {
    srv.RegisterOnShutdown(func() {
        // 回调只发出长连接收尾通知，不在 Server 内部同步等待。
        go closeSockets()
    })
}

func waitForServer(srv *http.Server) error {
    // ErrServerClosed 表示关闭流程接管了监听循环，不应当重复发布为启动故障。
    err := srv.ListenAndServe()
    if errors.Is(err, http.ErrServerClosed) {
        return nil
    }
    return err
}

服务层还要保证主流程真的等到 Shutdown 返回。若信号协程调用了 Shutdown 后主函数立刻退出，进程会在清理完成前结束；这看起来像“Shutdown 超时”，实际是等待编排缺失。相反，如果主流程等待了 Shutdown，但某个 Hijack 连接永远不返回，就需要对该协议单独设期限或执行强制收尾。

用落地清单定位 deadline exceeded

遇到关闭超时，可以按下面顺序缩小范围：

1. 先分辨返回值。把 ListenAndServe 的 ErrServerClosed 与 Shutdown 的上下文错误分开记录。
2. 确认活动请求。在 handler 入口、关键下游调用和返回位置记录请求标识与耗时，重点找关闭时仍未返回的路径。
3. 检查上下文链。搜索是否存在脱离 r.Context() 的 context.Background()、无期限等待或没有退出分支的 goroutine。
4. 单独盘点特殊连接。确认 WebSocket、TCP 升级或其他 hijack 连接有通知、关闭和最终等待策略。
5. 重算外部预算。让请求收尾、依赖收尾和进程退出窗口彼此兼容；不要用无穷增大的 Shutdown 超时掩盖不返回的业务。

常见追问

Shutdown 返回超时后还能继续复用同一个 Server 吗？

不建议这样做。官方文档说明，调用过 Shutdown 后 Server 不应复用，后续 Serve 类方法会返回 ErrServerClosed。应该让当前进程按既定失败策略结束，或在更高层重新创建服务对象。

把 Shutdown 的 context 改成 Background 就不会超时了吗？

它可能不再因期限返回，但也会失去退出边界；如果请求或长连接永不结束，进程就可能一直卡在关闭阶段。正确做法是给 Shutdown 明确预算，并修复没有响应取消信号的工作。

总结：Go 的优雅关闭是“停止接新请求 + 等待已有工作收尾”，不是立即杀掉所有连接。先看活动请求是否归零，再核对业务上下文、长连接通知和主流程等待，通常比盲目增加超时时间更快找到根因。