Go http.MaxBytesReader 超限后怎样返回清晰的 HTTP 错误

文件上传接口最怕两件事同时发生：请求体没有上限，或者超限以后只返回一条用户看不懂的“读取失败”。Go 的 http.MaxBytesReader 适合把这两个问题拆开处理：先在 Handler 入口包住 r.Body，再判断读取结果是不是 *http.MaxBytesError。确认超限后，在响应头还没有写出之前返回 413 Request Entity Too Large，客户端就能得到稳定、可行动的错误。

关键点是不要把 io.ReadAll 返回的所有错误都当成 EOF。MaxBytesReader 在超过限制的读取上会返回带有 Limit 字段的 *http.MaxBytesError，用 errors.As 分支处理即可。

官方地址：https://pkg.go.dev/net/http

先分清 MaxBytesReader 报错和普通 EOF

MaxBytesReader(w, r.Body, limit) 返回的是一个 io.ReadCloser。它和 io.LimitReader 都能限制读取量，但前者面向入站请求体，超限读取会给出非空的 *http.MaxBytesError，并且关闭包装对象时会继续关闭底层请求体。这样做的价值不是把数据截断后“凑合解析”，而是让 Handler 知道请求没有完整到达。

判断时不要比较错误字符串，也不要只写 err == io.EOF。错误可能被解码器包了一层，使用 errors.As 才能保留类型判断。以下代码把“读取成功”“请求体过大”和“其他读取错误”分成三条可观察路径：

func upload(w http.ResponseWriter, r *http.Request) {
	const limit = 1 

把 413 返回放在响应头提交之前

最常见的失误是先调用 WriteHeader(200) 或先写入 JSON 成功体，随后才解析上传内容。一旦响应头提交，后面即使发现 MaxBytesError，也无法可靠地把状态改成 413。对于 JSON 接口，应该先完成限制读取和必要的语法解析，再统一写出成功响应。

如果接口能提前看到可信的 Content-Length，可以把它当作快速拒绝条件；但分块传输或长度缺失时，仍必须依靠包装后的读取结果。这个检查只能减少无谓读取，不能替代 MaxBytesReader。

三组边界请求足够验证实现

排查时准备三组请求：小于 1 MiB 的内容应进入成功路径；恰好达到限制的内容应以实际读取结果为准，不要凭字符串长度猜测；超过限制的内容必须命中 *http.MaxBytesError 并返回 413。若只测试带 Content-Length 的请求，还要补一组长度未知或分块请求，避免把代理层的行为误当成 Handler 已经完成限制。

生产配置上，响应体可以只暴露“请求体过大”和限制值，详细错误留在结构化日志中。限制值应由上传接口的业务上限决定，不要把它写成所有 API 共用的神奇常量；JSON、头像和大文件上传往往需要不同边界。

常见问题

为什么不能只用 io.LimitReader？

它能限制读取量，但不会提供 MaxBytesReader 的专用超限错误语义，也不是面向请求体的 ReadCloser 包装。需要明确返回 413 时，MaxBytesReader 更直接。

读取超限后还要继续解析剩余内容吗？

不建议。超限已经说明请求不满足接口契约，应立即返回并结束当前 Handler，避免继续消耗内存或进入不完整的业务对象。

为什么我的 413 没有生效？

重点检查是否在错误分支之前已经写过响应头或响应体，以及解析器是否在包装 r.Body 之前就被调用。