Go HTTP 服务优雅停机实战：信号处理、摘流和超时关闭

线上服务发布时，最怕“进程停了，请求还没处理完”。如果直接退出，正在上传、下单、写日志的请求可能被中断；如果一直等，又会拖慢发布。Go 的 HTTP 服务本身提供了 `Shutdown` 能力，关键是要把信号处理、健康检查摘流、超时关闭和后台任务收尾串成一条稳定流程。

适合人群：已经会写 Go HTTP 接口，正在把服务部署到 Docker、Kubernetes、systemd 或自研发布平台的同学。本文示例只依赖标准库，拿过去就能改。

目录

• 为什么直接退出会丢请求
• 优雅停机的完整流程
• 一份可运行的 Go 示例
• 后台任务如何一起收尾
• 上线检查和常见坑

一、为什么直接退出会丢请求

一个 HTTP 服务正在处理请求时，进程如果马上结束，客户端看到的可能是连接断开、网关 502、业务状态不一致。尤其是下面几类接口，更容易受到影响：

• 请求耗时较长：导入、导出、文件上传、聚合查询。
• 写入链路较长：先写数据库，再发消息，再刷新缓存。
• 调用外部依赖：短信、支付、对象存储、第三方接口。

优雅停机的目标不是“无限等待”，而是在一个可控窗口内完成三件事：不再接新流量、已有请求尽量跑完、超时后明确结束。这样发布系统不会卡住，用户请求也不会被随意切断。

二、优雅停机的完整流程

推荐把停机流程拆成四步：收到系统信号后先把 readiness 标记为不可用，让负载均衡停止转发新请求；等待一个很短的摘流窗口；调用 `http.Server.Shutdown` 等待已有连接完成；最后关闭后台任务和资源连接。

这条链路里最容易漏掉的是摘流窗口。很多平台把服务标记为不可用后，还需要几秒钟把路由表、连接池、网关缓存同步完。如果刚收到信号就立刻关闭监听，仍然可能有少量请求打过来。

三、一份可运行的 Go 示例

下面这份示例包含三个接口：`/healthz` 用于健康检查，`/work` 模拟一个慢请求，`/` 返回普通响应。收到 SIGINT 或 SIGTERM 后，服务会先把健康检查置为失败，再等待 3 秒摘流，然后最多等待 20 秒让已有请求完成。

package main

import (
    "context"
    "errors"
    "fmt"
    "log"
    "net/http"
    "os/signal"
    "sync/atomic"
    "syscall"
    "time"
)

func main() {
    var shuttingDown atomic.Bool

    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        if shuttingDown.Load() {
            http.Error(w, "shutting down", http.StatusServiceUnavailable)
            return
        }
        _, _ = w.Write([]byte("ok"))
    })

    mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
        _, _ = w.Write([]byte("hello 17golang"))
    })

    mux.HandleFunc("/work", func(w http.ResponseWriter, r *http.Request) {
        select {
        case 

可以用两个终端验证效果：一个终端启动服务，另一个终端请求 `/work`，再给服务发送 SIGTERM。只要慢请求能在超时窗口内完成，`Shutdown` 会等它返回；如果超过窗口，服务会按设置结束。

四、后台任务如何一起收尾

很多服务不只有 HTTP 请求，还会有定时任务、消费任务、缓冲日志、数据库连接池。建议把这些资源都挂在同一个生命周期里：主上下文取消后，先停止接收新任务，再等待正在处理的任务结束，最后关闭连接。

type WorkerGroup struct {
    stop chan struct{}
    done chan struct{}
}

func NewWorkerGroup() *WorkerGroup {
    return &WorkerGroup{
        stop: make(chan struct{}),
        done: make(chan struct{}),
    }
}

func (g *WorkerGroup) Start() {
    go func() {
        defer close(g.done)
        ticker := time.NewTicker(2 * time.Second)
        defer ticker.Stop()

        for {
            select {
            case 

在主流程里，`srv.Shutdown` 完成后继续调用 `workers.Stop(closeCtx)`。这样 HTTP 连接和后台任务共用同一个关闭预算，发布平台看到的停机时间也更可控。

五、上线检查和常见坑

1. 不要把摘流等待设得太久

摘流窗口通常 2 到 5 秒就够了。它不是等待请求完成的时间，只是给网关、负载均衡或服务发现一点同步时间。真正等待请求完成的是 `Shutdown` 的超时上下文。

2. 慢请求要尊重请求上下文

业务代码里调用数据库、缓存、外部接口时，尽量传入 `r.Context()`。当客户端断开或服务停机时，下游操作才能及时停止，避免无意义地占用连接。

3. 健康检查要区分存活和可接流量

有些平台会区分 liveness 和 readiness。停机阶段通常应该先让 readiness 失败，但不要马上让 liveness 失败，否则平台可能认为进程异常并强制结束。

4. 本地验证命令

go run main.go
curl http://127.0.0.1:8080/work
kill -TERM $(pgrep -f "go run main.go")

验证时重点看三点：信号到达后 `/healthz` 是否变成 503；已有 `/work` 请求是否能在超时内返回；超过超时窗口时服务是否能明确退出。

总结

Go HTTP 服务优雅停机可以按一条固定路径实现：收到信号、标记不可接流量、短暂摘流、调用 `Shutdown`、收尾后台任务。这个流程不复杂，但能显著减少发布和重启时的请求中断，也能让服务在容器和编排平台里表现得更稳定。