优雅停机

Go 的 http.Server.Shutdown 不是“立即关闭端口”的快捷方法，而是一套有等待语义的优雅停机流程。它先停止接收新连接，再关闭空闲连接，最后等待正在处理的请求回到空闲状态。因此，调用后仍然等待并不代表方法失效，通常说明还有活动请求、长轮询或流式处理没有结束。

想让优雅停机可控，核心是给 Shutdown 传入带超时的 context，同时保证主 goroutine 不会因为 ListenAndServe 返回 ErrServerClosed 就提前退出。

先看 Shutdown 为什么会等待连接

官方语义可以拆成四个对象：监听器负责接收新连接，idle 连接暂时没有请求，active 连接正在执行请求，hijack 连接已经脱离标准 HTTP 生命周期。Shutdown 会关闭监听器和 idle 连接，但不会打断 active 请求，而是等待它们自然结束。

用带超时的 context 设定停机边界

不要把 context.Background() 作为生产停机的唯一选择。它会让 Shutdown 一直等到连接归还；更稳妥的做法是给停机窗口设置明确时长，并单独处理 http.ErrServerClosed。

package main

import (
	"context"
	"errors"
	"log"
	"net/http"
	"time"
)

func serve(srv *http.Server, stop 

这里的关键不是把错误吞掉，而是区分两条路径：ErrServerClosed 表示服务已进入关闭流程；context 到期则说明仍有连接未能在窗口内结束。主流程还应等待负责调用 Shutdown 的 goroutine 完成，不能只看到 ListenAndServe 返回就退出进程。

一直等不到 idle 时，按连接状态找原因

如果 Shutdown 总是返回 context deadline exceeded，优先查活动请求的生命周期，而不是反复增加超时时间。常见原因包括处理器内部等待下游、没有结束的长轮询、持续写响应的流式接口，以及把客户端断开没有传递给下游。

可以用 ConnState 记录状态变化，观察哪些连接长时间停留在 StateActive。它适合做定位线索，不应该被写成“收到停机信号后强制关闭所有 active 连接”的替代品。

srv := &http.Server{
	Addr: ":8080",
	// 记录连接状态，帮助定位停机时长期保持 active 的请求。
	ConnState: func(conn net.Conn, state http.ConnState) {
		if state == http.StateActive {
			log.Printf("active connection: %s", conn.RemoteAddr())
		}
	},
}

上面的片段只展示观测点，实际文件还需要导入 log、net 和 net/http。生产代码应避免在状态回调里做阻塞 I/O；真正的修复应回到 handler，让请求在收到取消信号后停止等待和写出。

hijack 连接要单独收尾

WebSocket 或其他协议升级后，连接可能已经被应用接管，Shutdown 不会替你关闭或等待它们。可以用 RegisterOnShutdown 发出协议级通知，但回调只负责启动收尾，不应在回调内部等待全部连接结束；等待动作应由独立的连接管理器完成。

还要注意，Server 调用过 Shutdown 后不能复用，之后再次 Serve 会返回 ErrServerClosed。因此优雅停机应该配合进程级重启或新 Server 实例，而不是尝试“关掉再开”。

相关问题

为什么 ListenAndServe 返回了，进程还不能退出？ 因为 Serve 返回只表示监听循环结束；主流程还需要等待 Shutdown 的清理逻辑，避免活动请求被进程直接终止。

Shutdown 超时后要不要改用 Server.Close？ 如果停机窗口已到期，可以按业务等级决定是否强制关闭；但 Close 会立即关闭更多连接，应该记录未完成请求并把它当作降级路径。

keep-alive 会让 Shutdown 永远等待吗？ 纯 idle 连接会被 Shutdown 关闭，真正拖住等待的通常是 active 请求或脱离标准生命周期的 hijack 连接。