HTTP 服务器读取请求体超时的连接处理

我在处理慢上传接口时，最容易先改错的是 ReadHeaderTimeout：它能挡住“连请求头都迟迟发不完”的连接，却不会替你决定请求体还能读多久。Go 的 net/http 里，服务器级 ReadTimeout 可以覆盖完整请求，而需要按接口区分上传预算时，应在处理器里给当前请求体设置读取截止时间。

要点是：ReadHeaderTimeout 负责请求头，ReadTimeout 负责整个请求（包含请求体），IdleTimeout 负责 keep-alive 连接等待下一次请求；请求体读取超时后，应用还要分别处理超时、客户端断开、大小超限，以及 HTTP/1.1 是否关闭连接。

官方地址：https://pkg.go.dev/net/http。下面按我实际排查这类接口时的顺序，把超时边界和连接处理拆开。

先分清三个 Server 超时字段

ReadHeaderTimeout 是读取请求头的时间预算。请求头读完后，标准库会重置连接读取截止时间；如果它为零，服务器会回退使用 ReadTimeout，两者都没有正值时就没有对应的读取超时。

ReadTimeout 的范围更大，覆盖读取完整请求，包括请求体。它适合作为服务器级兜底，但它不能让每个 Handler 根据文件大小、网络速度或业务类型做不同决定。IdleTimeout 则是 keep-alive 连接等待下一次请求的时间，不是当前请求体的上传时限。

按接口给请求体设置读取截止时间

慢上传接口通常需要一个更明确的策略：先让服务器快速读完请求头，再由当前处理器为请求体设置自己的读取截止时间。ResponseController.SetReadDeadline 设置的是包含请求体在内的读取截止时间；读取超过截止时间后，请求体读取会返回错误。

func uploadHandler(w http.ResponseWriter, r *http.Request) {
	// 读取请求体的预算由接口决定，避免所有接口共用一个拍脑袋的时长。
	deadline := time.Now().Add(15 * time.Second)
	controller := http.NewResponseController(w)
	if err := controller.SetReadDeadline(deadline); err != nil {
		// 当前 ResponseWriter 不支持设置读取截止时间时，不能假装超时已生效。
		http.Error(w, "server cannot set read deadline", http.StatusInternalServerError)
		return
	}

	// 时间边界之外再加大小边界，避免慢速大请求同时消耗时间和内存。
	r.Body = http.MaxBytesReader(w, r.Body, 4

这段写法的重点不是把每个错误都映射成同一个状态码，而是先阻止不完整的请求体进入业务层。实际项目中还可以把错误原因写入结构化日志，但不要把整段上传内容写进日志。

超时、断开和超大请求不要混为一谈

客户端主动断开时，服务端读请求体通常会提前收到读取错误，r.Context() 也会反映连接关闭或请求取消。读取截止时间到了，则属于服务器主动结束等待。两者都意味着本次 body 不完整，但排障动作不同：前者应关注客户端、代理或网络，后者应关注接口预算、上传大小和部署链路的时间限制。

http.MaxBytesReader 处理的是大小边界，不是速度边界。一个很小的请求体也可能因为客户端发送得很慢而触发 deadline；一个高速发送的大文件也可能先触发大小上限。把这两个边界分开，日志才有判断价值。

我还会避免在读取失败后继续调用业务解析器。JSON 解码器面对半截数据时可能只返回“语法错误”，这会掩盖真正的网络超时或连接关闭原因。

HTTP/1.1 连接该不该关闭

请求体读取超时后，当前请求已经没有完整输入。HTTP/1.1 下，如果连接里还可能残留这次请求的字节，就不应把“连接可以 keep-alive”理解成“请求可以继续”。示例里只在 HTTP/1.1 的超时分支写入 Connection: close，让客户端知道这条连接不应继续复用。

这不是恢复请求的办法。连接关闭不会把已读取的字节拼回去，也不会让客户端自动重发一个安全的请求。是否重试要由调用方和业务幂等策略决定；上传接口尤其要避免因为客户端重试而产生重复写入。

如果接口确实允许大文件慢速上传，可以把截止时间设计成“固定准备时间 + 按大小计算的预算”，或改用分片上传和上传会话。不要单纯把 ReadTimeout 调得很大，因为这会扩大所有请求占用连接和处理资源的窗口。

部署时的最小复查表

最后记住一条经验：服务器超时字段解决的是默认边界，Handler 解决的是业务差异，连接关闭解决的是本次 HTTP 会话的后续使用。三层策略各自负责一件事，慢上传和请求体超时就不会再被误判成普通业务错误。

相关问题

• 只设置 ReadHeaderTimeout 能限制上传时间吗？不能，它主要限制请求头读取；请求体需要 ReadTimeout 或处理器级读取截止时间。
• 请求体超时后还能复用同一个 Request 吗？不应直接复用。当前 Body 已经部分读取或关闭，应重新创建请求体和请求对象。
• IdleTimeout 能替代请求体超时吗？不能。它控制 keep-alive 等待下一次请求，不覆盖当前 Handler 正在读取的 body。