Go / 系统课时
优雅停止 HTTP 服务
优雅停止 HTTP 服务
HTTP 服务退出时,真正要解决的不是“把进程停掉”,而是停止接收新连接,同时给正在处理的请求一个完成窗口。本节用 Go 标准库实现信号监听、Shutdown、超时控制与验证流程,避免发布或缩容时把正常请求直接截断。
学习目标
- 理解
http.Server.Shutdown在停止监听、处理空闲连接和等待活动请求时的行为 - 使用
signal.NotifyContext接收SIGINT与SIGTERM,把退出流程集中到主协程 - 为优雅停止设置明确超时,并验证在途请求会在进程退出前完成
Shutdown 到底会做什么
Shutdown 不是立即杀死连接。调用后,http.Server 会先关闭监听器,让新的 TCP 连接无法再进入;随后关闭空闲连接,并等待正在处理请求的连接回到空闲状态。只要这些活动请求在给定上下文到期前结束,Shutdown 就会返回 nil。
这与 Server.Close 不同:Close 会直接关闭当前连接,更适合无法继续等待时的兜底动作。正常发布、滚动升级和进程退出,应优先走 Shutdown,并由超时决定最多等待多久。

用标准库实现退出流程
下面的服务提供一个耗时 3 秒的 /slow 请求,用来观察停止过程。关键点是:信号上下文只负责“收到退出通知”,真正传给 Shutdown 的超时上下文要从新的 context.Background() 创建,因为信号上下文此时已经取消。
将代码保存为 main.go,执行 go run main.go。服务启动后访问 http://localhost:8080/slow,并在 3 秒内按 Ctrl+C;如果信号在请求处理中到达,就能看到等待行为。
package main
import (
"context"
"errors"
"log"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
log.SetFlags(0)
mux := http.NewServeMux()
mux.HandleFunc("/slow", func(w http.ResponseWriter, r *http.Request) {
log.Println("request started")
time.Sleep(3 * time.Second)
_, _ = w.Write([]byte("ok\n"))
log.Println("request finished")
})
srv := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
}
errCh := make(chan error, 1)
go func() {
log.Println("server started at :8080")
errCh <- srv.ListenAndServe()
}()
signalCtx, stop := signal.NotifyContext(
context.Background(),
os.Interrupt,
syscall.SIGTERM,
)
defer stop()
select {
case err := <-errCh:
if err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatalf("listen failed: %v", err)
}
return
case <-signalCtx.Done():
log.Println("shutdown signal received")
}
// 信号上下文已经取消,因此为 Shutdown 单独创建等待窗口。
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := srv.Shutdown(shutdownCtx); err != nil {
log.Fatalf("graceful shutdown failed: %v", err)
}
if err := <-errCh; err != nil && !errors.Is(err, http.ErrServerClosed) {
log.Fatalf("server stopped unexpectedly: %v", err)
}
log.Println("server stopped gracefully")
}预期结果
server started at :8080
request started
shutdown signal received
request finished
server stopped gracefully这里最重要的顺序是 request finished 出现在 server stopped gracefully 之前。日志没有时间戳是因为示例关闭了默认时间前缀;真实服务可以保留结构化时间字段。
生产环境还要补两层保护
优雅停止时间必须有上限。如果某个 handler 永远不返回,Shutdown 会在超时上下文到期后返回错误;此时进程可以记录失败并执行更强的兜底退出,而不是无限等待。超时时间应覆盖业务请求的正常尾延迟,而不是随意设成很大的值。
如果服务前面还有负载均衡器或 Kubernetes,通常要先让实例从流量入口摘除,再调用 Shutdown。这是因为外部流量发现状态传播需要时间,只关闭本地监听器可能让少量新请求在切换窗口内继续被路由到即将退出的实例。
验证是否真的优雅
验证时不要只看“进程能退出”,而要看退出期间请求是否被正确处理。至少检查三件事:信号到达后不再接受新连接;已经进入 handler 的请求能在超时前完成;超时路径能被日志和监控观察到。
当这三点都成立,服务才具备可预测的停止边界。这样发布、扩缩容或宿主机重启时,HTTP 层不会把正常的在途请求无声地截断。