Go HTTP 服务优雅关闭怎么做？Shutdown、超时和连接收尾的取舍

服务实例收到终止信号后，如果立刻让进程退出，正在处理的支付回调、上传和长查询都会被截断；如果只调用 http.Server.Shutdown 又不给时间预算，某条慢连接可能让下线一直挂住。比较稳的做法是把关闭拆成四步：先停止接收新流量，再等待短请求完成，同时通知长连接退出，最后按明确超时兜底。

先按流量模型决定关闭策略

优雅关闭不是一段固定代码，而是一组约束的取舍。对只有短请求的后台 API，重点是不要接收新连接、给在途请求几秒钟完成时间；对带 SSE、WebSocket 或升级协议的服务，重点转成“通知客户端尽快离开，并限制最长等待”；对消费队列的 HTTP 网关，还要把停止取新任务、确认已取任务和关闭下游连接排进同一预算。

net/http 官方文档对 Shutdown 的行为写得很清楚：它会先关闭开放的监听器，再关闭空闲连接，然后等待活动连接变为空闲并关闭。关闭开始后，Serve、ListenAndServe 等方法会返回 ErrServerClosed；主程序不能看到这个返回就直接结束，而要等待关闭流程完成。

一段可用的最小关闭骨架

下面的写法把启动与关闭职责分开：HTTP 服务在单独 goroutine 中运行，主流程等待系统信号，再用固定预算调用 Shutdown。示例只演示普通 HTTP 请求的收尾，长连接和后台任务会在后文单独处理。

func main() {
	srv := &http.Server{
		Addr:              ":8080",
		Handler:           routes(),
		ReadHeaderTimeout: 5 * time.Second,
	}

	serverErr := make(chan error, 1)
	go func() {
		serverErr 

这段代码的关键不是 20 秒这个数字，而是“有预算、能观测、可调整”。线上应从平台的终止宽限期反推：如果编排平台会在 30 秒后强制终止，应用内部通常要留出一部分时间给负载均衡更新和长连接通知，不能把 30 秒全交给 Shutdown。

为什么先摘掉新流量，比先停监听更稳

服务进程调用 Shutdown 后会停止接受新连接，但上游负载均衡、服务发现或反向代理可能还没有把实例摘掉。尤其在 keep-alive、HTTP/2 和连接复用存在时，客户端短时间内仍可能把请求打到即将退出的实例。实践中通常先让 readiness 或健康检查变为不可接流量，等待一个短缓冲，再进入进程关闭。

缓冲时间不必很长，目的只是让上游观察到状态变化。它应与健康检查频率、负载均衡刷新周期和业务容忍度匹配。这里不要用固定经验值覆盖所有环境：内网网关和公网多层代理的传播时间差异很大，先在预发环境记录从 readiness 变化到新请求停止进入的实际分布，再决定预算。

普通 HTTP、WebSocket 和后台任务要分开收尾

Shutdown 会等待普通活动连接，但官方文档同时指出，它不会主动关闭或等待被接管的连接，例如 WebSocket。对于这类连接，可通过 RegisterOnShutdown 发出协议专属的关闭通知，然后由连接管理器统计当前会话数，等待它们自己完成关闭。

后台 goroutine 也不能只靠 HTTP 服务关闭。每个长任务应有自己的根 Context 或停止信号：停止接收新任务、让已取任务在预算内完成、超时后把未完成任务交还队列或进入可重试状态。只把 Shutdown 放在 HTTP 层，不会自动取消这些后台工作。

Close 什么时候才该出现

Server.Close 和 Shutdown 的语义不同。前者会立即关闭监听器和活动、空闲连接；后者尽量不打断活动连接。大多数发布流程应先走 Shutdown，仅当总预算耗尽、实例必须退出时，才把 Close 当成明确的强制兜底。这样做意味着可能会中断少量请求，因此要配合幂等、重试和客户端提示设计。

另一个常见误区是对每个依赖都用同一个超时。HTTP 请求、数据库事务、消息确认和 WebSocket 关闭的收尾速度不同。更好的方式是共享一个总 deadline，再给每个子系统预留子预算；总预算耗尽时记录是哪一层没有回落，而不是只得到一个笼统的“关闭超时”。

上线时应该观察哪些结果

1. 新流量是否停止。从 readiness 变更开始，观察实例的新请求数是否在预期窗口内降到零。
2. 在途请求是否自然回落。记录关闭开始时的 active request 数和返回时间分布，避免只看进程是否退出。
3. 长连接有没有剩余。记录 WebSocket、SSE 或自定义升级连接的会话数，并确认广播关闭后会下降。
4. 后台任务是否交接成功。检查任务领取数、确认数、重试数和队列积压，避免服务退出后留下“已取未完成”。
5. 强制关闭是否发生。只要进入 Close 或外部终止，就应有单独指标和日志，便于后续调整预算。

我更建议把一次受控下线演练放进发布前检查：对一台低流量实例发出终止信号，确认新流量停止、在途请求回落、长连接收到通知、任务没有丢失。这个结果比代码里是否出现了 Shutdown 更能说明方案可靠。

常见问题

Shutdown 会自动结束所有 goroutine 吗？

不会。它只管理 HTTP 服务器知道的监听器和普通连接。后台任务、自己创建的 goroutine、WebSocket 等需要独立的停止与等待机制。

为什么 ListenAndServe 返回了错误，但服务算正常停止？

调用 Shutdown 或 Close 后，ListenAndServe 会返回 http.ErrServerClosed。这是预期控制流，应与真正的启动或监听失败区分开。

关闭超时后要不要立刻 Close？

取决于平台的终止宽限期和业务幂等能力。通常先记录未回落的连接或任务，预算确实耗尽时再强制关闭，并把它作为需要复盘的信号。

WebSocket 能通过 RegisterOnShutdown 直接等到关闭吗？

不能。该钩子适合启动协议专属的通知动作，不应在钩子里长时间等待。等待会话结束应由外层连接管理器和总预算负责。

健康检查变失败后还需要 Shutdown 吗？

需要。健康检查只帮助上游停止分发新流量，Shutdown 负责本机监听器、空闲连接和活跃请求的收尾，两者承担不同边界。

优雅关闭的核心不是“等一会儿再退出”，而是让流量、连接和任务都知道停止从哪里开始、最多等多久、超时后怎样处理。把这些边界拆清楚，发布和扩缩容时的偶发失败会少很多。