滚动发布 Go HTTP 服务时，最怕的不是服务停不下来，而是它停得太快：SIGTERM 一来，连接还没排空，支付、下单、回调这类接口就可能只写了一半响应。今天这篇不讲 API 手册，按生产事故的方式把 Go HTTP 优雅关闭讲透。
先看一个真实味道很重的场景
你把一个 Go HTTP 服务放到滚动发布里，平台给旧进程发 SIGTERM，新实例开始接流量。看起来一切正常，但业务同学反馈偶发 502、499，日志里还有一些请求刚开始查库就断了。最后排查下来，问题不在数据库、不在网关，而是进程收到信号后直接退出，没有给正在处理的请求留排空时间。
这个坑我见过很多次。平时本地 Ctrl+C 很丝滑，线上一到发布窗口就露出边界：长请求、慢下游、客户端重试、反向代理连接复用，一起把“能跑”的代码变成“半截请求制造机”。
坏写法：把 ListenAndServe 当成主流程全部
很多项目第一版都是这么写的，短小、能启动、能接请求。但它没有接管系统信号，也没有区分 http.ErrServerClosed，更谈不上给活跃连接一个收尾窗口。
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/pay", payHandler)
// 线上最常见的坏味道：信号来了没有排空连接，
// ListenAndServe 返回 ErrServerClosed 还可能被 log.Fatal 打成故障。
log.Fatal(http.ListenAndServe(":8080", mux))
}
这段代码的问题不是语法，而是生命周期太粗糙。服务不是只有“启动”和“挂掉”两个状态，中间还应该有“停止接新流量、等待旧请求完成、收尾资源、退出进程”这几个步骤。
正确理解 Server.Shutdown
http.Server.Shutdown(ctx) 的核心价值是“有边界地温柔停机”。它会先关闭 listener，避免继续接新连接；再关闭 idle 连接；最后等待 active 连接回到 idle，直到你给的 context 超时或取消。注意，这不是无限等待，也不会替你处理所有后台 goroutine。
换句话说，Shutdown 管的是 HTTP server 的连接生命周期，不是你整个业务进程的所有生命周期。你的消息消费者、定时任务、异步落库、缓存刷新、外部 SDK 长连接，都要有自己的退出协议。
推荐写法：信号、server、超时分开管
我的习惯是把 HTTP server 显式创建出来，配上基础超时，然后用 signal.NotifyContext 接系统信号。ListenAndServe 放到 goroutine 里跑，主 goroutine 等信号，收到后创建一个新的 shutdownCtx，专门控制优雅关闭的最大等待时间。
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/pay", payHandler)
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 3 * time.Second,
IdleTimeout: 60 * time.Second,
}
errCh := make(chan error, 1)
go func() {
err := srv.ListenAndServe()
if err != nil && !errors.Is(err, http.ErrServerClosed) {
errCh <- err
}
close(errCh)
}()
sigCtx, stop := signal.NotifyContext(
context.Background(), syscall.SIGINT, syscall.SIGTERM,
)
defer stop()
select {
case <-sigCtx.Done():
log.Println("shutdown signal received")
case err := <-errCh:
if err != nil {
log.Fatalf("http server failed: %v", err)
}
return
}
shutdownCtx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
log.Printf("graceful shutdown timeout: %v", err)
_ = srv.Close()
}
if err := <-errCh; err != nil {
log.Printf("http server stopped with error: %v", err)
}
}
这里有两个细节很重要。第一，http.ErrServerClosed 不是故障，它通常说明 server 被正常关闭了，不应该被 log.Fatal 打成事故。第二，shutdownCtx 不要复用已经 canceled 的信号 context，否则你刚调用 Shutdown，它就会立刻返回。
Handler 也要尊重请求上下文
优雅关闭不是只在 main 里写几行代码。真正决定能不能稳住的，是你的 handler 和下游调用有没有使用 r.Context()。如果用户断开、网关取消、服务正在关闭，context 会把取消信号一路传下去。
func payHandler(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
orderID := r.URL.Query().Get("order_id")
if orderID == "" {
http.Error(w, "missing order_id", http.StatusBadRequest)
return
}
result, err := charge(ctx, orderID)
if err != nil {
if errors.Is(ctx.Err(), context.Canceled) {
log.Printf("request canceled order_id=%s", orderID)
return
}
http.Error(w, "charge failed", http.StatusBadGateway)
return
}
_ = json.NewEncoder(w).Encode(result)
}
我比较反感那种在 handler 里重新 context.Background() 的写法。它会把请求生命周期切断，导致上游都不等了，下游调用还在傻跑。线上排查时，这类 goroutine 往往最难解释。
滚动发布里怎么配才稳
如果服务前面有负载均衡或容器平台，光写 Go 代码还不够。你需要先让实例从就绪状态里摘出去，再给反向代理和客户端一点时间停止把新请求打进来，然后才进入 Shutdown。否则你这边已经准备停了，那边还在往旧实例发新请求。
经验上，Shutdown 超时时间要小于平台给进程的终止窗口。比如终止窗口是 30 秒，你可以给 HTTP 排空 20 秒，再留几秒给日志 flush、指标上报和最后的兜底退出。不要把所有时间都吃满，不然后面的清理逻辑没有余地。
容易忽略的几个坑
- 不要在收到 SIGTERM 后立刻 os.Exit(0)，它会跳过 defer，也不给请求收尾机会。
- 不要把 ErrServerClosed 当 fatal error，否则正常发布会被监控当成异常。
- 不要让 handler 里所有下游调用都用 context.Background()，这会破坏取消链路。
- WebSocket、SSE、长轮询这类长连接要单独设计关闭协议，不能只指望普通 HTTP 请求模型。
- 后台 worker 要和 HTTP server 分开关闭，最好有统一的 stop channel 或 context。
上线前我会这样验
第一步，在预发跑一组 5 到 20 秒的慢请求，发布时观察这些请求是不是能自然完成。第二步，看日志里有没有把 ErrServerClosed 打成 fatal。第三步，确认收到 SIGTERM 后 readiness 是否先变成不可用。第四步，看关闭耗时分布，别只看成功率。第五步，压一次下游超时，确认 r.Context() 能让调用及时收住。
我还会专门查一眼 goroutine 数量。优雅关闭写得好的服务，退出前 goroutine 会有明显回落；写得差的服务，HTTP 端口没了，后台任务还一堆，像是假装下班。
最后聊两句
Go 的 net/http 已经把优雅关闭的基础能力给得很清楚了，难点不在 API，而在你有没有把发布、负载均衡、请求 context、后台任务和超时窗口一起设计。线上服务的稳定，很多时候就是这些不起眼的边界。
我的建议很简单：HTTP server 显式创建，信号单独处理，Shutdown 给明确超时，handler 尊重 r.Context()，发布流程里先摘流量再排空。做到这几步，SIGTERM 就不会再变成半截请求的开关。
Python Pydantic v2 实战：TypeAdapter 别在请求里反复造 
