Go net/http Header.WriteSubset 怎样过滤不该转发的请求头

我在写一个很小的 HTTP 转发层时，原本想“保留大部分请求头，只排除几个不该继续传递的字段”。真正容易踩坑的地方不是 WriteSubset 的调用，而是排除表的键名和 Request.Host 的位置。

结论先说：http.Header.WriteSubset 会把 Header 以线格式写入 io.Writer，排除表中值为 true 的键不会被写出；排除键不会替你做规范化，必须和 Header map 中的实际键名匹配。

这篇只讨论 Header 过滤和写出边界，不把它当成完整代理实现，也不把它误称为运行截图。正文里的两张图都是静态结构说明图。

我第一次踩坑：排除表写对了，头部却还在

WriteSubset 的签名看起来很直白：给它一个 Writer，再给一个 map[string]bool。但官方文档特别强调，检查排除表时不会先把键名规范化。也就是说，Authorization 和 authorization 不是同一个排除键。

下面这个小例子把排除动作交给 WriteSubset，同时保留错误返回。示例中的值是演示数据，不代表任何真实凭据。

package main

import (
    "bytes"
    "fmt"
    "net/http"
    "net/textproto"
)

func writeForwardHeaders(h http.Header, excluded []string) (string, error) {
    // 先把调用方传入的排除键统一成 Header 常见的规范形式。
    exclude := make(map[string]bool, len(excluded))
    for _, key := range excluded {
        canonical := textproto.CanonicalMIMEHeaderKey(key)
        if canonical != "" {
            exclude[canonical] = true
        }
    }

    var buf bytes.Buffer
    // WriteSubset 只负责写线格式；业务层仍要处理 Writer 错误。
    if err := h.WriteSubset(&buf, exclude); err != nil {
        return "", err
    }
    return buf.String(), nil
}

func main() {
    headers := make(http.Header)
    headers.Set("X-Trace-ID", "demo-trace")
    headers.Set("Authorization", "Bearer demo")
    headers.Set("User-Agent", "header-demo")

    // 传入小写键也能得到同一个规范化排除键。
    wire, err := writeForwardHeaders(headers, []string{"authorization"})
    if err != nil {
        panic(err)
    }
    fmt.Print(wire)
}

在这个例子里，Set 会把键保存为规范形式，辅助函数也把排除项规范成同样的形式，所以 Authorization 不会出现在写出结果中。重要的是，WriteSubset 不会修改 headers；它只是读取 map 并写入目标 Writer。

把“排除什么”与“怎么写出”分开

我后来把代码拆成两层：上层根据业务决定哪些字段不能继续传播，下层只负责把剩下的 Header 写到 Writer。这样做的好处是，转发规则不会藏在底层序列化调用里，也方便测试排除表。

排除项通常来自具体场景：内部链路标记、只对当前服务有意义的字段，以及不应自动复制到下游的敏感字段。它们不是 WriteSubset 自己判断出来的。若直接通过 map 下标写入 Header，例如 h["x-trace-id"] = []string{"demo"}，就要确保排除表使用相同的键名，或者在进入写出层前统一规范化。

空排除表表示不额外过滤；但“全部写出”不等于“适合转发”。是否复制某个头部，仍然是你的协议和业务责任。不要把一个方便的 map 操作当成安全策略。

转发时别把所有头部都当成 Header

另一个容易误判的点是 Host。对传入请求来说，Host 会被提升到 Request.Host，并从 Header map 中移除。因此你遍历或调用 WriteSubset 时，不能期待它顺便写出 Host。如果目标是生成完整的 HTTP/1.x 请求，应该让 Request.Write 根据 Request 的字段生成请求，而不是只拼 Header。

这也说明了两个 API 的职责差别：

• Header.WriteSubset：只写 Header 的线格式，适合你已经明确请求行和字段边界的场景。
• Request.Write：综合 Method、URL、Host、Header、Body 等 Request 字段，生成完整请求。

如果你实现的是转发器，比较稳妥的拆法是先构造新的目标 Request，再显式复制允许的 Header；需要输出 Header 时才使用 WriteSubset。这样 Request.Host、请求体、Content-Length 等字段不会被错误地当成普通 map 项。

写出错误、规范化和排查清单

我现在遇到“头部怎么还在”的问题，会按下面顺序排查：

1. 打印或检查 Header map 的实际键名，确认是不是直接下标写入造成了非规范键。
2. 确认排除 map 的值确实是 true；只存在键但值为 false 不会排除。
3. 确认排除动作发生在写出前，并且没有随后又从原 Request 复制一遍头部。
4. 确认期待的字段是不是 Request.Host、Content-Length 或其他由 Request 写出逻辑处理的字段。
5. 保留 WriteSubset 的 error 返回，不要为了“只是写内存 buffer”而丢掉它。

对多数内存 bytes.Buffer 场景，写入错误通常不容易出现；但函数接受的是通用 io.Writer，未来换成网络连接、限长 Writer 或测试替身后，错误就可能成为正常控制分支。

适合谁，以及我最后的取舍

如果你在写 HTTP 代理、请求录制器、协议测试工具或自定义转发层，这个 API 很适合做“按排除表写出 Header”这一小块工作。对我来说，最重要的经验有三点：先确认 Header map 的真实键名，再构造规范化排除表；把业务上的允许/禁止复制规则放在上层；涉及完整请求时不要忘了 Host 在 Request 字段里。

相关问题：

• 排除表的键名为什么要区分大小写？因为 WriteSubset 检查排除表时不会先规范化键名。
• WriteSubset 会修改原 Header 吗？不会，它读取 Header 并把线格式写到 Writer。
• 想写出完整代理请求该用哪个 API？先构造 Request，再根据需要使用 Request.Write 或 Request.WriteProxy；不要只依赖 Header.WriteSubset。