Go HTTP 超时把 HeaderTimeout 与整体超时分开的配置方法

Go 里常被口头称作“HeaderTimeout”的配置，实际字段名是 http.Server.ReadHeaderTimeout。它只给服务端读取请求头一段时间；请求体和整个读取阶段还要看 ReadTimeout。因此，想把“慢请求头防护”和“正常请求整体预算”分开，应该同时配置这两个字段，而不是寻找一个名为 HeaderTimeout 的 API。

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

先把 HeaderTimeout 对应到 ReadHeaderTimeout

http.Server 没有 HeaderTimeout 字段，搜索这个词时真正要找的是 ReadHeaderTimeout。该值限制服务端读取请求头的时间，适合拦住只建立连接、迟迟不发完整首部的客户端。

它不等于“整个请求最多只能运行这么久”。请求头读完后，服务端还可能继续读 body、执行 handler、写回响应，这些阶段分别由其他配置负责。下图只表达字段与阶段的静态关系，不是运行截图或实测证据。

同时配置请求头和整体读取预算

典型服务可以先给请求头较短的保护窗口，再给普通请求更长的完整读取窗口。注意，ReadTimeout 是从读取请求开始计算的整体上限，包含请求头时间，所以两个值不是 3 秒加 30 秒，而是两个相互约束的上限。

package main

import (
    "log"
    "net/http"
    "time"
)

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/upload", func(w http.ResponseWriter, r *http.Request) {
        // 业务代码只处理已经通过服务端读取预算的请求。
        w.WriteHeader(http.StatusNoContent)
    })

    server := &http.Server{
        Addr:              ":8080",
        Handler:           mux,
        ReadHeaderTimeout: 3 * time.Second,  // 首部阶段的短保护窗口
        ReadTimeout:       30 * time.Second, // 首部加请求体的整体读取上限
        WriteTimeout:      15 * time.Second, // 响应写出预算，不延长读取时间
        IdleTimeout:       60 * time.Second, // keep-alive 等待下一次请求的上限
    }

    // 启动失败必须交给进程入口处理，避免服务假启动。
    log.Fatal(server.ListenAndServe())
}

这个比例只适合作为普通 JSON 或小型表单接口的起点。上传接口的请求体更大时，不能只把 ReadHeaderTimeout 调大；应结合允许的 body 大小、客户端发送速度和代理层预算重新计算 ReadTimeout。

别把读取、响应和空闲连接混成一个超时

WriteTimeout 约束服务端写响应的时间，慢查询或大响应可能需要更长预算；IdleTimeout 则针对 keep-alive 连接在两次请求之间的空闲等待。它们都不是 ReadHeaderTimeout 的替代品。

如果只想限制 handler 的处理时间，还可以在业务层使用请求上下文或 http.TimeoutHandler，但那是处理层语义，不能代替连接读取阶段的超时。尤其是慢请求头问题，等 handler 开始执行已经太晚。

上线前用四项清单复核

排查超时时，先看日志发生在“还没进入 handler”“读取 body 途中”还是“开始写响应之后”。只有先定位阶段，才知道应该调整哪一个字段；一味把所有秒数改大，通常只是把连接占用和故障暴露时间一起放大。

常见问题

Go 的 HeaderTimeout 能不能直接这样写？

不能。http.Server 的实际字段是 ReadHeaderTimeout，标题里的 HeaderTimeout 是便于搜索的说法，代码必须使用官方字段名。

ReadHeaderTimeout 和 ReadTimeout 要不要相加？

不要相加。ReadTimeout 是包含请求头在内的完整读取上限；ReadHeaderTimeout 为首部阶段增加更早的保护边界。

为什么设置了 ReadHeaderTimeout，接口还是超时？

它只覆盖请求头。若超时发生在 body 读取、handler 执行或响应写出阶段，应分别检查 ReadTimeout、业务上下文和 WriteTimeout。