Go 服务优雅关闭与信号处理:context 传播、连接排水与最后请求保障
Go 服务的部署事故里,"关闭比启动更容易出事"是共识:K8s SIGTERM 后进程直接退出、在途请求被掐断、后台任务写了一半、消息确认丢失。Go 的并发原语让优雅关闭的实现不难但容易漏。本文给一套完整的关闭框架:信号处理、HTTP/DB/MQ 分层排水、超时兜底,以及"最后一条日志都别丢"的细节。
一、标准骨架:signal.NotifyContext + 分层 shutdown
func main() {
ctx, stop := signal.NotifyContext(context.Background(),
syscall.SIGTERM, syscall.SIGINT)
defer stop()
srv := newServer() // HTTP
wkr := newWorker() // 后台任务/消费者
go func() { log.Fatal(srv.ListenAndServe()) }()
go wkr.Run(ctx)
<-ctx.Done() // 收到信号
log.Println("shutdown signal received")
shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel() // K8s terminationGracePeriodSeconds 要 > 这个值
srv.Drain(shutdownCtx) // 1. HTTP:停收新请求 + 等在途
wkr.Stop(shutdownCtx) // 2. 任务:完成当前批 + 退订
db.Close() // 3. 资源:连接池/文件句柄最后关
log.Println("bye") // 4. 日志刷盘(见第六节)
}
顺序原则:入口先关(不再进新活)、执行层再排干、依赖资源最后释放。反序会让排水期间的新内部调用失败。
二、HTTP:Shutdown 的语义与连接池配合
http.Server.Shutdown(ctx) 关闭 listener、等待在途请求完成——两个常见误解:
- keep-alive 空闲连接也会被关(不会等它们复用),这是正确行为;
- 长连接/SSE/WebSocket 不会自己结束——必须在 handler 里监听
ctx.Done()主动收尾:
func streamHandler(w http.ResponseWriter, r *http.Request) {
flusher := w.(http.Flusher)
for {
select {
case <-r.Context().Done(): // Shutdown 时触发
return // SSE 循环必须靠这个退出
case ev := <-ticker.C:
fmt.Fprintf(w, "data: %v\n\n", ev)
flusher.Flush()
}
}
}
滚动发布的完整链条:LB 摘除(readiness 先失败)→ SIGTERM → Shutdown(25s) → 进程退出。K8s 里 preStop hook sleep 5 + readiness gate 给 LB 收敛窗口,缺这一段就会出现"pod 已 Terminating 但流量还在进"的零星 5xx。
三、消息消费者:先退订再排干
func (w *Worker) Stop(ctx context.Context) {
w.consumer.Close() // 1. 停止拉新消息(退订/停 poll)
w.wg.Wait() // 2. 等 in-flight handler 完成(wg 在 Handle 里 Add/Done)
select {
case <-ctx.Done():
w.flushOffsets() // 3. 超时兜底:未确认消息交还队列重投
default:
w.commitAll()
}
}
关键约束:处理中的消息要么完成要么显式不确认(让 broker 重投),绝不能"进程退了 offset 已提交但没处理完"——这是数据丢失的第一来源。Kafka/Redis Stream/RabbitMQ 的语义差异在关闭路径上要各自验证一次。
四、后台任务与定时器:ctx 取消 + 最后 flush
func (j *Job) run(ctx context.Context) {
t := time.NewTicker(j.interval)
defer t.Stop()
for {
select {
case <-ctx.Done():
j.flushPending(ctx) // 退出前把缓冲里的数据落库/落盘
return
case <-t.C:
j.process()
}
}
}
带本地缓冲的组件(批量写、指标上报、日志)都要有 flush-on-exit;time.AfterFunc 类一次性定时器同样挂进 WaitGroup 管理,否则关闭竞态下会 panic-in-panic。
五、超时与兜底:给关闭本身设死线
shutdownCtx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()
done := make(chan struct{})
go func() { srv.Drain(shutdownCtx); wkr.Stop(shutdownCtx); close(done) }()
select {
case <-done:
case <-time.After(28 * time.Second):
log.Println("forced exit") // 排水失败也要退出,交给编排层
os.Exit(1)
}
三层死线对齐:排水超时(25s) < terminationGracePeriodSeconds(30s) < 平台强杀。任何一环缺失,"优雅关闭"就退化成 SIGKILL。
六、别丢最后一条日志与退出码
- 缓冲式 logger(zap async、OTel batch span)必须
Sync()/Flush()后再退出——关闭日志本身要同步写 stderr; - 退出码语义化:0 = 正常排水完成;1 = 强制超时退出(监控可据此统计"不优雅率");
/debug/pprof/goroutine?debug=1在 SIGQUIT 时 dump——预发保留该习惯,生产用SIGTERM前主动 dump 一次 goroutine 数进日志。
七、测试:把关闭路径写进单测
func TestGracefulShutdown(t *testing.T) {
srv := newTestServer()
go srv.ListenAndServe()
// 发一个慢请求 + 立即 Shutdown,断言:请求完成、新请求被拒、无 panic
done := make(chan error, 1)
go func() { _, err := http.Get(srv.URL + "/slow"); done <- err }()
time.Sleep(50 * time.Millisecond)
ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
defer cancel()
if err := srv.Server.Shutdown(ctx); err != nil { t.Fatal(err) }
if err := <-done; err != nil { t.Fatalf("in-flight request killed: %v", err) }
}
关闭路径的 bug 只在真实信号下暴露,CI 里模拟 SIGTERM(syscall.Kill(os.Getpid(), syscall.SIGTERM))跑一次完整 main 流程是最便宜的保险。
小结
Go 优雅关闭的完整清单:signal.NotifyContext 接 SIGTERM → 入口先停(HTTP Shutdown + LB 摘除窗口)→ 消费者"退订-排干-兜底重投"三步 → 带缓冲组件 flush-on-exit → 排水超时 < 宽限期 < 强杀的三层死线对齐 → logger Sync 与语义化退出码。每一条都是几行代码,但缺任何一条都会在滚动发布时变成用户可见的 5xx 或静默数据丢失。把关闭测试写进 CI 后,这套骨架可以在所有 Go 服务间直接复制——它应该是脚手架的一部分,而不是每次事故后的补丁。
评论(0)
登录 后参与评论。