httputilDumpRequest记录请求结构

Go 服务端可以使用 httputil.DumpRequest(r, false) 把请求结构转为便于阅读的文本。第二个参数为 false 时不包含请求体；为 true 时会读取请求体并在成功后替换为可再次读取的 Body。生产环境通常先记录经过筛选的请求元数据，遇到确实需要检查小体积正文的问题，再单独选择更细的诊断方式。

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

先按负载选择诊断粒度

排查网关后端接口时，常见问题是方法、路径、Host 或内容类型与预期不同。先看这些字段，往往就能缩小范围。持续上传、文件传输或长时间不结束的流式请求，不适合为了日志完整性读取整个 Body。即使普通 JSON 请求，正文也可能含个人信息或凭据。

这里的推荐架构是：访问日志负责日常观测，临时诊断工具只接收经过筛选的请求副本。不要把 DumpRequest 默认开启在全部请求上，也不要把它的文本结果直接当作原始网络数据。

用白名单副本生成请求文本

下面是一个无需启动服务的独立例子。它构造一条入站测试请求，然后生成一份刻意缩减的诊断视图：只保留方法与两个白名单头字段；路径、Host 统一替换，查询参数完全去掉。这样可以展示内容协商结构，同时避免把凭据字段和业务标识原样输出。示例不是通用脱敏库，实际项目需按自己的数据分类选择可记录字段。

package main

import (
    "fmt"
    "log"
    "net/http"
    "net/http/httptest"
    "net/http/httputil"
    "net/url"
    "strings"
)

// RequestView 生成经过筛选的诊断副本，不读取原始正文。
func RequestView(r *http.Request) ([]byte, error) {
    v := r.Clone(r.Context())
    v.URL = &url.URL{Path: "/diagnostic-target"}
    v.RequestURI = "/diagnostic-target"
    v.Host = "redacted.invalid"
    v.Header = make(http.Header)

    // 仅保留此例允许展示的头，并限制每个字段的数量和长度。
    for _, key := range []string{"Accept", "Content-Type"} {
        values := r.Header.Values(key)
        if len(values) > 4 {
            values = values[:4]
        }
        for _, value := range values {
            if len(value) > 256 {
                value = value[:256]
            }
            v.Header.Add(key, value)
        }
    }
    // Clone 不会复制 Body 数据；本例明确移除共享的正文引用。
    v.Body = nil
    v.GetBody = nil
    v.ContentLength = 0
    v.TransferEncoding = nil
    v.Trailer = nil
    return httputil.DumpRequest(v, false)
}

func main() {
    // 仅使用虚构测试数据，不连接外部服务。
    r := httptest.NewRequest("POST",
        "http://example.invalid/orders?debug=sample",
        strings.NewReader("sample-body"))
    defer r.Body.Close()
    r.Header.Set("Accept", "application/json")
    r.Header.Set("Content-Type", "text/plain")

    dump, err := RequestView(r)
    if err != nil {
        log.Fatal(err)
    }
    // 引号转义让换行成为可读转义字符，避免多行日志混排。
    fmt.Printf("request_view=%q\n", dump)
}

按代码构造，文本包含 POST、占位路径、占位 Host 和白名单头，不包含 sample-body，也不包含 debug 查询参数。本例给的是预期判断，没有声称已执行。若诊断必须保留真实路由，可记录框架提供的路由模板，例如带参数占位的路由定义；不要简单把含订单号或用户标识的完整路径视为无敏感信息。

比较三种 Dump 函数的职责

DumpRequest 面向服务端观察收到的请求。DumpRequestOut 面向客户端准备发出的请求，会包含标准 Transport 可能补充的某些头字段。DumpResponse 则用于响应对象。选错对象时，拿到的文本很容易与真正想排查的那一侧不一致。

例如，在服务端已经解析好的请求中，Host 是 Request 的单独字段，不能只遍历 Header 就认为没有 Host。请求 URI 也有 RequestURI 和 URL 的区别；前面的缩减视图同时处理这两处，避免修改 URL 后却仍然输出未处理的 RequestURI。

DumpRequestOut 的结果也不能代表任意自定义 RoundTripper、代理或 TLS 链路最终发送的每个字节。需要研究传输层差异时，应先明确是哪一层补充或修改了字段。

解释请求体与原始报文边界

DumpRequest(true) 的便利建立在读取 Body 的基础上，当前实现会把正文读入内存。成功后下游通常还能读取相同字节，但这并不等于没有成本：读取会提前发生，可能带来等待、内存占用和原始 Reader 关闭行为。若此前已经消费了部分 Body，它不会自动找回丢失的前半段。

只把请求 Clone 后交给 true，也不能解决问题：Clone 是浅复制 Body，副本仍共享原来的读取对象。确实需要正文诊断时，应先设计请求大小限制、读取超时、内容筛选和错误响应策略。事后把 dump 文本截短，只能减少日志长度，不能限制之前已经发生的读取与分配。

官方说明还指出，DumpRequest 出错后，请求状态不能依赖为仍可正常使用。因此在读取正文失败后，不能不加区分地把原请求继续交给业务处理器。前面的 false 示例处理的是已去除 Body 的副本，不提供 true 模式的恢复方案。

输出也不是原始报文的逐字节副本。解析会丢失头字段名原有的大小写及字段排列信息；同一头字段的多个值的顺序则得以保留。HTTP/2 请求会以 HTTP/1.x 形式展示，不能从中推断原始二进制帧排列。

确定线上启用与退出条件

对于云上服务，可以按接口或请求标识临时启用诊断，设置采样、有效期、日志权限和保留期限。高并发时优先使用固定字段的结构化日志，避免每个请求都生成一份较大的文本。日志系统发生拥塞时，也要有明确的丢弃或降级策略，不能让临时诊断变成主业务阻塞点。

落地时依次明确需要观察哪一侧、哪些字段允许记录、是否必须读取正文、最大输入规模、失败时如何退出。排障完成后关闭临时开关。本文的白名单副本适合解释受限请求结构；如果需要精确保留全部字段，它就不再是合适的记录格式。

body=false 就不会记录凭据吗？

它只控制正文是否加入。Authorization、Cookie、自定义头和查询参数都需要另外处理，不能把 false 当作自动脱敏开关。

能靠 dump 判断 HTTP/2 帧吗？

不能。输出是文本化的 HTTP/1.x 表示，不保留 HTTP/2 二进制表示。

为什么改了 URL，日志里仍有旧查询串？

入站请求的 RequestURI 可能仍保存原值。构造诊断视图时应同时考虑这个字段，并清楚标注哪些内容经过替换。

官方接口说明：https://pkg.go.dev/net/http/httputil#DumpRequest；实现参考：https://go.dev/src/net/http/httputil/dump.go。