Go http.Server 优雅关闭为什么仍有连接挂起怎样构造最小复现

如果调用 http.Server.Shutdown 后进程迟迟没有退出，通常不是监听端口没有关掉，而是仍有连接处在活动状态：处理器还没有返回、请求在等待下游，或者连接已经被 hijack。Shutdown 会关闭监听器和空闲连接，但会等待活动连接完成；它也不会替你关闭 WebSocket 这类 hijacked 连接。

官方地址：https://pkg.go.dev/net/http#Server.Shutdown

下面用一个刻意阻塞的处理器构造最小复现，再用 ConnState 和请求上下文区分“正常等待”和“代码没有退出”。

先分清监听器关闭和请求结束

Shutdown 的职责是停止接收新连接、清理空闲连接，并等待现有请求回到可关闭状态。因此 ListenAndServe 返回 http.ErrServerClosed，只说明监听入口已经结束，并不说明所有处理器都完成了。

真正需要定位的是那条仍处于活动状态的连接：它可能卡在业务锁、下游 HTTP 调用、消息消费，也可能在 handler 中等待一个永远不会到来的信号。退出上下文只负责给这段等待设置上限。

用阻塞处理器构造最小复现

下面的服务把 /hold 请求故意卡在 channel 上。收到终止信号后，监听器会关闭，但这条请求仍未返回，所以 Shutdown 会等到处理器释放，或者等到超时上下文到期。

package main

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

func main() {
	// 用 channel 模拟一个迟迟没有完成的业务依赖。
	hold := make(chan struct{})
	mux := http.NewServeMux()
	mux.HandleFunc("/hold", func(w http.ResponseWriter, r *http.Request) {
		select {
		case 

启动后在另一个 shell 请求 curl http://127.0.0.1:8080/hold，再向服务发送 SIGTERM。如果没有让处理器返回，约 3 秒后日志会显示 context deadline exceeded。这就是“端口已经不再接收新请求，但已有连接仍挂起”的最小复现。

用 ConnState 和上下文定位挂起点

给服务器加上 ConnState 可以记录连接从 StateNew、StateActive 到 StateIdle 或 StateClosed 的变化。若连接长期停在 StateActive，优先检查 handler 内部等待；若已经是 StateIdle，Shutdown 通常会主动清理它；若是 StateHijacked，则必须由应用自己维护关闭协议。

srv := &http.Server{
	Addr: ":8080",
	Handler: mux,
	ConnState: func(conn net.Conn, state http.ConnState) {
		// 只记录连接状态，帮助判断是活动请求还是空闲连接。
		log.Printf("remote=%s state=%s", conn.RemoteAddr(), state)
	},
}

诊断时不要把 StateActive 当成“网络连接坏了”。它只说明连接上仍有请求处理工作；根因往往在 handler 等待的资源。让下游调用继承 r.Context()，并为数据库、RPC 或 HTTP 客户端设置自己的超时，才能让 Shutdown 有机会等到业务自然返回。

按连接类型选择修复方式

普通 HTTP 请求的修复重点是“收到取消就返回”：把 r.Context() 传入下游，并在阻塞选择中处理 Done()。主 goroutine 则必须等待 Shutdown 返回，不能因为 ListenAndServe 先返回就直接结束进程。

如果优雅等待超过可接受窗口，可以记录超时并调用 Server.Close 做强制兜底；这会中断仍在处理的连接，不能当作无损优雅关闭。若连接经过 hijack 升级成 WebSocket 或自定义协议，Shutdown 不负责关闭它，应使用 RegisterOnShutdown 发出应用层通知，再等待自己的连接管理器清理。

常见误区和速查表

最小判断顺序是：先看 ListenAndServe 是否只是正常返回，再看 ConnState 是否还有活动连接，最后检查 handler 是否响应请求上下文。只要把“监听已关”和“请求已完成”分开观察，优雅关闭为什么挂起就不再是一个模糊现象。

相关问题

为什么设置了 Shutdown 超时还会看到连接？ 超时只让调用返回，不会让业务代码自动完成；必要时还要决定是否调用 Close。

StateIdle 也会阻塞 Shutdown 吗？ 按标准 HTTP 连接语义，空闲连接属于 Shutdown 的清理对象；若仍不退出，应继续排查活动请求、hijack 连接或主 goroutine 的等待逻辑。