搭建带优雅停机和请求超时的生产级 HTTP 服务

把 http.ListenAndServe 放进 main 函数并不能算生产配置：默认服务缺少明确的请求读取、响应写出和空闲连接边界，进程收到重启信号时也可能直接中断正在处理的请求。更稳妥的做法是显式创建 http.Server，把服务启动、信号监听和优雅退出拆开管理。

官方文档：https://pkg.go.dev/net/http

先把 HTTP 服务的三个时间边界写出来

我更愿意先配置 Server，再把 Handler 注入进去。ReadHeaderTimeout 只覆盖读取请求头的时间，适合挡住迟迟不发完整请求头的连接；WriteTimeout 约束服务端写响应的时间；IdleTimeout 则针对 keep-alive 连接等待下一次请求的空闲阶段。它们不是一个“接口执行超时”，不能替代 Handler 内部的业务 context。

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.StatusNoContent)
    })

    srv := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 5 * time.Second,  // 限制慢速请求头。
        WriteTimeout:      15 * time.Second, // 普通 API 的响应写出上限。
        IdleTimeout:       60 * time.Second, // keep-alive 空闲连接上限。
    }

    serverErr := make(chan error, 1)
    go func() {
        // Serve 返回 ErrServerClosed 代表主动关闭，不应记成故障。
        serverErr 

启动 goroutine 后要区分两类错误

ListenAndServe 放在 goroutine 后，main 需要同时等待监听错误和退出信号。端口被占用、权限不足等启动故障应立即记录；收到信号后调用 Shutdown，它返回的 http.ErrServerClosed 是主动关停的正常结果，不应被报警系统当成服务崩溃。

这里给 serverErr 使用缓冲为 1 的 channel，是为了让服务 goroutine 在 main 已经进入退出路径时仍能把错误送出，不因接收方停止而卡住。信号 channel 也要在结束时执行 signal.Stop，减少全局信号订阅残留。

Shutdown 的等待时间要独立于请求超时

收到 SIGTERM 后，Shutdown 会停止监听新连接，并等待已有连接上的请求结束，但它不会替你决定“最多等多久”。退出 context 应该独立设置，例如 20 秒；不能直接复用某个请求的 context，也不能使用永不结束的 context.Background() 作为唯一等待条件。

如果在途请求超过退出窗口，记录超时原因后调用 Close。这会牺牲仍未完成的请求，但换来进程可以退出，便于编排系统继续拉起新实例。生产环境还应让负载均衡器先摘除实例，再发送终止信号，给连接迁移留出余量。

普通 API、上传和流式响应不要共用一套数值

15 秒的 WriteTimeout 适合多数短请求，却可能截断大文件下载或 SSE。长连接接口需要单独设计：可以拆到不同的 Server，或者在确认协议和客户端行为后调整写超时。Handler 内部仍应通过 r.Context() 传递取消信号，让数据库、下游 HTTP 调用和后台任务一起结束。

排查超时可以沿这张清单走：先看请求头是否迟迟不完整，再看 Handler 是否卡在下游依赖，最后判断是响应写出过慢还是 keep-alive 空闲过久。只把所有数字调大，通常只是把连接堆积推迟到更晚才暴露。

延伸问答

Shutdown 会立刻中断正在执行的 Handler 吗？

不会。它会等待在途请求结束，只有 context 超时后仍未完成时，才需要由调用方决定是否用 Close 强制收尾。

为什么不直接用 http.ListenAndServe？

快捷函数不便于集中配置 Server 的超时字段，也没有给信号退出流程留下清晰的控制点。生产服务应显式构造 http.Server。

Handler 超时和 WriteTimeout 是一回事吗？

不是。Handler context 超时控制业务执行，WriteTimeout 控制服务端写响应，两者应分别设置并互相配合。

最终的判断标准不是“参数越大越安全”，而是每个阶段都有可解释的时间边界，收到终止信号后既能给正常请求收尾，也不会因为一个失控连接阻塞整个进程退出。