Go http.Server Shutdown 返回错误时怎么判断上下文超时

服务收到退出信号后，http.Server.Shutdown 返回非 nil，不一定代表监听器关闭失败。最常见的情况是优雅关闭窗口已经结束，但仍有活动请求没有回到 idle。判断这类错误时，应先看它是否能被 errors.Is(err, context.DeadlineExceeded) 匹配，再把 Serve 返回的 http.ErrServerClosed 单独处理。

如果错误来自 Shutdown(ctx)，且匹配 context.DeadlineExceeded，就可以确认是传入的关闭上下文超时；如果是 ListenAndServe 返回 http.ErrServerClosed，那是正常关停信号，不应按故障报警。

先分清 Shutdown 与 ListenAndServe 的错误

Shutdown 的职责是优雅地停止接收新连接，并让已有请求自然结束。官方文档描述的顺序是先关闭所有监听器，再关闭空闲连接，最后等待活动连接回到 idle。这个等待阶段如果超过 ctx 的截止时间，返回值就是该上下文的错误。

另一条错误通道来自 ListenAndServe 或 Serve。当程序调用 Shutdown 关闭监听器后，这些方法会返回 http.ErrServerClosed。因此它和 Shutdown 的返回值不能混在一个日志判断里。

用 context.Err 判断是否真的超时

标题里的“上下文超时”，指的是传给 Shutdown 的那个上下文到期，而不是某个 HTTP 请求自己超时。用 context.WithTimeout 创建关闭上下文，并在返回错误上使用 errors.Is，可以同时兼容被包装过的错误。

package main

import (
    "context"
    "errors"
    "fmt"
    "net/http"
    "time"
)

func gracefulStop(srv *http.Server) error {
    // 只给“等待已有请求结束”设置窗口，不复用某个请求的 Context。
    shutdownCtx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
    defer cancel() // 关闭计时器，避免把取消函数遗忘在成功路径上。

    if err := srv.Shutdown(shutdownCtx); err != nil {
        switch {
        case errors.Is(err, context.DeadlineExceeded):
            // 这个分支说明优雅关闭窗口已到期，仍有连接没有回到 idle。
            return fmt.Errorf("HTTP 优雅关闭超时: %w", err)
        case errors.Is(err, context.Canceled):
            // 父上下文或外部取消信号中断了本次收尾。
            return fmt.Errorf("HTTP 优雅关闭被取消: %w", err)
        default:
            // 其他错误优先按监听器或底层资源关闭失败排查。
            return fmt.Errorf("HTTP 关闭失败: %w", err)
        }
    }
    return nil
}

这里不要写成 err.Error() == "context deadline exceeded"。错误文本是给人看的，errors.Is 才是 Go 错误链的语义判断。context.WithTimeout 返回的取消函数也要调用：它既能释放定时器相关资源，也让代码的成功、失败路径保持一致。

超时后如何定位残留连接

匹配到 DeadlineExceeded 只说明“等完了还没收干净”，还不能说明是哪一个请求卡住。排查时先看活动请求是否在等待数据库、外部 HTTP 或消息系统；这些下游调用应继续接收请求上下文，避免 HTTP 层已经进入关停而依赖调用仍无限等待。

还要区分空闲连接与长连接。空闲连接会在 Shutdown 阶段被关闭，真正拖住等待的一般是仍在处理中的请求。被 hijack 的连接，例如 WebSocket，不由 Shutdown 关闭或等待；它们需要在应用自己的连接管理器里发送关闭通知，并等待协议层完成收尾。

如果业务允许更长的尾部时间，可以调大关闭窗口；如果进程必须在固定时间退出，则应在超时后进入明确的强制关闭策略。不要把超时直接吞掉，也不要假设再次调用 Shutdown 就能复用同一个 Server——Server 一旦调用过 Shutdown，后续不能重新用于 Serve。

把关闭流程写成可观测的收尾

生产日志至少应记录关闭窗口、错误分类和剩余资源线索。Serve 协程则只把真正的启动或异常错误上报：

serveErr := make(chan error, 1)
go func() {
    // Serve 在 Shutdown 后会返回 ErrServerClosed，这是正常生命周期信号。
    serveErr 

这个结构的关键不是把所有错误都转成成功，而是让两条生命周期通道各自承担责任：Shutdown 负责告诉你优雅收尾是否完成，Serve 负责告诉你监听循环为何结束。若需要在超时后关闭活动连接，应把这一动作作为显式的运维策略记录下来，而不是伪装成优雅关闭成功。

常见问题

Shutdown 返回 context.Canceled 也算超时吗？

不算。context.Canceled 表示取消信号先到，context.DeadlineExceeded 才表示截止时间先到；两者都可以用 errors.Is 区分。

为什么 ListenAndServe 报 ErrServerClosed 但服务没有故障？

因为 Shutdown 会主动关闭监听器，Serve 系列方法随后用 http.ErrServerClosed 结束阻塞。这是正常收尾路径，排除它后再记录其他错误。

超时后再调用 Shutdown 能继续等待吗？

不要把它当作可靠的续期机制。应先定位未结束的活动请求或 hijacked 连接，并根据进程退出预算选择延长原窗口、通知长连接或执行强制关闭。