Golang优雅停机实现全解析

Go服务实现真正优雅停机的关键在于必须显式调用`http.Server.Shutdown()`并传入带超时的`context.Context`，而非依赖`ListenAndServe()`的默认阻塞行为——后者会无视SIGTERM导致进程被系统强杀、请求中断、日志截断；正确做法是将`ListenAndServe()`放入独立goroutine，配合带缓冲的信号通道监听SIGTERM，收到信号后先清理gRPC、数据库等外部资源，再触发Shutdown等待活跃请求自然完成，同时务必忽略`ErrServerClosed`这一正常退出信号，绝不可用`Close()`替代，否则将彻底破坏“优雅”本质。

Go 服务在 Kubernetes 或其他容器环境中收到 SIGTERM 后立刻退出，不是配置问题，而是没写 shutdown 逻辑——http.Server.Shutdown() 必须显式调用，且必须配带超时的 context.Context，否则所有“优雅”都是假象。

为什么 http.ListenAndServe() 不能直接用于优雅停机

它内部阻塞等待连接，不响应系统信号；一旦收到 SIGTERM，进程被 OS 强杀，正在处理的请求全中断。你看到的“秒退”“连接重置”“日志断在中间”，基本都源于此。

• 必须把 srv.ListenAndServe() 放进 goroutine，否则主 goroutine 卡死，后续信号监听、shutdown 调用全失效
• srv.ListenAndServe() 返回 http.ErrServerClosed 是正常退出信号，不是错误，要显式忽略
• 别用 srv.Close() 替代 —— 它会立即关闭 listener 并强制断开所有连接，和“优雅”完全相反

signal.Notify 后必须有接收动作，否则信号永远收不到

signal.Notify() 只是注册监听，不自动阻塞或触发逻辑。常见错误是调完就继续往下走，main 函数结束进程直接退出。

• 通道必须带缓冲：sigChan := make(chan os.Signal, 1)，否则快速连发两次 SIGTERM 会丢一次
• 必须显式接收信号：<-sigChan（单次）或 for range sigChan（持续），且该操作不能被其他阻塞逻辑挡住
• 只监听 syscall.SIGINT 和 syscall.SIGTERM，Kubernetes 默认发的是后者，os.Interrupt 在容器里无效

Shutdown() 不是万能的，它只等 handler 返回，不杀 goroutine

srv.Shutdown(ctx) 会拒绝新连接，并遍历当前活跃连接，等每个 handler 执行完毕（或 ctx 超时）。但它不管 handler 内部起了什么 goroutine，也不设 I/O 超时。

• handler 里用了 time.Sleep(5 * time.Second)？必须改用 select { case <-time.After(5 * time.Second): ... case <-ctx.Done(): return }
• DB 查询写了 db.QueryRow("...")？得换成 db.QueryRowContext(req.Context(), "...")
• 起了无 context 约束的 goroutine，比如 go sendToKafka(data)？应包装为 go func() { select { case <-ctx.Done(): return; default: sendToKafka(data) } }()
• 没设 srv.ReadTimeout/WriteTimeout，慢连接可能永远 hang 住，导致 Shutdown 卡死

HTTP 之外的资源必须手动清理，顺序不能错

http.Server.Shutdown() 只管 HTTP 连接层。gRPC、WebSocket、DB、Redis、Kafka 消费者等，全得你自己关，且顺序影响数据一致性。

• 先停业务入口：调 grpcServer.GracefulStop()（不是 Stop()），再调 httpServer.Shutdown(ctx)
• 再关依赖资源：db.Close() 必须在所有 DB 查询 handler 返回后调，否则可能丢事务；redisClient.Close() 同理
• 消息消费者（如 sarama）：先 consumer.Stop() 停拉取，再等当前 handler 完成，最后 consumer.Close()
• 长连接（WebSocket/SSE）：http.Server.Shutdown() 不感知它们，得自己维护连接 map，收到 shutdown 信号后遍历 conn.Close()

最常被忽略的一点：所有后台 goroutine（指标上报、心跳、定时任务）都必须监听同一个 ctx.Done()，且不能靠 defer 或 os.Exit() 强退——它们会跳过 cleanup，导致连接泄漏、数据写半截、日志丢失。真正的优雅，藏在每一个 handler 的 select 里，不在启动脚本或 preStop 钩子里。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Golang优雅停机实现全解析》文章吧，也可关注golang学习网公众号了解相关技术文章。