平滑下线是进程退出前必须执行的强制流程，须严格按顺序反注册consul、shutdown http、gracefulstop grpc、关闭db/kafka等组件，否则必然导致幽灵实例、连接中断和重复消费。
平滑下线不是“最好有”，而是进程退出前必须执行的强制流程；跳过 Consul 反注册、乱序关闭或忽略 gRPC/DB 等组件，必然产生幽灵实例、连接中断和重复消费。
Consul 反注册必须在 Shutdown HTTP 前完成
Consul 不会自动感知进程退出，反注册失败会导致服务列表里残留已死实例，下游持续转发请求过去。顺序错了——比如先 srv.Shutdown() 再调 client.Agent().ServiceDeregister()——就可能因网络抖动导致 deregister 请求发不出去，而 HTTP server 已停，流量彻底丢失。
- 用
signal.Notify监听syscall.SIGTERM和syscall.SIGINT，仅注册一次 - 反注册必须带重试：最多 3 次，每次间隔 200ms，超时设为 1.5s（
client.Config.HttpClient.Timeout = 1500 * time.Millisecond） - 反注册成功后，
time.Sleep(200 * time.Millisecond)，给 Consul 集群状态广播留出缓冲时间 - 若 deregister 返回非
nilerror，只打log.Error，不 panic，继续走 shutdown 流程
http.Server.Shutdown() 只是起点，不是终点
srv.Shutdown() 仅终止 HTTP 连接生命周期，对 gRPC、Kafka 消费者、定时任务、WebSocket 管理器完全无效。若只关 HTTP，gRPC server 仍在收流、消费者还在拉消息，等于“半关机”。
初始化并管理阿里云SDK Go 客户端，涵盖 sync.Once 单例、goroutine 安全、endpoint 与 region 配置、VPC 端点及调试。
-
srv.Shutdown()必须在 goroutine 中调用，否则阻塞主流程，后续清理逻辑无法执行 - gRPC server 要显式调用
grpcServer.GracefulStop()，Stop()会立即断连，等同于 kill -9 - Kafka 消费者（如 sarama）需调
consumer.Close()，并确认ConsumePartition循环已退出 - 所有后台 goroutine 必须通过
context.Context控制，shutdown 前调cancel()，goroutine 内部检测ctx.Done()后自行退出
DB.Close() 和资源清理的隐藏陷阱
db.Close() 是阻塞调用，但它只等 idle 连接归还，不等正在执行的 query。如果 handler 还在跑 SQL，db.Close() 就会卡住，甚至引发 panic。
- 确保所有 HTTP handler 已进入 shutdown 状态（例如用
sync.WaitGroup+ 中间件计数活跃请求数），不再发起新 DB 查询 -
db.Close()应放在srv.Shutdown()之后、grpcServer.GracefulStop()之后，但早于os.Exit(0) - 若使用连接池（如 pgxpool），调用
pool.Close()，它内部已做等待逻辑，比 raw*sql.DB更可靠 - 避免 defer 注册注销逻辑——panic 时 defer 可能不执行，必须绑定到信号处理路径中
K8s preStop + terminationGracePeriodSeconds 必须配齐
K8s 默认发 SIGTERM 到容器主进程，但若 terminationGracePeriodSeconds 小于实际 shutdown 耗时，kubelet 会在你还没 deregister 完就发 SIGKILL，直接回退到 kill -9。
-
terminationGracePeriodSeconds至少设为 45 秒：预留 5s 反注册重试 + 15s HTTP shutdown + 10s gRPC/DB 清理 + 15s 容错缓冲 -
preStophook 不必写 shell 脚本，Go 进程自己监听信号即可；但要确认容器内无其他进程劫持信号 - 本地调试用
Ctrl+C触发SIGINT，行为应与 K8sSIGTERM完全一致，避免环境差异导致线上故障 - 在日志里打上明确标记，如
"[shutdown] step: deregister consul → shutdown http → graceful stop grpc → close db"，便于 trace 实际执行路径
最常被跳过的其实是反注册后的那 200ms sleep 和 gRPC 的 GracefulStop() —— 它们不报错、不 panic，但会让下游多承受几秒错误请求，且问题难以复现。别依赖“应该没问题”，每个环节都得有显式控制和可验证的日志。
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
