Go / 系统课时
用 Shutdown 做优雅退出
用 Shutdown 做优雅退出
HTTP 服务收到发布重启或 SIGTERM 时,直接结束进程会中断正在处理的请求。这里用 signal.NotifyContext 接收退出信号,再给 http.Server.Shutdown 一个明确的截止时间,让监听先停止、在途请求完成,超时后才强制关闭。
学习目标
- 说明
Shutdown对监听连接、空闲连接和在途请求分别做什么。 - 用操作系统信号触发带超时的优雅退出流程。
- 通过一个 3 秒请求验证进程不会在收到信号后立刻退出。
看懂 Shutdown 的退出顺序
Server.Shutdown(ctx) 会先关闭监听器,阻止新连接进入;随后关闭空闲连接,并等待活动连接回到空闲状态。它不会等待到无限久,而是受传入 context 控制。若 context 到期仍有处理中的请求,Shutdown 返回该 context 的错误,此时可以调用 Server.Close() 强制收尾。
生产环境常把优雅退出预算设为 10~30 秒,并确保小于编排平台给进程的总终止宽限期。例如平台只给 30 秒,就不要把 Shutdown context 也设成 30 秒;可以给应用 20 秒,为日志刷新和强制关闭留余量。

实现可运行的优雅退出服务
下面示例适用于 Go 1.20+ 的 Linux/macOS 服务进程。/work 固定处理 3 秒,方便验证收到中断信号后仍会把已进入的请求处理完。ReadHeaderTimeout=5s 还避免客户端长时间不完整发送请求头。
package main
import (
"context"
"errors"
"fmt"
"log"
"net/http"
"os"
"os/signal"
"syscall"
"time"
)
func main() {
mux := http.NewServeMux()
mux.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
log.Println("work started")
time.Sleep(3 * time.Second)
fmt.Fprintln(w, "done")
log.Println("work finished")
})
server := &http.Server{
Addr: ":8080",
Handler: mux,
ReadHeaderTimeout: 5 * time.Second,
}
runErr := make(chan error, 1)
go func() {
log.Println("listening on :8080")
if err := server.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
runErr <- err
}
}()
signalCtx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
select {
case err := <-runErr:
log.Fatalf("server failed: %v", err)
case <-signalCtx.Done():
log.Println("shutdown signal received")
}
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
if err := server.Shutdown(shutdownCtx); err != nil {
log.Printf("graceful shutdown failed: %v; forcing close", err)
if closeErr := server.Close(); closeErr != nil {
log.Printf("force close failed: %v", closeErr)
}
}
log.Println("server stopped")
}预期输出
<TIME> listening on :8080日志前缀中的 <TIME> 由 log 包在运行时生成,实际值会不同。若 8080 已被占用,ListenAndServe 会返回监听错误,程序会通过 runErr 结束,而不是进入假成功状态。
用在途请求验证退出行为
先运行服务,再从第二个终端请求 /work。在请求发出后、3 秒结束前,回到运行服务的终端按 Ctrl+C。如果服务部署在 Linux 容器中,也可以由编排平台发送 SIGTERM。
go run main.go预期输出
<TIME> listening on :8080第二个终端执行:
curl -i http://127.0.0.1:8080/work预期输出
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: <TIME>
Content-Length: 5
done服务端在这次请求期间收到 Ctrl+C 后,日志顺序应保持“先收到退出信号,再等工作完成,最后停止服务”:
<TIME> work started
<TIME> shutdown signal received
<TIME> work finished
<TIME> server stoppedDate 和日志时间中的 <TIME> 是动态值。关键验收点不是具体时间,而是 work finished 出现在 server stopped 之前,且客户端仍得到完整的 200 响应。
处理超时和强制关闭边界
把示例中的 /work 睡眠改成 15 秒,同时保留 Shutdown 的 10 秒截止时间,就会走失败分支。Shutdown 返回 context deadline exceeded,示例随后调用 Server.Close(),活动连接会被强制关闭,客户端可能看到连接被中断而不是完整响应。
如果程序还有后台任务,常见顺序是:先停止接收新流量,再 Shutdown HTTP Server,接着停止消费者与定时任务,最后关闭数据库和日志输出。不要在收到信号后直接 os.Exit,因为它不会运行 defer,也不给在途请求任何完成机会。
在容器或 systemd 中验收时,至少检查三件事:退出信号后端口不再接受新连接、已经进入 handler 的短请求能完成、超过退出预算的长请求最终会被强制结束。这样才能确认“优雅退出”不是只打印了一条 shutdown 日志。