Golang微服务优雅关闭详解

Golang微服务的优雅关闭绝非简单接收SIGTERM后立即退出，而是要确保所有HTTP请求处理完毕、后台goroutine主动终止、数据库连接池彻底清空后才安全退出；其核心在于用统一的context.Context协调http.Server.Shutdown()、sql.DB.Close()及自定义goroutine的生命周期，避免因关闭顺序错误（如DB先关导致新请求失败）、超时缺失（如慢查询阻塞db.Close）或goroutine失控引发502错误、连接泄漏甚至进程卡死，真正实现“等活干完、还清资源”的可靠下线。

Go 服务收到 SIGTERM 后立即退出？不是优雅关闭

真正的优雅关闭，是让正在处理的 HTTP 请求跑完、后台 goroutine 收尾、数据库连接池清空后再退出。否则 SIGTERM 一来就杀进程，502 Bad Gateway 或数据库连接泄漏就是常态。

关键不在“关”，而在“等”——等正在跑的活干完，等资源还回去。Go 标准库的 http.Server.Shutdown() 就是干这个的，但它不自动等你自定义的 goroutine，也不管 sql.DB 的连接池是否真正空了。

• 必须显式调用 server.Shutdown()，不能只靠 server.Close()（后者会立刻中断活跃连接）
• Shutdown() 默认最多等 30 秒，超时后强制关闭，得根据业务请求最长耗时调大 context.WithTimeout()
• 数据库连接池不会因 Shutdown() 自动归还所有连接，得手动调 db.Close()，且它本身会阻塞直到所有连接归还或上下文超时

如何协调 HTTP Server、DB 连接池和自定义 goroutine 的关闭顺序

三者生命周期不同步：HTTP server 关闭后可能还有 goroutine 在往 DB 写日志；DB 关了，goroutine 却还在等响应。必须用一个统一的 context.Context 驱动全部退出流程。

推荐结构：主 goroutine 监听 SIGTERM → 触发 cancel 函数 → 所有组件监听同一 ctx.Done() 做清理 → 最后调 server.Shutdown() 和 db.Close()。

• 不要在 http.HandlerFunc 里启动无 context 管控的 goroutine，否则 shutdown 时无法感知它们是否结束
• db.Close() 必须在 server.Shutdown() 完成之后再调，否则新请求可能撞上正在关闭的连接池，报 "sql: database is closed"
• 自定义长期 goroutine（如消息消费）应定期检查 ctx.Err() == context.Canceled，并主动退出，别靠 panic 或 os.Exit

为什么 sql.DB.Close() 有时卡住？

它不是立刻释放资源，而是等所有被借出的 *sql.Conn 归还、所有正在执行的查询完成。如果某条查询卡死（比如慢 SQL、网络分区），db.Close() 就会一直 block，导致整个 shutdown 流程 hang 住。

• 上线前务必给 db.QueryContext()、db.ExecContext() 等传入带超时的 context，避免单个查询拖垮全局关闭
• 生产环境建议设置 db.SetConnMaxLifetime() 和 db.SetMaxOpenConns()，防止连接池积压旧连接
• 若发现 db.Close() 超时，可先调 db.PingContext() 检查连通性，再结合 pprof 查看 goroutine 堆栈，定位卡在哪条 query

信号监听与测试：本地验证优雅关闭是否真生效

本地用 kill -TERM $(pidof your-service) 测试最直接，但要注意：SIGTERM 可能被 shell 忽略，或进程未正确注册 signal handler。

• 必须用 signal.Notify() 显式监听 os.Interrupt 和 syscall.SIGTERM，别依赖框架默认行为
• 写个简单压测脚本，在 kill 前发 10 个 2 秒延迟的请求，观察是否全部返回 200，且进程退出前没打印 "http: Server closed" 以外的 panic 或 error
• 加一行 log.Printf("shutting down: %v", err) 在 server.Shutdown() 后，能快速区分是超时退出还是正常收尾

最易被忽略的是：数据库事务没 commit/rollback 就退出，或者 defer 里没覆盖所有错误路径。关机那一刻，没人替你补 commit。

好了，本文到此结束，带大家了解了《Golang微服务优雅关闭详解》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多Golang知识！