Go HTTP 服务怎样优雅关闭

Go HTTP 服务要优雅关闭，核心不是收到信号后直接退出进程，而是先停止接收新的连接，再给正在处理的请求一个有限的收尾时间。标准库的 http.Server.Shutdown 正好提供了这条边界：它关闭监听器和空闲连接，等待活跃连接回到空闲；如果超时，则返回上下文错误，调用方再决定是否强制收尾。

官方文档：https://pkg.go.dev/net/http；信号处理文档：https://pkg.go.dev/os/signal。下面的写法适合普通 HTTP 请求，WebSocket 等被 hijack 的长连接需要单独通知。

先把“优雅关闭”拆成四个边界

一个服务收到 SIGTERM 或 Ctrl+C 后，至少要区分四件事：

• 监听器：关闭后不再接收新的连接。
• 空闲连接：可以直接关闭，避免服务迟迟不退出。
• 活跃请求：交给 Shutdown 等待，但必须设置时间上限。
• 长连接：WebSocket 等 hijacked 连接不由 Shutdown 等待，需要业务层自己发通知。

ListenAndServe 在正常关闭后会返回 http.ErrServerClosed，这不是故障。真正需要报警的是监听器本身返回的其他错误。

把停止信号接入服务生命周期

signal.NotifyContext 可以把系统信号转成上下文取消。关键点有两个：服务 goroutine 负责监听，主流程负责等待信号并调用 Shutdown；调用关闭方法后，主流程还要继续等待监听 goroutine 返回，不能立刻让 main 结束。

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

    srv := &http.Server{Addr: ":8080", Handler: mux}
    // 将 SIGINT、SIGTERM 转成可等待的取消信号。
    ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stop()

    // 长连接的业务层通知应立即开始，但不在回调里等待关闭完成。
    srv.RegisterOnShutdown(func() { log.Println("开始通知长连接退出") })

    serveErr := make(chan error, 1)
    go func() {
        // 独立 goroutine 让主流程同时等待服务退出或停止信号。
        serveErr 

这段代码没有把 ctx 直接传给 Shutdown，是因为收到信号后该上下文已经被取消；另外创建一个十秒的关闭上下文，才能给活跃请求留下排空时间。实际项目中可以把数据库、消息消费者等资源的清理放在 Shutdown 返回之后，并保持清理顺序稳定。

超时、Close 和长连接怎么取舍

Shutdown 返回超时错误，说明仍有连接没有回到空闲状态。此时调用 Close 会立即关闭服务器持有的连接，因此它应该是明确的兜底，而不是默认路径。关闭超时要结合最长业务请求、负载均衡摘流时间和容器的停止窗口设置，不能机械地写成一个很小的数字。

需要特别注意，HTTP 升级或 hijack 后的连接不属于 Shutdown 能完整管理的范围。可以使用 RegisterOnShutdown 发出“准备退出”的通知，再由 WebSocket、SSE 或自定义协议的管理器负责发送关闭消息、停止接收新任务并等待连接结束。

上线前用这张清单收尾

1. 把 ListenAndServe 的 http.ErrServerClosed 当作正常关闭，不要误报故障。
2. 确认收到信号后先进入 Shutdown，而不是直接调用 os.Exit。
3. 确认主流程等待服务 goroutine 返回，且数据库、队列等资源不会在请求仍使用时提前释放。
4. 确认 Shutdown 超时后有可观测日志和 Close 兜底，并记录被中断的请求。
5. 确认 WebSocket 等长连接有独立的通知、超时和回收逻辑。

如果服务运行在容器中，还要让平台的停止宽限期大于应用的关闭超时，否则应用还没完成排空就会被平台强制终止。

常见问题

为什么只调用 Shutdown，进程还是马上退出？

通常是 main 没有等待服务 goroutine，或其他 goroutine触发了进程退出。调用 Shutdown 后继续等待 ListenAndServe 返回，并让资源清理处在同一个生命周期中。

Shutdown 超时后一定要调用 Close 吗？

不一定，但必须有明确策略。若停止窗口即将结束，Close 可以避免进程悬挂；若业务允许继续等待，也可以把超时记录下来后交给更上层的停止机制。无论选择哪种方式，都要让超时可观测。

RegisterOnShutdown 会替我关闭 WebSocket 吗？

不会。它只是提供通知钩子，而且回调不应等待关闭完成。WebSocket 管理器仍需自己维护连接、发送关闭消息并设置最终超时。