优雅停机时新请求为何还会进入，怎样关闭监听并等待在途请求

Go 服务收到 SIGTERM 后仍有新请求进入，通常不是 http.Server.Shutdown 失效，而是程序还没有真正调用它：仅取消业务 Context、把就绪探针改成失败，或先执行一段清理，都不会自动关闭监听器。真正开始 Shutdown 后，标准库会先关闭该 Server 的监听器，再关闭空闲连接，并等待活动连接回到空闲状态。

一个可靠的停机顺序可以概括为：先把实例标记为 draining，让就绪检查失败并拒绝新业务；给上游少量时间停止路由；随后调用 Shutdown 关闭监听并等待在途 Handler；超过截止时间才调用 Close 强制结束普通 HTTP 连接。主 goroutine 必须等 Shutdown 返回，不能在 ListenAndServe 返回 ErrServerClosed 时直接退出。

Go 标准库参考：https://pkg.go.dev/net/http#Server.Shutdown、https://pkg.go.dev/os/signal#NotifyContext

先分清新请求是在什么时候进入的

“收到停机信号”和“停止接收连接”是两个不同事件。signal.NotifyContext 只把信号转换为 Context 取消；如果代码在收到信号后继续做缓存刷新、注册中心注销或日志归档，而尚未调用 Shutdown，Serve 仍持有监听器，请求自然还能进入。

负载均衡器或编排平台还有自己的状态传播时间。实例把 /readyz 改成 503 后，上游不一定在同一微秒停止转发；已经建立的 Keep-Alive 连接也可能处在边界窗口。因此 draining 阶段既要让就绪检查失败，也要让业务入口快速返回 503，避免刚被摘除的实例继续接新任务。

先写一个能观察 draining 状态的服务

下面的示例把信号 Context 和请求 Context 分开。不要把收到 SIGTERM 的 Context 直接设置成所有请求的 BaseContext；否则信号到达时，正在执行的 Handler 会同时看到取消，与“让在途请求自然完成”的目标冲突。

package main

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

type application struct {
    draining atomic.Bool
}

func (a *application) ready(w http.ResponseWriter, _ *http.Request) {
    if a.draining.Load() {
        // draining 后让上游尽快摘除实例。
        http.Error(w, "draining", http.StatusServiceUnavailable)
        return
    }
    w.WriteHeader(http.StatusOK)
    _, _ = w.Write([]byte("ready"))
}

func (a *application) work(w http.ResponseWriter, r *http.Request) {
    if a.draining.Load() {
        // 边界窗口内到达的请求不再开启新业务工作。
        w.Header().Set("Retry-After", "5")
        http.Error(w, "server is shutting down", http.StatusServiceUnavailable)
        return
    }

    select {
    case 

这段代码里没有额外用 sync.WaitGroup 统计普通 HTTP Handler，因为 Server.Shutdown 已经负责等待标准 HTTP 活动连接。自己再维护一套计数容易在 Add 与 Wait 之间制造竞态。只有 Handler 启动了脱离请求生命周期的后台任务时，才需要单独的任务组和停止协议。

用两类请求观察停机窗口

这个小实验不需要压测工具。先启动服务，再发一个持续三秒的请求；请求尚未完成时发送 SIGTERM。draining 标记会让新请求得到 503，而已经进入的请求仍有机会完成。下面命令里的 PID 请替换为当前服务进程号。

# 启动示例服务，日志保留在当前前台会话中。
go run .

# 在另一个非生产测试会话中发起一个持续约三秒的在途请求。
curl -i http://127.0.0.1:8080/work

# 把 12345 替换为示例服务 PID，发送常见容器停机信号。
kill -TERM 12345

# draining 传播窗口内的新业务请求应返回 503 和 Retry-After。
curl -i http://127.0.0.1:8080/work

# 就绪检查应返回 503，提示上游停止继续路由。
curl -i http://127.0.0.1:8080/readyz

检查时关注三个结果：第一，收到信号后 /readyz 立即失败；第二，新的 /work 不再启动耗时任务；第三，已进入的请求可以在 20 秒截止时间内返回。之后 Serve 以 http.ErrServerClosed 结束，这是正常停机结果，不应被当成启动故障。

Shutdown 等待哪些资源，又不会等待哪些资源

官方定义很明确：Shutdown 先关闭所有已打开的监听器，再关闭空闲连接，然后等待连接返回空闲并结束。如果传入的 Context 到期，它返回 Context 错误；这个超时用于限制等待，并不等于自动把所有自定义资源都清掉。

• 普通 HTTP Handler：由 Shutdown 等待，前提是 Handler 能在业务超时内返回。
• 空闲 Keep-Alive 连接：会在 Shutdown 过程中关闭，不再用于接收下一次请求。
• WebSocket 或 hijacked 连接：不在 Shutdown 的自动等待范围内，应用必须自己通知和等待。
• 后台消费者、队列和定时任务：不属于 http.Server，需要独立的取消 Context 与任务组。
• 多个 Server：业务端口、管理端口和指标端口若分别创建 Server，就要逐个停止。

RegisterOnShutdown 适合发出协议级停机通知，例如通知 WebSocket 管理器停止接受新会话；回调本身不应该阻塞等待。真正的等待仍由应用自己的连接管理器完成。

var websocketManager interface {
    BeginShutdown()
    Wait(context.Context) error
}

// 回调只发通知，不在 Server 内部阻塞等待长连接退出。
srv.RegisterOnShutdown(func() {
    websocketManager.BeginShutdown()
})

// Shutdown 返回后，再用同一个截止时间等待应用管理的长连接。
if err := websocketManager.Wait(shutdownCtx); err != nil {
    log.Printf("websocket shutdown incomplete: %v", err)
}

为什么有时调用了 Shutdown 仍像是提前退出

最常见的错误是把 ListenAndServe 放在主 goroutine，而在另一个 goroutine 调用 Shutdown。Shutdown 一开始关闭监听器，ListenAndServe 立刻返回 ErrServerClosed；如果 main 随即 return，整个进程会终止，负责等待活动连接的 goroutine 也被一起结束。

解决方法就是示例中的角色反转：Serve 放到 goroutine，主 goroutine 等信号并同步执行 Shutdown。这样 main 的生命周期覆盖完整停机过程。

另一个误区是把 Shutdown(context.Background()) 当成“永远安全”。它确实可以无限等，但只要某个 Handler 没有业务超时、卡在外部依赖或一直写流式响应，发布就可能永远结束不了。生产环境必须给 Shutdown 一个小于平台终止宽限期的截止时间，把剩余时间留给日志刷新和最后退出。

扩展到多个服务和后台任务

如果同一进程里还有管理端口、指标端口、消息消费者或定时任务，先画清资源所有权，再决定顺序。通常先停止产生新工作，再等待已有工作；HTTP Server、队列消费者和 WebSocket 管理器各自维护自己的停止方法，最外层只负责共享截止时间和错误汇总。

groupCtx, cancelGroup := context.WithCancel(context.Background())
defer cancelGroup()

// 停止消费者继续领取新消息，但让已经领取的任务自行收尾。
consumer.StopAccepting()

// 取消只属于后台任务的 Context，不复用请求的停机信号 Context。
cancelGroup()

// 为所有应用资源共享剩余截止时间，避免各自无限等待。
if err := consumer.Wait(shutdownCtx); err != nil {
    log.Printf("consumer shutdown incomplete: %v", err)
}

数据库连接池通常放在所有请求与后台任务结束后再关闭。否则活动 Handler 虽然被 Shutdown 等待，却可能因为连接池先关而失败。日志器和遥测导出器也应留到最后刷新，但要有独立超时，不能把进程再次卡住。

上线前逐项确认

• 收到信号后是否立即设置 draining，并让就绪检查失败。
• draining 窗口内的业务 Handler 是否快速返回 503，而不是继续创建新任务。
• 是否真正调用了每一个 http.Server 的 Shutdown。
• main 是否等待 Shutdown 和 Serve 都结束，而不是看到 ErrServerClosed 就退出。
• Shutdown 截止时间是否小于部署平台给进程的终止宽限期。
• Handler 是否有数据库、HTTP 客户端和业务级超时，能够在截止时间内返回。
• WebSocket、hijacked 连接、后台消费者和定时任务是否有独立停止协议。
• 强制 Close 是否只作为超时兜底，并记录了未完成资源。

排查“停机后还有请求”时，不要只盯着信号处理代码。先确认 draining 是否生效，再确认监听器何时关闭，最后确认主 goroutine 是否真的等到了所有活动 Handler 返回。把摘流量、关监听和等在途请求拆成三个可观察边界，优雅停机才不会停在“看起来已经关了”的状态。

相关问题

Shutdown 会取消所有请求的 Context 吗？

不会为了停机直接打断活动连接。它等待活动连接回到空闲并关闭；请求自身仍应有业务超时和客户端取消处理。

为什么 Shutdown 后 ListenAndServe 返回错误？

这是接口约定。Server 在 Shutdown 或 Close 后，ListenAndServe、Serve 等方法会返回 http.ErrServerClosed，正常停机时应把它当成预期结果。

Shutdown 超时后还要调用 Close 吗？

如果进程必须在固定宽限期内退出，通常要用 Close 强制关闭普通活动连接，并记录哪些请求未完成。它不会自动管理 WebSocket 等 hijacked 连接。

需要自己给每个 Handler 加 WaitGroup 吗？

普通 HTTP Handler 通常不需要，Shutdown 已经等待活动连接。脱离请求生命周期的 goroutine、消费者或长连接才应由应用单独计数和等待。