Go HTTP 服务怎么设请求边界：请求体、超时和响应头的生产配置

一个看似普通的 POST /api/avatar 接口，最容易被忽略的不是业务校验，而是连接进来以后能占用多少时间和内存。请求头慢悠悠发、请求体传几百兆、客户端读到一半直接停住，默认启动的 Go HTTP 服务还是会老老实实在那儿等。线上真正要做的，是把「正常允许的请求范围」直接写进服务入口：哪些请求可以放宽等待时长，哪些请求该直接快速拒绝，拒绝之后日志里要留好可溯源的依据。

先把上传接口的合法边界说清楚

假设头像上传接口只接受 5 MiB 以内的图片，正常情况下客户端几秒内就能把请求头和请求体传完，服务端返回一段 JSON。这类边界不应该藏在某个深层的业务分支里，要从 http.Server 层就和业务处理逻辑一起做约束。只设一个数值很大的全局读超时看起来省事儿，最后往往会出现慢请求头、慢上传和正常大文件传输全部挤在同一个计时器里，出问题的时候完全找不到排查依据。

这里不用急着把所有阈值都压到最小。5 MiB 是业务允许的文件最大体积，不等于网络传输时间只能留 5 秒；移动网络环境下的普通用户可能需要更长的上传窗口。限制值要结合接口用途、反向代理的上限和实际线上链路情况来定，不要直接套一套通用常量。

服务入口负责请求头、响应和连接空闲时间

先给普通 API 配一套清晰的入口规则。示例里留 3 秒用来收完整的请求头，20 秒留给常规请求体读取操作，10 秒用来把结果写回给客户端，空闲连接超过 60 秒就不再继续占用资源。这些数字只是参考起点，正式发布前要结合实际的上传体积和网关日志做校准。

srv := &http.Server{
	Addr:              ":8080",
	Handler:           routes(),
	ReadHeaderTimeout: 3 * time.Second,
	ReadTimeout:       20 * time.Second,
	WriteTimeout:      10 * time.Second,
	IdleTimeout:       60 * time.Second,
	MaxHeaderBytes:    16 

ReadHeaderTimeout 和 ReadTimeout 很容易被当成同一套规则。前者从连接建立的那一刻就开始计时，核心要求是请求头必须在指定时间内收完；后者覆盖读取请求的全流程。对只接收小体积 JSON 的内部接口，20 秒可能已经非常宽松；对允许上传 100 MiB 文件的接口，更适合拆分到单独的服务或者独立路由处理，避免同一组全局参数要同时适配所有不同特征的流量。

不要把长连接接口塞进普通超时模型

服务端推送、长轮询和大文件下载的运行节奏和普通 JSON 返回完全不一样。尤其是持续往外输出数据的接口，如果直接套过短的 WriteTimeout，网速偏慢的客户端会在还有有效数据要传输的时候就被强制断开。更稳妥的做法是把这类接口单独拆分出来，明确心跳机制、取消信号的传递和代理层的时间限制，再判断要不要关掉全局写超时。

请求体上限要落在具体处理函数

MaxHeaderBytes 管不了请求里的文件内容；Content-Length 也不能当成唯一的防护手段，因为请求可以用分块传输的方式绕过基础校验。上传处理逻辑刚进入的时候就用 http.MaxBytesReader 包裹住 r.Body，后面的解析逻辑才会在体积超出上限的时候立刻停止读取。

const maxAvatarSize = 5  maxAvatarSize {
		http.Error(w, "avatar is too large", http.StatusRequestEntityTooLarge)
		return
	}
	// 继续做 MIME 类型、像素尺寸和存储校验。
	w.WriteHeader(http.StatusNoContent)
}

有个很常见的误区是只判断 header.Size。这个值适合拿来给用户做提示，却不是真正的读取边界；真正能防止处理逻辑把超大体积内容全读进内存的是 MaxBytesReader。另外，FormFile 返回的错误不全是体积超限，格式不对、字段缺失这类问题也会走到这个分支，所以返回的响应要区分不同场景，日志里也要带上路由名和具体的拒绝原因。

把拒绝结果变成可复查的依据

加完各类限制之后，最头疼的就是客户端看到 400 或者 413，服务端却只留了一行模糊的错误记录。建议在网关和应用日志里记录路由、状态码、读取耗时、请求长度和链路追踪 ID，不要记录完整 Cookie、Authorization 内容或者上传的文件原始内容。靠这些字段就能区分出「用户确实上传了超出大小的文件」和「某个中间代理提前截断了请求」这两类不同的场景。

started := time.Now()
next.ServeHTTP(recorder, r)

logger.Info("http request finished",
	"path", r.URL.Path,
	"status", recorder.Status(),
	"content_length", r.ContentLength,
	"duration_ms", time.Since(started).Milliseconds(),
	"request_id", r.Header.Get("X-Request-ID"),
)

验证边界的时候准备三类测试请求就够：正常 1 MiB 的图片要返回成功；6 MiB 的图片要返回 413；故意构造的超大请求头要在入口阶段就被直接拒绝。第三类测试不用在线上环境反复跑，在预发环境结合网关日志确认一次生效就可以。这里不用急于下结论：如果 6 MiB 的请求在网关层就被拦截，应用日志没有对应记录也是正常的，说明边界生效的位置比应用层更靠前。

上线前用一份清单核对参数是否互相冲突

• 确认 CDN、Nginx 或者 API 网关的请求体上限不小于应用允许的最大值，或者明确指定由哪一层返回 413 状态码。
• 确认上传接口的 ReadTimeout 可以覆盖目标地区的慢速网络场景，不要只在办公室的内网环境测一次就直接上线。
• 确认流式下载、服务端推送这类特殊路由没有误用时长过短的 WriteTimeout。
• 确认 400、413 和超时相关的日志不会写入令牌、Cookie、文件内容这类敏感数据。
• 确认压测结束之后，连接数和 goroutine 数量可以回落至正常的稳定水位。

HTTP 服务的安全配置不是堆越多超时规则就越好。核心是让每个入口都有可解释的时间和体积边界：小接口直接快速失败，上传接口按业务允许的体积读取，长连接类的特殊请求单独走明确的策略。出异常的时候，靠状态码和耗时字段就能把问题定位到网关层、连接读取层还是业务解析层。

相关问答

只设置 MaxHeaderBytes 能限制上传文件大小吗？

不能。它只限制请求头的总大小，文件内容全部存放在请求体里。上传接口要使用 http.MaxBytesReader，在解析操作执行之前就把读取逻辑包裹住 r.Body。

ReadTimeout 和 context 超时可以只留一个吗？

两者负责的场景完全不同。ReadTimeout 约束的是网络读取层面的操作，处理函数里的 context 超时更适合约束数据库调用、下游 HTTP 请求这类业务层面的操作。一般场景下两个规则都要单独设置，还要让业务调用逻辑能感知到请求取消的信号。

明明设置了请求体限制，为什么还是会看到 400 错误？

多部分表单格式损坏、字段名不匹配这类问题，也会让 FormFile 返回错误。用 errors.As 单独识别 http.MaxBytesError 这类体积超限的错误，其余异常按非法请求处理，同时保留完整的错误原因日志。

WebSocket 也适合套用这套 http.Server 的超时规则吗？

连接升级之后要按 WebSocket 专属的读写期限和心跳模型来管理。普通 HTTP 的全局读写超时可以作为入口层的基础防护，但不能替代连接建立之后的心跳检测和主动关闭逻辑。

收尾检查

先从最容易出问题的上传路由开始落地：服务入口层限制请求头、空闲连接和普通响应的时长，处理函数层限制请求体的最大体积，日志保留好状态码和耗时等溯源依据。等这条路径跑稳之后，再按不同接口的特征拆分出更长时长的上传、下载或者持续连接的专属策略，避免一个全局超时规则把所有不同特征的请求绑在同一个假设里。