Go HTTP 服务怎样区分读请求头和读请求体超时

Go HTTP 服务中，ReadHeaderTimeout 管读请求头的时间，ReadTimeout 管读取整个请求的时间，包含请求体。它们不是“请求头结束后再开始一段独立的请求体计时”的两个串联计时器，也都不是 Handler 业务逻辑的总执行时限。

若现有配置只有 ReadTimeout，拆出较短的 ReadHeaderTimeout 时，不能顺手把 ReadTimeout 删除后仍期待慢请求体被自动限制。这里讲的是配置职责的迁移，不是某个 Go 新版本引入的变更。官方参数说明：https://pkg.go.dev/net/http#Server。

先限定要调整的读取阶段

先区分请求头没有读完与请求体没有读完。正常进入 Handler 后，程序能够访问已解析的请求头，但请求体通常仍由 Handler 通过 r.Body 读取。不能把“进入处理器”当作“请求内容全部收到”。

本文用普通明文 HTTP/1 请求解释读取职责，不扩展 TLS 握手、HTTP/2 多路复用、写响应或保持连接等待下一请求的超时。线上经过反向代理时，客户端、代理和 Go 服务看到的是不同连接，不能直接把客户端上传时间等同于 Go 服务的读取时间。

把两个字段及零值规则分开

尤其留意零值回退：ReadHeaderTimeout 为 0、ReadTimeout 为正时，头读取并非没有限制，而是采用 ReadTimeout。两者都没有正值时，不应期待默认存在一个固定的读取时限。不要为了表达“未配置”而随意用负值，因为它与零值回退含义不同。

两个字段可同时使用。请求头读取完成后，连接读截止时间会调整为后续读取所需的设置；这不意味着只配置头超时就能限制请求体。如果 ReadTimeout 为正，它提供的是整个请求读取预算，不是每读到一个字节就重新给一段完整时间，也不是根据上传速率自动续期。

识别只配一个参数的迁移风险

旧配置只有 ReadTimeout: 18 * time.Second 时，头读取也可能沿用这份预算。增加 4 秒的头读取设置，目的是把头部允许时间写清楚；保留 18 秒整个请求读取预算，则仍明确限制整体读取。两个数字仅是教学示例，需要根据实际接口和网络条件选择。

相反，改成“ReadHeaderTimeout 为 4 秒，ReadTimeout 为 0”，就只保留头读取限制。这样可能适合另有请求级读取策略的上传服务，但并不等同于“正文也有 4 秒”。另一种误解是把 ReadTimeout 的 18 秒当成读完头以后追加的 18 秒，导致对慢上传容忍范围判断错误。

如果接口之间存在普通小请求和长上传的差别，一个全局固定预算可能不适合所有请求；本文只说明这两个 Server 字段不能提供逐请求上传速率策略，不在此扩展另一套超时实现。

为普通 HTTP 接口写明确配置

下面完整示例保存为 main.go，仅供读者自行尝试。本轮未启动服务、未发送慢请求、未测量结果。Handler 用 io.Copy 将请求体读到 io.Discard，不把整份内容堆进内存；示例不处理业务、不保存上传文件，也不是完整生产上传接口。

package main

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

func main() {
    mux := http.NewServeMux()
    mux.HandleFunc("/receive", func(w http.ResponseWriter, r *http.Request) {
        if r.Method != http.MethodPost {
            w.Header().Set("Allow", http.MethodPost)
            http.Error(w, "请使用 POST", http.StatusMethodNotAllowed)
            return
        }

        // 进入 Handler 只说明请求头已可供使用，不代表请求体读完。
        log.Print("进入处理器：准备读取请求体")
        n, err := io.Copy(io.Discard, r.Body)
        if err != nil {
            var ne net.Error
            if errors.As(err, &ne) && ne.Timeout() {
                log.Printf("请求体读取超时：已读取 %d 字节，错误 %v", n, err)
                // 尝试回送错误；连接状态不保证客户端一定收到响应。
                http.Error(w, "读取请求体超时", http.StatusRequestTimeout)
                return
            }
            log.Printf("请求体读取失败：已读取 %d 字节，错误 %v", n, err)
            http.Error(w, "请求体读取失败", http.StatusBadRequest)
            return
        }
        log.Printf("请求体读取完成：%d 字节", n)
        w.WriteHeader(http.StatusNoContent)
    })

    srv := &http.Server{
        Addr: "127.0.0.1:8080",
        Handler: mux,
        // 这些是教学示例值，不是生产通用推荐。
        ReadHeaderTimeout: 4 * time.Second,
        // 整个请求读取预算包含请求体，不是每次 Read 重新计时。
        ReadTimeout: 18 * time.Second,
    }

    // 演示明文 HTTP/1 请求，避免把协议差异混入读取职责。
    log.Print("启动本地示例服务")
    if err := srv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
        log.Fatal(err)
    }
}

判断超时使用错误类型的 Timeout 方法，不用固定的错误文本作为唯一判断。部分读取之后失败，n 仍可记录已读字节，但这些数据不能被当作完整业务请求。返回 408 是示例 Handler 的处理选择，不代表 net/http 的所有头部超时都会自动返回同一状态码。

服务端请求体由 net/http 在处理流程结束时关闭，示例不把它转交后台使用。读取到 EOF 后才记录“读取完成”。真实接口还需自己的大小与业务内容限制；读取时间限制不等于长度限制。

按请求头和请求体分别观察现象

读者自行在隔离环境观察时，应把现象分开记录：头部读取过慢，目标 Handler 可能根本没有进入；头部正常、请求体迟迟读不完，则可能已经出现进入日志，而后在读取 Body 时得到错误。进入日志与读取完成日志是一对定位标识，不代表服务端已经自动识别所有原因。

这仍需结合实际错误：客户端主动断开、请求体格式问题、代理提前终止也会造成读取失败，不能看到 err 就归因于 ReadTimeout。代理若先完整缓冲请求体，再转发到 Go 服务，Go 服务的读取现象也可能与客户端慢上传不同。

还要做反向理解：请求头和请求体都读完后，Handler 继续做很久的计算，并不由这两个读取字段直接设置业务总执行时限。读超时不是用于强制停止任意 Go 代码的计时器；客户端没收到响应，也不能单凭这一点证明是读头还是读体超时。

保留超时配置的迁移清单

• 记录原有两个字段的实际值，尤其区分零值回退和显式负值。
• 拆分配置后写清：哪个接口保留整体读取预算，哪个接口另有策略。
• 普通接口与长上传分别考虑，不把示例秒数复制成统一标准。
• 记录进入 Handler、Body 读取完成和读取错误，不仅看客户端状态。
• 区分读取时间、业务执行、代理限制和请求长度，不让一个字段承担全部职责。

只设置 ReadHeaderTimeout，请求体也会超时吗？

不能据此得出结论。这个字段在头读取结束后不继续充当请求体的统一时限；如果 ReadTimeout 没有正值且没有其他限制，就没有它提供的整体读取超时。

ReadTimeout 为零，ReadHeaderTimeout 为正是否有效？

头读取仍有明确预算，但不能把它理解为整个请求体读取预算。这种配置需要结合接口已有的请求体策略。

为何超时后客户端不一定收到 408？

示例只在 Handler 检测到请求体读取超时后尝试写 408；读头失败可能发生在 Handler 之前，连接和代理状态也会影响响应能否送达。服务端日志与客户端观察要分开解释。

相关资料：Server 字段说明 https://pkg.go.dev/net/http#Server；HTTP/1 服务端读取实现 https://go.dev/src/net/http/server.go。整理配置时先明确“限制哪段读取”，再决定参数值，比单纯增加一个 timeout 字段更可靠。