Go http.Server 如何配置优雅关闭的超时时间

Go 的 http.Server 没有一个名为“优雅关闭超时”的独立字段。正确做法是创建一个带截止时间的 context.Context，再把它传给 Server.Shutdown(ctx)。例如把关闭预算设为 5 秒：服务会先停止监听新连接、关闭空闲连接，并在这 5 秒内等待在途请求结束；超时后返回 context.DeadlineExceeded，主流程可以记录日志并继续退出。

关闭超时配置在 Shutdown 的上下文里，而不是 ReadTimeout 或 WriteTimeout 里。前两个控制请求读写，后者控制整个关闭等待窗口。

为什么超时要放在 Shutdown 的上下文里

ReadTimeout、ReadHeaderTimeout 和 WriteTimeout 是请求处理阶段的限制；它们不会告诉服务器“收到退出信号后最多等多久”。Shutdown 接收的 ctx 才是关闭流程的统一截止时间。官方实现的语义是：先关闭监听器，再关闭空闲连接，随后等待活跃连接回到空闲。如果上下文先到期，就返回上下文错误。

这意味着“停止接收新请求”和“给旧请求留收尾时间”是两个相邻但不同的动作。信号上下文负责触发关闭，带超时的派生上下文负责限制等待范围。

一套可复用的退出代码

下面的最小写法把服务启动、信号接收、关闭预算和错误判断放在同一个主流程里。示例选择 5 秒只是起点，真实值应覆盖大多数正常请求的收尾时间，同时小于编排平台或进程管理器的强制终止窗口。

package main

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

func main() {
    srv := &http.Server{Addr: ":8080", Handler: http.DefaultServeMux}
    signalCtx, stopSignal := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
    defer stopSignal() // 关闭完成后恢复信号默认行为并释放通知资源。

    go func() {
        if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
            log.Printf("HTTP 服务异常退出: %v", err) // 只有非正常关闭才记录为故障。
        }
    }()

    

这里要注意两个细节。第一，ListenAndServe 在 Shutdown 开始后会返回 http.ErrServerClosed，这是预期路径。第二，关闭上下文不要直接复用已经因信号取消的 signalCtx：信号一到它就会结束，Shutdown 将没有任何等待时间，所以要从 context.Background() 重新派生一个带超时的上下文。

5 秒不够时怎么判断

不要一看到超时就盲目把数字改大。先看哪些请求仍处于在途状态，再区分它们是普通 HTTP 请求、流式响应，还是已经被应用接管的长连接。普通连接会参与 Shutdown 的等待；如果业务有慢查询、文件上传或批量导出，应让这些操作响应请求上下文取消，并单独记录它们的最大收尾时间。

官方文档特别指出，Shutdown 不会关闭或等待 hijacked connections，例如 WebSocket。此时可以用 RegisterOnShutdown 发出协议级通知，但回调应启动特殊连接的收尾，不要在回调里阻塞等待全部关闭。若服务必须等这些连接结束，应由业务层维护连接集合和独立的等待机制。

常见问题

Shutdown 返回超时错误后还能继续复用 Server 吗？

不能把它当作可重启对象。Shutdown 调用后，官方语义不支持再次复用同一个 Server 继续提供服务；应该让进程退出，由外部进程管理器重新拉起。

关闭超时设置成 0 会立即断开吗？

不会因为给 Shutdown 传入一个普通的无截止时间上下文就立即断开；那反而可能无限等待。需要立即终止时使用 Server.Close，但它会主动关闭活动连接，不属于优雅关闭。

为什么收到第二个 Ctrl+C 仍然没有退出？

NotifyContext 会改变信号的默认退出行为，直到调用返回的 stop。生产环境通常让第一次信号走优雅关闭，超时后由进程管理器强制终止；本地调试则可以在超时分支显式调用 Close。