Go 语言 HTTP 服务的优雅关机与超时控制：从原理到可运行示例

在生产环境里，一个 HTTP 服务最常见的退出方式不是优雅的，而是粗暴的：收到终止信号后进程直接退出，正在处理的请求被中途打断，客户端收到连接重置，正在写入数据库的操作也可能只完成一半。Go 语言标准库的 net/http 包已经内置了优雅关机能力，配合信号处理和合理的超时设置，我们可以在不丢弃在途请求的前提下，让服务平稳地停下来。本文从原理讲起，再给出一份可以直接运行的完整示例，最后列出实践中容易踩的坑。

一、什么是优雅关机

优雅关机是指服务收到停止信号后，不再接受新的连接，但会等待已经建立的连接把正在处理的请求完成，然后再退出进程。这个过程有三个关键点。第一，停止监听：不再接受新连接，避免新的工作进入系统。第二，等待在途请求：已经开始处理的请求继续执行，直到完成或者达到关机超时上限。第三，释放资源：请求处理完之后，再按顺序关闭数据库连接池、消息队列消费者、后台定时任务等资源。

Go 的 http.Server 提供了两个名字相近但行为完全不同的方法。Close 方法会立即关闭所有活动连接，正在处理的请求会被强制中断。Shutdown 方法则先关闭监听器，等待在途请求完成，超时后才强制关闭。它接受一个 context.Context 参数，这个上下文的超时时间就是我们愿意等待在途请求的最长时间。如果上下文超时时仍有请求没有完成，Shutdown 会返回上下文的错误，进程应当记录日志并退出，而不是无限期等待。

二、信号从哪里来

在 Linux 环境中，部署工具和容器编排系统通常用信号通知进程停止。手动按 Ctrl+C 会发送 SIGINT 信号，Kubernetes 删除 Pod 时会先发送 SIGTERM 信号，等待一段时间后才发送 SIGKILL 强制杀死进程。SIGKILL 是无法捕获和处理的，所以优雅关机必须在 SIGINT 和 SIGTERM 阶段完成。Go 标准库的 os/signal 包可以把信号转成通道事件，signal.NotifyContext 更进一步，把信号和 context.Context 结合起来：收到信号时上下文被取消，主流程只要等待上下文完成，就可以开始关机。

需要注意的是，开发环境中直接用编辑器或调试器停止进程，有时发送的不是上述信号，或者直接杀死了进程组，优雅关机的代码就不会被执行。验证优雅关机时，应当在终端里用 kill 命令发送 SIGTERM，或者按 Ctrl+C 触发 SIGINT，而不是依赖工具的停止按钮。

三、超时设置：四种超时各管什么

只有关机逻辑而没有超时设置，服务仍然可能被一个慢请求拖住。http.Server 提供了四个常用的超时字段，含义各不相同。ReadTimeout 限制从建立连接到读完整个请求所用的时间，包含请求体。ReadHeaderTimeout 只限制读请求头的时间，它可以比 ReadTimeout 更短，用来尽早拒绝只发一半请求头的慢速连接。WriteTimeout 限制从读完请求头到写完响应的时间，包含处理业务逻辑的时间，所以它不能设得比业务正常耗时还短。IdleTimeout 限制空闲的长连接保持时间，超过后服务器会关闭连接，释放文件描述符。

这四个超时如果全部留空，服务器会一直等待，慢连接会长期占用资源。如果设得太小，正常的上传、大文件下载和耗时查询都会被误杀。一个常见的起点是：请求头超时 2 秒，读超时 5 秒，写超时 10 秒，空闲超时 60 秒，再根据接口的实际耗时分布调整。对于文件上传和导出接口，应当单独用中间件设置更宽松的超时，而不是把全局写超时放得很大。

四、完整可运行示例

下面是一份可以直接保存为 main.go 并用 go run 运行的示例。它监听 8080 端口，提供健康检查接口和一个模拟慢处理的接口，收到 SIGINT 或 SIGTERM 后等待最多 10 秒让在途请求完成。

package main

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

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/healthz", func(w http.ResponseWriter, r *http.Request) {
        w.WriteHeader(http.StatusOK)
        _, _ = w.Write([]byte("ok"))
    })
    mux.HandleFunc("/slow", func(w http.ResponseWriter, r *http.Request) {
        select {
        case <-time.After(5 * time.Second):
            _, _ = w.Write([]byte("done"))
        case <-r.Context().Done():
            log.Println("客户端已断开或服务正在关机，停止处理 /slow")
        }
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadTimeout:       5 * time.Second,
        ReadHeaderTimeout: 2 * time.Second,
        WriteTimeout:      10 * time.Second,
        IdleTimeout:       60 * time.Second,
    }

    go func() {
        log.Println("服务启动，监听 :8080")
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            log.Fatalf("服务启动失败：%v", err)
        }
    }()

    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stop()
    <-ctx.Done()
    log.Println("收到停止信号，开始优雅关机")

    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
    defer cancel()
    if err := srv.Shutdown(shutdownCtx); err != nil {
        log.Printf("优雅关机未在 10 秒内完成：%v", err)
    }
    log.Println("服务已停止")
}

这份代码有几个细节值得注意。ListenAndServe 必须放在单独的 goroutine 里运行，否则主流程会被阻塞，收不到信号。关机后 ListenAndServe 会返回 http.ErrServerClosed，这不是错误，而是正常关机的标志，必须单独判断，不能把它当成启动失败。处理函数里监听 r.Context().Done()，可以在客户端断开或者关机超时后及时停止工作，避免对已经没有人等待的结果继续消耗资源。

五、在途请求与资源关闭的顺序

优雅关机不是只调用一次 Shutdown 就结束了，资源关闭的顺序同样重要。正确的顺序一般是：先让负载均衡器把实例从后端列表中摘除，停止把新流量分发过来；然后调用 Shutdown，等待在途请求完成；接着关闭数据库连接池、缓存客户端和消息生产者；最后退出进程。如果顺序反过来，先关闭数据库连接池，再等待请求完成，那么在途请求在访问数据库时就会失败，优雅关机也就失去了意义。

对于后台 goroutine，例如定时清理任务和消息消费者，应当用 sync.WaitGroup 跟踪它们的生命周期，在关机时先通知它们停止接受新任务，等待它们处理完手头的工作后再退出。如果后台任务本身也需要调用数据库或者外部接口，同样要把请求上下文或者关机上下文传进去，让它们能够感知取消信号，而不是在关机时被强行丢弃。

六、验证方法

验证优雅关机需要两个终端。先在一个终端运行服务，在另一个终端用 curl 请求本地 8080 端口的 /slow 接口。在请求还没有返回时，在服务终端按 Ctrl+C，观察慢请求是否仍然返回了 done，而不是连接被重置。再用 kill 命令发送 SIGTERM 重复一次，确认两种信号都能触发关机。还可以用 curl 的 --max-time 参数验证写超时：把 WriteTimeout 临时改小，请求一个耗时超过写超时的接口，确认服务器会主动断开连接，而不是无限等待。

健康检查接口也应当纳入验证。关机开始后，服务不再接受新连接，健康检查应当失败，负载均衡器据此把实例摘除。如果健康检查在关机过程中仍然返回成功，新的流量就可能继续被分发到正在退出的实例上。实际部署时，还要留出足够的时间窗口：Kubernetes 的 terminationGracePeriodSeconds 应当大于关机超时时间，否则容器会在关机完成前被强制杀死。

七、常见误区

第一个误区是用 Close 代替 Shutdown。Close 适用于进程已经确定不再需要处理任何请求、希望立即退出的场景，例如启动失败后的清理，而不是日常的滚动发布。第二个误区是忽略 ListenAndServe 返回的 ErrServerClosed，把正常关机记录成启动错误，干扰故障排查。第三个误区是把超时时间设为零并认为这样是关闭超时，实际上零值表示不限制，慢连接会一直占用资源。第四个误区是在处理函数里忽略请求上下文，客户端已经断开后仍然继续执行耗时操作，白白浪费计算资源。

第五个误区是只在本地验证通过就认为生产环境也没有问题。本地只有一个实例，没有负载均衡器和连接池，关机顺序的问题很难暴露。发布前应当在接近生产的环境里做一次滚动发布演练，观察在途请求成功率、错误日志和关机耗时，确认关机超时时间与部署工具的等待时间匹配。

结语

优雅关机并不复杂，核心就是三个动作：捕获 SIGINT 和 SIGTERM，调用 Shutdown 并设置合理的等待上限，按照先停流量、再等请求、最后关资源的顺序退出。配合读超时、写超时和空闲超时，服务既不会被慢连接拖垮，也不会在发布时丢弃正在处理的请求。把本文的示例作为起点，根据接口的实际耗时调整超时时间，再做一次真实的信号验证，就可以把这套做法用到自己的服务里。