Go HTTP 请求体为什么只能读一次：io.ReadAll 后绑定参数为空怎么排查

平时用Go写HTTP接口时，经常会碰到一个很迷惑的现象：明明前面接收到了完整的JSON请求，日志里打印出的请求内容也完全正常，可走到后面的参数绑定或者 json.NewDecoder 解析步骤时，拿到的数据直接是空的。这个问题绝大多数情况都不是客户端没传参数，而是服务端代码已经提前把 r.Body 读完了。http.Request.Body 本身是流格式对象，每读一次内部读取指针就往后走，后面的代码再尝试读取时，指针已经停在流的末尾，自然读不到任何内容。

问题现场：日志有内容，绑定却是空结构体

先看一个很多人都写过的常规接口。为了排查线上问题，我们在业务handler前面加了一段请求日志打印逻辑，把收到的body完整输出到日志里。日志里的内容明明完全正常，可后续业务代码里的结构体所有字段全是对应类型的零值。

func login(w http.ResponseWriter, r *http.Request) {
    raw, err := io.ReadAll(r.Body)
    if err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }
    log.Printf("request body=%s", string(raw))

    var req LoginRequest
    if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
        http.Error(w, err.Error(), http.StatusBadRequest)
        return
    }

    fmt.Fprintf(w, "user=%s", req.User)
}

这段代码的坑点就出在 io.ReadAll(r.Body) 这一步。它已经把整个请求体从头读到了末尾，后面执行的 json.NewDecoder(r.Body) 再去读取同一个请求体对象，自然拿不到任何内容。

先验证：是不是 body 被提前读完了

碰到这类问题先别急着怀疑前端传参错了，也别急着去查网关的配置。先加两行简单的调试日志，确认请求体在进入参数绑定逻辑之前，是不是已经被完全消费过了。最直观的验证方式，就是把首次读取请求体的内容长度，还有后续解析操作返回的错误信息都打印出来。

raw, _ := io.ReadAll(r.Body)
log.Printf("raw body len=%d", len(raw))

var req LoginRequest
err := json.NewDecoder(r.Body).Decode(&req)
log.Printf("decode err=%v req=%+v", err, req)

如果第一次读到的内容长度是正常数值，比如 38、120、512 这类符合请求预期的大小，后面却出现 EOF 报错，基本就能确认是读取顺序出了问题。这个时候先别直接下结论说 JSON 格式写错了，EOF 在这里的实际含义更接近“当前可读流里已经没有剩余内容”。

定位原因：Request.Body 是流，不是可重复读取的缓存

r.Body 的底层类型是 io.ReadCloser。它更像一条只能单向往前输送内容的水管，而不是一份可以随时拉到开头反复读取的内存字符串。全部读完之后，内部的读取位置已经走到了流的末尾，除非你手动把读到的内容完整保存下来，再重新构造一个全新的reader对象赋值回去，否则后续代码没有办法自动让读取指针回到开头。

这个坑绝大多数出现在三类代码场景里：第一类是请求日志中间件，为了完整打印请求内容提前读了一遍body；第二类是签名校验逻辑，需要拿到原始body的完整字节计算签名摘要；第三类是临时加的调试代码，当时为了排查问题调用了读取逻辑，上线之前忘了删掉恢复。这些代码本身的逻辑都是合理的，问题只出在读完之后没有把可读的新body对象重置回去。

修复方案：缓存字节后重置 Body

如果业务逻辑确实需要先读取一遍原始body，再把它交给后面的参数绑定逻辑处理，就要把之前读出来的字节内容重新塞回 r.Body 里。常规的兼容写法一般是配合 bytes.NewBuffer 和 io.NopCloser 一起实现。

func cacheBody(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        data, err := io.ReadAll(r.Body)
        if err != nil {
            http.Error(w, err.Error(), http.StatusBadRequest)
            return
        }
        _ = r.Body.Close()

        log.Printf("request body=%s", string(data))
        r.Body = io.NopCloser(bytes.NewBuffer(data))

        next.ServeHTTP(w, r)
    })
}

调整完之后后面的业务handler再调用 json.NewDecoder(r.Body) 时，读到的就是我们用缓存字节重新构造出来的全新reader对象。要注意这个操作并不是让原来的旧body对象自己倒回开头，而是用之前已经存好的字节内容，生成了一份从起始位置开始的新请求体对象。

复查结果：绑定成功以后还要控制大小

修复完成之后，可以用之前报错的同一个请求重测一遍：日志里能正常打印出原始JSON内容，业务结构体也能正确拿到所有字段值。这里建议顺便加一层内容大小的保护逻辑，不要没有限制地读取整个请求体内容到内存里，尤其是对外提供的公网接口，如果直接无上限读取 io.ReadAll 大体积body，很容易把服务内存占满。

r.Body = http.MaxBytesReader(w, r.Body, 1

如果你的接口只接受几十KB大小的JSON请求，把最大读取限制设为1 MiB已经留足了冗余空间。更大体积的文件上传场景，不建议用这种把整个body全读到内存的方式处理，改用流式读取或者专门的文件上传逻辑实现会更稳妥。

常见问题

为什么 Postman 传了参数，Go 里还是 EOF？

如果日志里能正常打印出完整body，执行解析操作的时候却报 EOF 错误，大概率是服务端代码在更早的链路里已经把请求体读过一次了。优先排查中间件、签名校验逻辑和调试日志模块的相关代码。

能不能直接读完 body 后复用 raw 字节解析？

可以。比如直接 json.Unmarshal(data, &req) 处理读到的字节内容。但如果后续链路里还有框架自带的绑定逻辑或者其他中间件要读取body内容，你仍然需要把新的可读对象重置回 r.Body。

GET 请求会不会遇到这个问题？

GET 请求通常不会携带请求体，主要参数都放在 query string 里传递。这类问题更多出现在 POST、PUT、PATCH 这类需要携带 JSON body 的接口场景里。

Gin、Echo 这类框架也会这样吗？

这类Web框架的底层还是复用Go标准库的request body流逻辑。部分框架会提供自带的缓存body或者重复绑定的辅助方法，底层实现原理也还是先把字节内容完整保存下来，再重新生成可读对象提供给后续的读取逻辑使用。