Go HTTP 服务优雅停机为何仍会丢请求：Shutdown、连接状态与超时窗口

线上发布切流后，旧实例日志里经常会出现一小撮 499、EOF 或“客户端提前断开”。调用了 server.Shutdown(ctx) 并不等于所有请求都会被保住：它先阻止新连接，再等待活跃连接结束；如果请求本身没有响应、处理时间超过停机上下文，或者进程在等待期间被强制结束，仍然会丢。

即使正确调用了 http.Server.Shutdown，也不能把它理解成“请求零丢失”开关；连接状态、全链路超时和进程退出顺序没有对齐时，正在处理的请求仍可能被中断。

先分清 Shutdown 到底承诺了什么

http.Server.Shutdown 会关闭监听器，让服务不再接受新的连接；随后它会关闭空闲连接，并等待活跃连接回到可关闭状态。这个过程是有序的，但它不会替每个 handler 设定业务截止时间，也不会改变已经发到客户端的数据。

因此，下面三件事不能混为一谈：

• 监听端口不再接收新请求；
• 当前 handler 已经返回，响应可以完整写出；
• 客户端已经收到响应，并且业务方把结果视为成功。

第一件事由服务器收口完成，第二件事取决于 handler，第三件事还受网络和客户端超时影响。

一个请求为什么会卡在停机窗口里

假设发布系统先把实例从负载均衡后端摘除，再发送 SIGTERM。此时仍可能有已经建立的 Keep-Alive 连接，也可能有刚进入 handler 的慢请求。摘流只影响后续分配，不会瞬间抹掉这些连接。

下面这个 handler 用来模拟一个还没结束的业务调用：

func reportHandler(w http.ResponseWriter, r *http.Request) {
    select {
    case 

如果停机上下文只有 3 秒，Shutdown 会在等待窗口结束后返回错误。它不会把这个 handler 变成成功响应；应用必须决定是继续等待、记录未完成请求，还是进入最后的强制收尾。

把停机编排写成可核对的阶段

生产代码通常需要一个独立的信号协程和一个明确的退出顺序。下面的重点不是复制一份万能模板，而是让每个阶段都有日志和可验证的结果：

func stopServer(srv *http.Server, stop 

实际项目还应在这段流程外完成负载均衡摘流、后台消费者停止接单和指标刷盘。不要只看 Shutdown 的返回值；至少要同时记录收到信号的时间、开始收口的时间、活跃请求数和最终退出原因。

停机超时应该怎样和业务耗时对齐

停机窗口不是越长越好。窗口太短会把正常的慢请求直接截断，太长则可能让发布滚动过慢，甚至让编排系统先杀进程。可以先用接口耗时分位数估算：普通接口按 P99 留出余量，长任务则通过独立队列或可恢复任务处理，不要让进程退出一直等它。

一个更容易验收的规则是：记录 shutdown_started_at、shutdown_deadline、active_requests 和 shutdown_result。当截止时间到达仍有活跃请求时，日志必须说明数量和最长等待时间，而不是只打印一个笼统的 timeout。

三个容易把请求丢失归错的边界

把客户端断开算成服务器停机失败

客户端主动取消、代理超时和服务端 handler 超时会在日志里表现出相似的 EOF。结合请求上下文、响应写入结果和反向代理日志，才能判断是谁先结束了连接。

把 Keep-Alive 当成新的业务请求

连接仍然存在不代表有请求正在处理。排空指标应区分连接数和活跃请求数，否则会因为空闲连接误判停机卡住。

超时后继续写响应

停机上下文到期后，handler 可能还在自己的调用链里运行。业务代码应监听 r.Context().Done()，让下游查询、远程调用和重试一起结束；否则即使进程暂时没退出，也可能继续占用资源。

常见问题：怎样确认这次停机没有留下隐患

Shutdown 返回 nil 就代表没有请求丢失吗？

不代表。它只能说明服务端收口和等待过程按服务器语义完成，客户端是否收到完整响应还要结合请求日志、代理状态和业务结果确认。

停机时应该先关数据库连接吗？

通常先停止接收新流量并排空 HTTP 请求，再关闭数据库等下游资源。顺序反过来会让仍在运行的 handler 先遇到连接池错误。

超时后要不要立刻调用 Close？

如果进程即将被编排系统强制结束，应记录未完成请求并进入最后的关闭路径。是否调用 Close 要结合服务的连接类型和恢复能力，不能把它当成补发响应的手段。

上线前的停机检查清单

• 负载均衡摘流是否早于服务端收口，并且有可观察的状态变化？
• handler 和下游调用是否都能响应 r.Context() 取消？
• 停机窗口是否覆盖正常请求 P99，并保留退出和日志刷盘余量？
• 超时是否会输出活跃请求数、最长等待时间和最终退出原因？
• 发布后是否用一条慢请求和一条 Keep-Alive 请求做过回归验收？