Go http.Server.Shutdown 一直等待如何定位连接

我第一次遇到 Go 服务退出卡住时，直觉是把 Shutdown 换成 Close。后来发现，真正有用的顺序是先回答一个问题：到底是哪类连接没有回到可关闭状态。Shutdown 会先关闭监听器，再关闭空闲连接，然后等待活动连接回到空闲；因此它“一直等待”通常不是 API 失灵，而是还有请求、长轮询、流式响应或被劫持的连接没有结束。

官方资料：https://pkg.go.dev/net/http#Server.Shutdown

先用 ConnState 记录连接状态，再给 Shutdown 设置有限的 context。超时后看记录决定是修 Handler、结束长连接，还是对无法优雅退出的连接使用 Close 兜底。

先分清 Shutdown 在等什么

Shutdown(ctx) 的等待对象不是监听端口，而是服务器仍在管理的连接。监听器关闭后，新的请求不会再进入；空闲连接可以被回收；处于 StateActive 的连接仍要等当前 Handler 返回。若 Handler 在等待外部任务、读取一个迟迟不结束的请求体，或者持续写流式响应，Shutdown 就会继续等。

还有一个容易漏掉的边界：被 Handler 劫持的连接，例如 WebSocket，不由 Shutdown 关闭或等待。它们要由应用协议自己通知、关闭和等待。Serve 等方法在 Shutdown 后返回 http.ErrServerClosed，这是正常退出信号，不应把它记录成故障。

用 ConnState 把“卡住”变成可定位的记录

我现在会先给服务挂一个轻量的 ConnState 回调。它不需要修改业务 Handler，就能看到连接从新建、活动、空闲到关闭或劫持的状态变化。诊断时重点关注 Shutdown 开始后仍长时间停在 StateActive 或 StateNew 的连接。

package main

import (
	"fmt"
	"net"
	"net/http"
	"sync"
)

// connectionTracker 只保存诊断所需的当前状态，避免把历史连接无限留在内存中。
type connectionTracker struct {
	mu     sync.Mutex
	states map[net.Conn]http.ConnState
}

func (t *connectionTracker) update(conn net.Conn, state http.ConnState) {
	t.mu.Lock()
	defer t.mu.Unlock()

	// 关闭或劫持后，http.Server 不再负责后续生命周期，所以从表中移除。
	if state == http.StateClosed || state == http.StateHijacked {
		delete(t.states, conn)
		return
	}
	t.states[conn] = state
	fmt.Printf("conn=%p state=%s\\n", conn, state)
}

func main() {
	tracker := &connectionTracker{states: make(map[net.Conn]http.ConnState)}

	server := &http.Server{
		Addr: ":8080",
		// 让排查结果包含 StateActive、StateIdle 等状态变化。
		ConnState: tracker.update,
	}

	_ = server
	// 这里接入真实的 ListenAndServe 与 Shutdown 逻辑。
}

这段记录器只回答“还有哪些连接没有结束”，不等于知道业务原因。接下来要把状态变化和请求路径、请求开始时间或 Handler 内部任务日志关联起来。若某连接在 Shutdown 前已进入 StateActive，优先检查对应 Handler 是否忘记返回、等待没有超时，或把流式响应设计成了无限生命周期。

给 Shutdown 加超时，区分慢退出和无限等待

不要让进程退出流程没有边界。给优雅退出一个明确的时间预算，超时后记录 context deadline exceeded，这条结果本身就是定位证据：服务器在预算内没有达到 quiescent 状态。

package main

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

func gracefulStop(server *http.Server) {
	// 预算只约束优雅退出等待，不改变已经完成的请求结果。
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()

	if err := server.Shutdown(ctx); err != nil {
		if errors.Is(err, context.DeadlineExceeded) {
			// 记录超时，随后根据 ConnState 和业务日志决定是否强制关闭。
			log.Printf("graceful shutdown timed out: %v", err)
			return
		}
		log.Printf("graceful shutdown failed: %v", err)
	}
}

这里不要把超时直接解释成“连接泄漏”。它也可能只是某个合法的长请求超过了十秒。诊断记录要进一步区分：普通请求应缩短 Handler 的外部等待；长轮询和流式响应应在退出信号到来时主动结束；WebSocket 等劫持连接则要走独立通知路径。

劫持连接要用 RegisterOnShutdown 单独收口

如果服务使用 WebSocket、HTTP/2 协议升级或其他 hijack 场景，Shutdown 不会替应用关闭它们。可以注册一个通知函数，让协议层开始自己的优雅退出，但这个回调不应该在里面同步等待所有连接结束，否则会把 Shutdown 的通知阶段再次拖住。

server.RegisterOnShutdown(func() {
	// 这里只发出协议层的关闭通知，不在回调里阻塞等待连接全部退出。
	notifyLongLivedClients()
})

实际清理仍应由连接管理器负责：收到通知后停止接收新消息，向客户端发送协议允许的关闭信号，设置自己的等待截止时间，最后释放连接。若应用没有保存这些连接的引用，Shutdown 期间就很难知道它们是否已经退出，这也是“服务看似停了但进程不退”的常见原因。

最后才选择 Close 兜底

当有限等待已经超时，而且进程必须马上退出时，可以记录原因后调用 server.Close()。它会关闭活动连接以及仍处于新建、空闲状态的连接，代价是可能中断正在处理的请求。被劫持的连接仍然需要协议层自己关闭，因此 Close 也不是万能的清理按钮。

我会用下面这张表做最后判断：

相关问题

Shutdown 返回 ErrServerClosed 是错误吗？

通常不是。Shutdown 后 Serve、ListenAndServe 等方法返回 http.ErrServerClosed 是标准的停止信号，重点看 Shutdown 自己是否返回上下文超时或监听器错误。

为什么 Shutdown 结束了但 WebSocket 还没断？

因为 hijacked 连接不在 Shutdown 的等待范围内。需要在应用层保存连接并实现通知、关闭和等待，不能只依赖 http.Server。

总结一下：先看连接状态，再看 Handler 是否能结束，给优雅退出设置时间预算，最后为 hijacked 连接建立独立清理路径。这样才能知道“Shutdown 一直等待”究竟是慢请求、半开连接，还是生命周期已经移交给应用的长连接。