Go环境配置错误导致go version失败是优雅停机的前提障碍；必须先验证which go、go env GOPATH/GOROOT及go mod init成功，再用http.Server.Shutdown()替代阻塞式ListenAndServe，并在goroutine中运行以响应信号。
Go 环境装不对，go version 都跑不起来，优雅停机根本无从谈起；而停机逻辑写错一行，比如用 server.Close() 代替 server.Shutdown()，就会导致上传中断、SSE 断连、gRPC 客户端收到 UNAVAILABLE 却服务端无日志——这不是“优雅”，是拔网线。
验证 go 命令是否真可用
很多人卡在第一步：终端敲 go version 报 command not found。这不是 Go 没装，是 PATH 没生效。
- macOS / Linux：运行
which go，没输出就检查/usr/local/go/bin或你自定义的安装路径是否加进~/.zshrc（或~/.bash_profile）的PATH里，改完记得source ~/.zshrc - Windows：PowerShell 里运行
Get-Command go；若失败，去「系统属性 → 高级 → 环境变量」确认 Go 的bin目录进了用户或系统PATH；别信安装器勾选的“添加到 PATH”，重启终端才生效 - 装完务必验证：
go env GOPATH和go env GOROOT应有合理输出；go mod init example.com/app能成功生成go.mod才算过关
用 http.Server.Shutdown() 替代 ListenAndServe
router.Run()（Gin）或 http.ListenAndServe() 是阻塞式启动，收不到信号就直接退出。必须显式构造 http.Server 实例，才能调 Shutdown()。
- 把
srv.ListenAndServe()放进 goroutine，否则主 goroutine 卡死，永远等不到信号 - 监听信号必须用带缓冲的 channel：
sigChan := make(chan os.Signal, 1)，否则第一个SIGTERM可能丢失 - 只监听
os.Interrupt（Ctrl+C）和syscall.SIGTERM（K8s 删除 Pod），别加SIGHUP等无关信号 - 关键示例片段：
srv := &http.Server{Addr: ":8080", Handler: router}
go func() {
if err := srv.ListenAndServe(); err != nil && err != http.ErrServerClosed {
log.Fatal(err)
}
}()
<p>sigChan := make(chan os.Signal, 1)
signal.Notify(sigChan, os.Interrupt, syscall.SIGTERM)
<-sigChan</p><p>ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
defer cancel()
if err := srv.Shutdown(ctx); err != nil {
log.Printf("server shutdown error: %v", err)
}超时时间必须比 K8s terminationGracePeriodSeconds 小 5–10 秒
K8s 默认给容器 30 秒宽限期（terminationGracePeriodSeconds），你的 context.WithTimeout 必须更短，否则 K8s 在超时后发 SIGKILL 强杀，清理逻辑根本跑不完。
立即学习“go语言免费学习笔记（深入）”；
- 若 K8s 配了
terminationGracePeriodSeconds: 30，代码里最多设25 * time.Second - 传
context.Background()或没设 deadline 的context.WithCancel()，等于让进程无限等待，必然卡死 -
srv.Shutdown()返回context.DeadlineExceeded很常见，说明有 handler 卡住没响应 ctx —— 此时记录日志即可，不要 panic，更不能 fallback 到srv.Close() - 调完
srv.Shutdown()后必须立刻cancel()，否则 context 泄漏，goroutine 持续监听ctx.Done()
HTTP 之外的资源必须手动关，且顺序不能反
srv.Shutdown() 只管 HTTP 连接层，DB、Redis、gRPC、WebSocket、后台 ticker 全得你亲手关。漏一个，进程就卡住；顺序错一个，可能 panic 或丢数据。
- 关闭顺序必须反向依赖：先停 Kafka/Sarama 消费者（不再拉新消息），再等 DB 连接池空闲（可先
db.SetMaxOpenConns(1)加速归还），最后关 HTTP server -
*sql.DB.Close()是阻塞操作，确保此前已无新查询发起，否则会一直等 - gRPC server 用
grpcServer.GracefulStop()（不是Stop()）；它不等流式 RPC 完成，需业务层配合超时 - WebSocket 连接不会被
Shutdown()自动等待，得自己用sync.Map维护存活连接，收到 shutdown 信号后遍历调conn.Close() - 所有长期 goroutine（如 metrics 上报）必须监听统一
ctx.Done()，不能用time.Sleep硬等
真正容易被忽略的点是：Shutdown 不会自动关闭监听套接字，它只协调连接层面的 graceful 结束；而监听器关闭由 ListenAndServe 返回 http.ErrServerClosed 触发——所以主 goroutine 必须捕获这个错误并退出，否则整个流程就断在那儿了。
