唯一靠谱的选择是http.Server.Shutdown(),因其先拒新连接再等待存量请求自然完成或超时;而Close()会立即终止监听并丢弃未完成请求,导致502/连接重置。

为什么 http.Server.Shutdown 是唯一靠谱的选择
直接调用 http.Server.Close 会立即终止监听并丢弃所有未完成的请求,这在生产环境等于主动制造 502/连接重置。Go 1.8 引入的 Shutdown 才是标准优雅关闭入口——它先关闭监听器,再等待活跃连接自然结束(或超时),全程不中断正在处理的 HTTP 请求。
关键点在于:Shutdown 不是“立刻关”,而是“等完再关”。它依赖每个连接的 net.Conn 自行退出读写循环,所以你的 handler 不能阻塞在无超时的 I/O 上(比如没设 Context 超时的数据库查询)。
必须配合 context.WithTimeout 控制最大等待时间
不设超时的 Shutdown 可能永远卡住(例如某个客户端长连接死活不发 FIN)。实际部署中必须用带 timeout 的 context:
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := server.Shutdown(ctx); err != nil {
log.Printf("server shutdown error: %v", err)
}
常见错误:把 time.Second * 30 直接传给 Shutdown —— 它只接受 context.Context,不是 duration。
- 10 秒是较稳妥的起点;若服务含大量流式响应或大文件上传,需按业务延长
- 超时后
Shutdown返回context.DeadlineExceeded,此时应记录告警但继续执行后续清理逻辑 - 别在
Shutdown前调用cancel(),否则 context 立即失效,等同于没等
信号监听要避开 os.Interrupt 和 syscall.SIGTERM 的陷阱
Linux 容器(如 Kubernetes)发的是 SIGTERM,而本地 Ctrl+C 是 os.Interrupt(本质是 SIGINT)。只监听其中一个会导致部分场景无法触发关闭:
sigChan := make(chan os.Signal, 1) signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
容易踩的坑:
使用 uber-go/dig 在 Golang 中实现依赖注入——基于反射容器,提供 Provide/Invoke、dig.In/dig.Out 参数与结果对象,支持命名依赖等
- 用
signal.Notify(sigChan, os.Interrupt)单独监听,在容器里收不到SIGTERM,进程永不退出 - 没设 buffer(
make(chan os.Signal, 1)中的1),当多信号连续到达时会丢失第二个 - 在
sigChan收到信号后,忘记停掉 signal.Notify(虽非必须,但避免 goroutine 泄漏)
HTTP handler 内必须尊重 Request.Context().Done()
优雅关闭的成败,一半取决于 handler 是否及时响应上下文取消。哪怕 Shutdown 等了 10 秒,只要某个 handler 死循环读 socket 或没检查 ctx.Done(),连接就卡住不释放。
典型反例:
// ❌ 错误:忽略 request context,可能永远阻塞
func badHandler(w http.ResponseWriter, r *http.Request) {
data := db.Query("SELECT * FROM huge_table") // 没传 ctx,查不完不返回
json.NewEncoder(w).Encode(data)
}
正确做法:
// ✅ 正确:显式传递并检查 context
func goodHandler(w http.ResponseWriter, r *http.Request) {
ctx := r.Context()
data, err := db.QueryContext(ctx, "SELECT * FROM huge_table")
if err != nil {
if errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded) {
http.Error(w, "request canceled", http.StatusServiceUnavailable)
return
}
http.Error(w, err.Error(), http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(data)
}
注意:中间件、日志、鉴权等所有异步操作都得透传和检查 ctx,否则优雅关闭就是纸面流程。
最常被忽略的一点:第三方库(比如某些 ORM 或 RPC 客户端)可能内部忽略传入的 context,导致你写了 QueryContext 仍卡住。上线前务必用真实压测验证 shutdown 耗时是否可控。










