Go http.Server 怎样优雅关闭空闲连接

Go 的 HTTP 服务准备退出时，想让空闲连接尽快释放、让正在处理的请求有机会完成，应调用 http.Server.Shutdown，而不是直接调用 Close。Shutdown 会先停止监听新连接，再关闭空闲连接，最后等待活动连接回到空闲；把一个带超时的 context.Context 传进去，就能避免某个请求一直占住退出流程。

官方文档地址：https://pkg.go.dev/net/http

最小正确做法是：用 goroutine 运行 ListenAndServe，收到退出信号后创建超时上下文并调用 Shutdown，同时把 http.ErrServerClosed 当作正常退出结果处理。需要注意，WebSocket 等被劫持的连接不会由 Shutdown 自动等待。

• 空闲连接：Shutdown 会主动关闭，不再让 keep-alive 连接拖住进程。
• 活动连接：Shutdown 不主动打断，等待它们完成或回到空闲。
• 异常退出：上下文超时、监听器关闭失败和真正的启动错误要分开记录。

先区分 Shutdown 和 Close 的连接语义

Server.Close 会立即关闭监听器以及新建、活动和空闲状态的连接，适合明确要快速中断的场景。Server.Shutdown 则把“停止接收新连接”和“等待已有请求”拆开处理：先关闭监听器，再关闭空闲连接，活动请求仍有机会写完响应。

因此，题目中的“优雅关闭空闲连接”并不是单独调用一个 idle API，而是让 Shutdown 负责整个服务退出阶段。请求处理函数如果还在运行，Shutdown 会继续等待；如果等待超过上下文截止时间，返回值就是上下文错误。

用退出信号和超时上下文接住服务生命周期

下面的示例只保留生命周期相关代码。服务主循环负责启动，独立 goroutine 等待退出信号；收到信号后，先创建有限时长的上下文，再调用 Shutdown。这样空闲 keep-alive 连接会被回收，活动请求则最多等待指定时长。

package main

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

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
        // 健康检查只返回固定文本，便于把示例重点放在服务退出。
        _, _ = w.Write([]byte("ok"))
    })

    srv := &http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    shutdownDone := make(chan struct{})
    go func() {
        // 同时监听容器常见的终止信号和本地中断信号。
        stop := make(chan os.Signal, 1)
        signal.Notify(stop, os.Interrupt, syscall.SIGTERM)
        

这个顺序里有两个容易遗漏的点。第一，ListenAndServe 返回 http.ErrServerClosed 不代表发布失败，它说明服务监听器已因 Shutdown 关闭。第二，主 goroutine 不能看到这个返回值就马上退出，否则负责等待活动连接的 Shutdown goroutine 可能还没完成。

为什么空闲连接会先被关闭

HTTP/1.1 keep-alive 会让一次请求结束后的 TCP 连接暂时保持空闲，以便复用。服务开始退出后，继续保留这些连接没有意义，还可能让进程的连接状态看起来迟迟没有收敛。Shutdown 把空闲连接作为第一批可安全关闭的对象，正在执行的 handler 则继续留在活动状态。

可以把退出过程理解为三层边界：

如果服务有连接状态统计，应该在退出信号到来后停止接收业务流量，再观察活动请求是否按预期减少；不能把“监听器已关闭”误认为“所有请求已经完成”。

超时、WebSocket 和 Close 的边界

当某个 handler 长时间阻塞、上游依赖迟迟不返回，或者客户端一直保持活动请求时，Shutdown 会等待到上下文过期并返回 context deadline exceeded。这时进程是否继续退出要由部署策略决定，但日志必须保留超时事实，方便区分“正常收尾”和“被截止时间截断”。

另一个边界是被劫持的连接，例如 WebSocket。官方文档明确说明，Shutdown 不会关闭也不会等待这类连接。服务需要通过自己的连接管理器、协议关闭帧或 RegisterOnShutdown 注册通知，再单独等待它们结束；不能只依赖 HTTP Server 的活动连接计数。

func shutdownWithFallback(srv *http.Server) error {
    // 先给正常请求一个收尾窗口，超时后再由上层决定是否强制结束进程。
    ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
    defer cancel()

    if err := srv.Shutdown(ctx); err != nil {
        // Shutdown 失败不等于可以安全调用 Close，是否强制中断要结合业务策略。
        return err
    }
    return nil
}

部署前快速检查

把优雅关闭接入容器或进程管理器前，可以按下面的清单检查：是否停止了新连接入口；是否在 ListenAndServe 返回后等待 Shutdown；是否设置了覆盖最慢正常请求的超时；是否把 ErrServerClosed 从真实错误中分开；是否另行管理 WebSocket 等 hijacked 连接。

如果业务目标是“马上断开所有连接”，才考虑 Close。如果目标是“空闲连接先关、活动请求尽量完成”，使用 Shutdown 加超时上下文更符合 Server 的生命周期语义。

相关问题

• Shutdown 返回上下文超时后，应该继续调用 Close 吗？
• 为什么 ListenAndServe 返回 ErrServerClosed 不应该记成故障？
• WebSocket 连接怎样配合 RegisterOnShutdown 做协议级收尾？