请求调试

在 Go 服务端做请求调试，最容易踩的坑不是“怎么打印”，而是打印以后请求体还能不能继续读。结论先说：服务端调试用 httputil.DumpRequest(r, true)，它会读取请求体并在成功时放回一个能产生相同字节的新 io.ReadCloser；只想看请求行和请求头时传 false。如果前置中间件已经把 r.Body 读到 EOF，DumpRequest 看到的也只会是空实体，必须先恢复 Body。

把 body 参数理解成“是否把实体放入转储”，把 req.Body 理解成“下游仍要消费的流”，就能稳定处理空请求体、重复读取和日志边界。

先区分服务端请求与客户端请求

httputil.DumpRequest 面向服务器端收到的客户端请求，适合放在 Handler 或服务端中间件里观察方法、路径、请求头和可选的实体。客户端准备发出的请求则应优先看 httputil.DumpRequestOut，它会通过客户端 Transport 的写出路径，包含诸如 User-Agent 这类 Transport 可能补上的头。

两者都返回 []byte 和 error。这不是线上页面或抓包工具的原始字节副本：官方文档说明 DumpRequest 返回的是 HTTP/1.x 形式的近似表示，解析成 http.Request 后，原始请求头名称的大小写和顺序等信息已经无法完整保留。

body 参数和空请求体怎么选

body=false 时，转储包含请求行、请求头等信息，但不读取请求实体；这适合 GET、健康检查、只关心鉴权头的排错。body=true 时才会尝试读取 req.Body。当 req.Body 为 nil 或 http.NoBody，结果自然没有实体内容，不需要为了“打印空 Body”额外构造字符串。

还有一个容易忽略的边界：HTTP/2 请求也会以 HTTP/1.x 形式出现在 DumpRequest 结果中，因此不要把它当作 HTTP/2 帧级别的原始抓包。

body=true 为什么不会让下游读到空 Body

成功调用 DumpRequest(r, true) 时，标准库会先把原始 Body 的字节读入内存，再把请求体替换成一个新的读取器。一份字节用于生成 dump，另一份用于恢复 r.Body，所以下游 JSON 解码器仍然可以读取同一个实体。

一个最小的服务端写法如下。注意先处理错误，再把 dump 交给日志；如果读取失败，官方文档不保证请求对象仍处于什么状态。

package main

import (
    "encoding/json"
    "log"
    "net/http"
    "net/http/httputil"
)

func handler(w http.ResponseWriter, r *http.Request) {
    // true 表示把请求实体也放进调试转储，并在成功时恢复 r.Body。
    dump, err := httputil.DumpRequest(r, true)
    if err != nil {
        // 读取失败时不要继续假设 r.Body 还能被安全消费。
        http.Error(w, "request dump failed", http.StatusBadRequest)
        return
    }
    log.Printf("incoming request:\n%s", dump)

    var payload struct {
        Name string `json:"name"`
    }
    // DumpRequest 成功后，下游仍可从恢复后的 r.Body 解码。
    if err := json.NewDecoder(r.Body).Decode(&payload); err != nil {
        http.Error(w, "invalid JSON", http.StatusBadRequest)
        return
    }
    w.WriteHeader(http.StatusNoContent)
}

这里的“恢复”只代表标准库在本次调用成功后替换了 Body，不代表可以无限次读取。下游一旦消费完流，下一次读取仍会到达 EOF；如果业务需要多次处理，应把字节缓存或使用专门的请求体工厂。

前置中间件已经读过 Body，为什么 DumpRequest 还是空

如果日志中间件、鉴权中间件或 JSON 预解析代码先执行了 io.ReadAll(r.Body)，原始流已经被消费。此时再调用 DumpRequest(r, true) 并不会凭空找回数据，它只能从当前 Body 读取到 EOF。

正确做法是：前置读取时保留字节，并在交给下一个处理阶段前放回一个新的 io.ReadCloser。下面的函数只负责恢复流，调用方仍要根据请求大小设置上限，避免把不受控的实体全部放进内存。

package requestdebug

import (
    "bytes"
    "io"
    "net/http"
)

func readAndRestore(r *http.Request) ([]byte, error) {
    // 读取前保留原 Body；nil 或 NoBody 表示没有可读实体。
    if r.Body == nil || r.Body == http.NoBody {
        return nil, nil
    }
    data, err := io.ReadAll(r.Body)
    if err != nil {
        return nil, err
    }
    // 关闭已经消费的流，再把相同字节交还给后续 Handler。
    if err := r.Body.Close(); err != nil {
        return nil, err
    }
    r.Body = io.NopCloser(bytes.NewReader(data))
    return data, nil
}

如果你已经拿到 data，后续调试可以基于这份字节构造日志，不必再次消费业务 Body；或者先恢复，再调用 DumpRequest。不要把“前置读取”和“DumpRequest 读取”都当成独立的数据源，它们面对的是同一个流。

大请求、敏感字段和失败状态要单独设边界

body=true 的核心代价是把 Body 读入内存。上传文件、超大 JSON 或未知长度请求不适合无条件完整转储。更稳妥的做法是默认使用 false，只在受控排障路径读取实体，并在读取前通过业务限制或 http.MaxBytesReader 设上限。

请求体可能含密码、Cookie、Authorization、身份证号或支付信息。原始 dump 直接写日志前应做字段级脱敏；如果只是定位路由和鉴权问题，记录方法、路径、状态和必要请求头通常已经足够。

最后，DumpRequest 的错误不能被忽略。官方说明在返回错误时请求状态未定义，因此不要在错误分支里继续依赖原 Body，也不要为了得到一段日志而重复发送同一请求。

一张表记住调用边界

常见问题

DumpRequest(r, true) 调用后还要手动给 r.Body 赋值吗？

成功路径通常不需要。DumpRequest 已经恢复了一个能产生相同字节的读取器；只有前置代码自己消费了 Body，或者你要改变读取上限与生命周期时，才需要显式恢复。

为什么 DumpRequest 的结果和 HTTP/2 抓包不一样？

它返回的是 HTTP/1.x 形式的近似表示，不是 HTTP/2 二进制帧。需要帧级信息时，应使用专门的网络观测工具。

空 Body 是不是说明客户端没有发送请求？

不是。GET、HEAD 或明确没有实体的请求可以正常到达服务端；当 Body 为 nil 或 NoBody 时，DumpRequest 只是不包含实体部分。

实际排查时，先确认请求方向，再决定是否读取 Body；若前面已有读取逻辑，优先恢复同一组字节。这样既能拿到调试信息，也不会把下游处理变成“读到空请求体”。