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 秒,为日志刷新和强制关闭留余量。

SIGTERM 到 HTTP Server Shutdown 的优雅退出时序

实现可运行的优雅退出服务

下面示例适用于 Go 1.20+ 的 Linux/macOS 服务进程。/work 固定处理 3 秒,方便验证收到中断信号后仍会把已进入的请求处理完。ReadHeaderTimeout=5s 还避免客户端长时间不完整发送请求头。

go
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")
}

预期输出

text
<TIME> listening on :8080

日志前缀中的 <TIME> 由 log 包在运行时生成,实际值会不同。若 8080 已被占用,ListenAndServe 会返回监听错误,程序会通过 runErr 结束,而不是进入假成功状态。

用在途请求验证退出行为

先运行服务,再从第二个终端请求 /work。在请求发出后、3 秒结束前,回到运行服务的终端按 Ctrl+C。如果服务部署在 Linux 容器中,也可以由编排平台发送 SIGTERM。

bash
go run main.go

预期输出

text
<TIME> listening on :8080

第二个终端执行:

bash
curl -i http://127.0.0.1:8080/work

预期输出

text
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Date: <TIME>
Content-Length: 5

done

服务端在这次请求期间收到 Ctrl+C 后,日志顺序应保持“先收到退出信号,再等工作完成,最后停止服务”:

text
<TIME> work started
<TIME> shutdown signal received
<TIME> work finished
<TIME> server stopped

Date 和日志时间中的 <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 日志。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 Shutdown 做优雅退出

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通