Go / 系统课时
实现优雅停机
实现优雅停机
优雅停机要解决的是“收到终止信号后不再接收新流量,同时给在途请求留出有限完成时间”。本节用 http.Server.Shutdown 串起信号捕获、停止监听、请求清空与超时兜底,形成可直接运行的停机流程。
学习目标
- 使用系统信号触发 HTTP 服务的有序关闭
- 为
Server.Shutdown设置 deadline,并正确处理超时 - 识别优雅停机对长连接和强制退出的边界
停机流程如何推进
收到 SIGINT 或 SIGTERM 后,不应直接结束进程。先调用 Shutdown:它会关闭监听器,使新连接无法进入;空闲连接会被关闭;已经进入处理器的请求继续执行,直到完成或停机上下文到期。

deadline 的作用不是让 Shutdown 自己“更快”,而是给等待过程设置上限。若超时仍有连接未结束,Shutdown 返回上下文错误;此时可以调用 Close 作为兜底,接受未完成请求会被中断这一结果。
实现信号驱动的 Shutdown
下面的程序提供 /work 接口模拟一个 2 秒请求。ListenAndServe 放在单独 goroutine 中运行,主 goroutine 等待系统信号;收到信号后创建 5 秒停机上下文,并在超时时调用 Close。
package main
import (
"context"
"errors"
"fmt"
"log"
"net/http"
"os/signal"
"syscall"
"time"
)
func main() {
log.SetFlags(0)
mux := http.NewServeMux()
mux.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
// 模拟已经进入服务端的在途请求。
time.Sleep(2 * time.Second)
fmt.Fprintln(w, "work finished")
})
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
}
sigCtx, stop := signal.NotifyContext(
context.Background(),
syscall.SIGINT,
syscall.SIGTERM,
)
defer stop()
serveErr := make(chan error, 1)
go func() {
log.Println("server listening on :8080")
serveErr <- srv.ListenAndServe()
}()
select {
case err := <-serveErr:
if !errors.Is(err, http.ErrServerClosed) {
log.Fatalf("serve failed: %v", err)
}
return
case <-sigCtx.Done():
log.Println("shutdown signal received")
}
shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
log.Printf("graceful shutdown failed: %v", err)
// deadline 已耗尽时,用 Close 中断残留连接,避免无限等待。
if closeErr := srv.Close(); closeErr != nil {
log.Printf("force close failed: %v", closeErr)
}
return
}
log.Println("server stopped gracefully")
}预期结果:保存为 main.go,执行 go run main.go,再按 Ctrl+C。如果没有超过 5 秒的在途请求,可看到:
server listening on :8080
shutdown signal received
server stopped gracefully如果信号到来时 /work 正在执行,Shutdown 会等待它返回;输出仍以 server stopped gracefully 结束,只是退出会延后到请求处理完成。端口、信号送达时刻和请求完成时刻取决于本机环境。
处理超时与长连接边界
停机超时应根据请求最长合理耗时和部署平台的终止宽限期共同决定。deadline 太短会把正常请求强制切断;过长则会拖慢发布和故障恢复。业务处理器还应有自己的请求级超时,不能把进程停机 deadline 当作普通请求的超时控制。
Shutdown 不会替你管理被 hijack 的连接,例如 WebSocket。此类连接已经脱离常规 HTTP 请求生命周期,需要单独广播“服务即将关闭”的信号,并等待连接管理器自行收尾。否则 HTTP 请求已经清空,进程仍可能因为长连接或后台 goroutine 无法退出。
验证停机是否真的优雅
验证时应同时观察“新请求”和“旧请求”。先发起一个持续 2 秒的 /work 请求,在它尚未返回时发送终止信号;旧请求应正常得到 work finished,而监听关闭后发起的新连接应失败。这样才能证明服务不是“收到信号就退出”,而是先停止接流量,再等待已接收的工作完成。
最终要保证的不是永远等待,而是在明确时间预算内尽量完成在途请求,并在预算耗尽时可控地结束进程。