Golang微服务下线保护避免请求丢失

在Golang微服务下线过程中，若未正确处理SIGTERM信号并实现优雅退出，极易导致正在处理的HTTP请求响应丢失、gRPC流中断或消息队列任务异常终止，尤其在Kubernetes环境中因preStop hook与Shutdown逻辑脱节而加剧问题；本文深入剖析了以http.Server.Shutdown()为核心、配合信号监听、合理超时（10–30秒）、context传播与goroutine协作的完整下线保护方案——强调“等什么”比“要不要等”更重要：必须等待活跃连接自然关闭、handler执行完毕及cleanup完成，同时指出Shutdown超时并非handler执行兜底机制，真正的可靠性依赖于每个handler内部对req.Context()的严格传递与deadline控制，为构建高可用Go微服务提供可落地的实践指南。

服务下线时 SIGTERM 信号处理不及时导致请求丢失

Go 进程收到 SIGTERM 后默认立即退出，但正在处理的 HTTP 请求可能还没写完响应、gRPC 流尚未关闭、或消息队列消费中的任务被中断。Kubernetes 的 preStop hook 若未配合优雅退出逻辑，容器会在几秒内被强制 kill，造成请求失败或数据不一致。

关键不是“要不要等”，而是“等什么”：必须等待活跃连接关闭、正在执行的 handler 返回、以及所有注册的 cleanup 函数完成。

• 用 http.Server.Shutdown() 替代直接调用 server.Close()，它会阻塞直到所有连接空闲或超时
• 在 main() 中监听 SIGTERM 和 SIGINT，触发 Shutdown()，不要忽略信号或仅用 os.Exit()
• 为 Shutdown() 设置合理超时（如 10–30 秒），太短起不到保护作用，太长拖慢滚动更新节奏
• 确保所有异步 goroutine（如定时上报、后台重试）都接受 context.Context 并在 Done() 时退出

HTTP Server Shutdown 超时设置与实际效果差异

http.Server.Shutdown() 的超时控制的是“等待已建立连接完全关闭”的最长时间，不是 handler 执行时间上限。如果某个 handler 卡死（比如数据库死锁、第三方 API 无响应），它不会被强制中断，整个 Shutdown() 就会卡住直到超时。

这意味着：超时值 ≠ 安全兜底，只是最后的“放弃等待”时间点。真正防卡死得靠 handler 内部的 context deadline。

• 所有 handler 必须使用传入的 req.Context()，并将其传递给下游调用（DB 查询、HTTP client、gRPC client）
• 在 Shutdown() 开始前，可主动关闭 listener（ln.Close()），阻止新连接接入，但已有连接仍可继续处理
• 检查日志中是否频繁出现 context deadline exceeded，这是 handler 未正确传播 context 的信号

srv := &http.Server{Addr: ":8080", Handler: mux}
go func() {
    if err := srv.ListenAndServe(); err != http.ErrServerClosed {
        log.Fatal(err)
    }
}()

// 收到信号后
sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, syscall.SIGTERM, syscall.SIGINT)
<-sigChan

ctx, cancel := context.WithTimeout(context.Background(), 15*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
    log.Printf("HTTP server shutdown error: %v", err)
}

gRPC Server 的 Graceful Stop 不等于 HTTP 的 Shutdown

grpc.Server.GracefulStop() 行为与 http.Server.Shutdown() 类似，但不自动管理 listener 生命周期，也不提供超时封装 —— 它只阻塞直到所有活跃 RPC 完成，没有内置 timeout。若客户端不结束流式调用或不发 status，它就永远等下去。

常见错误是只调用 GracefulStop() 却没关 listener，导致新连接仍能进来（尤其当 listener 复用 HTTP/2 端口时）。

• 必须先关闭 listener（ln.Close()），再调用 grpcServer.GracefulStop()
• 建议封装一个带超时的 stop 函数，用 time.AfterFunc 或 select 控制最大等待时间
• 对 streaming RPC，服务端需在收到 ctx.Done() 后主动 send error 并 break，不能只等客户端断开

Kubernetes preStop + readinessProbe 配合失效的典型场景

即使代码里做了优雅退出，K8s 层面配置不当也会让下线保护形同虚设。最常见的是：readinessProbe 延迟过长、preStop 时间短于 Shutdown 超时、或 probe 检查逻辑没覆盖真实流量路径。

例如：readinessProbe 每 10 秒检查一次，失败阈值是 3 次，那从服务开始拒绝新请求到 K8s 停止转发流量，最多延迟 30 秒 —— 这期间新请求仍会被打进来。

• readinessProbe.initialDelaySeconds 应 ≤ 5 秒，periodSeconds ≤ 3 秒，failureThreshold 设为 1
• preStop.exec.command 中 sleep 时间必须 ≥ 应用 Shutdown 超时（如应用设 15s，preStop 至少 sleep 20s）
• readinessProbe 的 endpoint 应返回当前是否允许新请求（例如检查 atomic.LoadUint32(&isShuttingDown)）

真正难处理的是长连接（WebSocket、gRPC stream）、异步回调、或依赖外部系统确认状态的场景 —— 这些没法靠简单超时解决，得靠业务层幂等 + 状态机驱动的下线流程。

今天带大家了解了的相关知识，希望对你有所帮助；关于Golang的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~