http.Server 优雅停机并等待连接收尾的实现方式

Go 服务的优雅停机，核心不是“收到信号后马上退出”，而是先让 http.Server 停止接收新连接，再给已经开始的请求一段明确的收尾时间。标准库提供的 Server.Shutdown 正好负责这件事：它会关闭监听器、关闭空闲连接，并等待活动连接回到空闲状态；如果等待超过传入的 Context，就返回 Context 的错误。

官方文档：https://pkg.go.dev/net/http#Server.Shutdown

结论：让 ListenAndServe 独立运行，把退出信号转换成带超时的 Shutdown，主 goroutine 必须等待它返回；不要把 ErrServerClosed 当成故障，也不要用 Close 代替优雅停机。

先分清 Shutdown 和 Close 的职责

Server.Close 是立即关闭监听器和连接的硬停机入口，活动请求可能被直接打断。Server.Shutdown 则先停止接收新的连接，再处理空闲连接，最后等待活动连接完成。两者返回的错误仍然需要记录，但它们对正在处理的请求给出的机会完全不同。

因此，部署环境里的退出流程通常要保留两个时间概念：进程收到退出信号后的总收尾窗口，以及单个请求自己使用的读写超时。前者由 Shutdown(ctx) 控制，后者由服务配置和业务 Context 控制，不能混成一个无限等待。

把信号、Serve 返回值和主 goroutine 接起来

最容易遗漏的是主函数的生命周期。如果启动服务的 goroutine 收到 ErrServerClosed 就结束，而主函数没有等待 Shutdown 返回，进程可能在活动请求完成之前退出。正确的结构是：服务 goroutine 只负责报告监听结果，信号处理 goroutine 负责调用 Shutdown，主函数等待关闭流程收尾。

package main

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

func main() {
	srv := &http.Server{
		Addr:    ":8080",
		Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			w.WriteHeader(http.StatusOK)
			_, _ = w.Write([]byte("ok"))
		}),
	}

	serveErr := make(chan error, 1)
	go func() {
		// Shutdown 会让 ListenAndServe 返回 ErrServerClosed，这不是异常。
		serveErr 

这里把错误分成两类：ErrServerClosed 是 Shutdown 或 Close 触发后的正常返回信号；端口占用、监听器创建失败等其他错误才代表服务启动或运行异常。serveErr 使用带缓冲的 channel，是为了让服务 goroutine 在主流程已经进入收尾时仍能安全发送结果。

用带超时的 Context 控制连接收尾窗口

Shutdown 会等待活动连接变为空闲，但这个等待并不是无条件的。把 context.WithTimeout 传进去，服务就有了可被编排系统识别的退出边界：窗口内完成时返回 nil，超过窗口时返回 context deadline exceeded。此时不要再误判为“没有执行 Shutdown”，而要把它记录为仍有连接没有在窗口内完成。

带超时的关闭逻辑还会暴露业务处理的问题：如果请求处理函数没有响应自身的 r.Context().Done()，它可能一直占着活动连接，直到 Shutdown 的总窗口耗尽。优雅停机只能管理连接生命周期，不能替业务代码凭空中断不可取消的工作。

func handler(w http.ResponseWriter, r *http.Request) {
	workDone := make(chan struct{})
	go func() {
		defer close(workDone) // 无论正常完成还是提前返回，都通知等待方
		// 执行可以被上层取消的业务工作。
	}()

	select {
	case 

在真实服务中，业务 goroutine 还应接收一个能被取消的子 Context；上面的代码只展示响应路径如何观察请求取消。关闭窗口和业务取消需要同时设计，否则“等待连接收尾”可能只是在等待一个永远不会结束的处理函数。

长连接、重复关闭和上线后的取舍

官方文档特别说明，Shutdown 不会关闭或等待被 hijack 的连接，例如 WebSocket。此类长连接需要由协议层单独发送关闭通知，并自行等待它们退出；RegisterOnShutdown 可以注册通知函数，但回调应该启动协议级收尾，不应该在回调里阻塞等待整个关闭流程。

另一个边界是复用：一旦对同一个 Server 调用了 Shutdown，后续再调用 Serve 等方法会返回 ErrServerClosed，因此不要把它当作可以反复启动的对象。需要重启时，创建新的 Server，并重新建立监听器和依赖。

结论：让停机流程拥有明确的等待者

http.Server 的优雅停机可以归纳成一条职责链：退出信号触发 Shutdown，Shutdown 关闭监听并处理空闲连接，带超时的 Context 限制活动连接的收尾窗口，主 goroutine 等待关闭结果，长连接再由协议层补充通知。只要把“停止接收新请求”“等待已有请求完成”和“超过窗口后的处理”分别写清楚，服务退出就不会变成一个不可解释的进程终止。

相关问题：

• 为什么不能直接用 Server.Close？ 因为它是立即关闭路径，活动请求不再获得优雅收尾机会。
• Shutdown 返回 nil 就代表所有后台工作都结束了吗？ 只代表 HTTP Server 的连接收尾完成，业务后台 goroutine 仍需自己的生命周期管理。
• 为什么要等待 ListenAndServe 的返回值？ 这样可以区分服务异常退出与 Shutdown 触发的 ErrServerClosed。