Go textproto.MIMEHeader.Del 怎样删除规范化后的请求头字段

如果一个 MIME 头字段可能以 content-type、Content-Type 或其他大小写形式传入，直接用原始字符串操作 map 很容易留下残余值。textproto.MIMEHeader.Del 的正确用法是传入字段名，让标准库先按 MIME 规则规范化键名，再删除这个键对应的全部值。

官方地址：https://pkg.go.dev/net/textproto#MIMEHeader.Del

Del 删除的是一个字段项及其所有值，不是只删除 Get 看到的第一个值；调用时可以使用大小写混合的键名，但直接访问 map 时必须自行遵守规范化约定。

先理解 MIMEHeader 的键名规范化

MIMEHeader 的底层类型是 map[string][]string。标准库的 Add、Set、Get、Values 和 Del 都会把传入键名交给 CanonicalMIMEHeaderKey。例如 content-type 会对应到 Content-Type，连字符后的字母会转成大写，其余字母转成小写。

这意味着删除时不必先猜测 map 里保存的大小写，只要这个键是通过标准方法写入的，下面的调用就能定位同一项：

package main

import (
    "fmt"
    "net/textproto"
)

func main() {
    header := make(textproto.MIMEHeader)
    // Add 会把字段名规范化为 Content-Type，并保留多个值。
    header.Add("content-type", "text/plain")
    header.Add("CONTENT-TYPE", "text/html")

    // Del 会用同样的规范化规则定位 Content-Type。
    header.Del("CoNtEnT-TyPe")
    fmt.Printf("remaining=%v\n", header)
}

这里的重点是“写入和删除使用同一套键名规则”。如果代码在中间直接写入了另一个大小写形式的 map 键，标准方法可能不会把它当作同一项，后文会专门说明这个边界。

用 Del 删除字段及其全部值

Get 只返回第一个值，但 Del 调用的是 map 的删除操作，会移除该键对应的整个 []string。因此同一个字段有多个值时，不需要循环调用，也不应该把 Get 返回的字符串当成待删除对象。

package main

import (
    "fmt"
    "net/textproto"
)

func main() {
    header := textproto.MIMEHeader{
        "X-Trace-Id": {"trace-a", "trace-b"},
        "Accept":     {"application/json"},
    }

    // Del 删除 X-Trace-Id 对应的整个切片，而不是只删除 trace-a。
    header.Del("x-trace-id")

    // Values 返回 nil，表示这个规范化键已经没有关联值。
    fmt.Printf("trace=%v accept=%v\n", header.Values("X-Trace-Id"), header.Get("Accept"))
}

在清理敏感字段、重建转发头或去掉旧协议字段时，这个“整项删除”语义很重要。删除之后再次调用 Get 会得到空字符串，调用 Values 会得到 nil；如果业务上需要区分“字段不存在”和“字段存在但值为空”，应在删除前自行检查 map 是否存在。

区分 Del、Get、Values 和直接 map 访问

四种操作的职责不同：Del 负责删除整项，Get 只读首值，Values 读取全部值，直接 map 访问则绕过方法层的键名规范化。工程代码可以用下面的表格快速判断：

Values 返回的是底层切片，不是副本；如果只是判断或读取，可以直接使用。如果要修改值集合，应该明确这是有意改变 header 的共享状态，而不是把返回切片当成隔离副本。

处理空 map 与非规范化键边界

对 nil 的 MIMEHeader 调用 Get 或 Values 是安全的，Del 也只是删除操作，不会因为没有目标项而返回错误。但如果要新增字段，仍然需要先初始化 map，因为给 nil map 赋值会触发运行时错误。

package main

import "net/textproto"

func removeOptional(header textproto.MIMEHeader, key string) textproto.MIMEHeader {
    // nil map 可以安全 Del；函数保持原引用，便于调用方继续使用。
    header.Del(key)
    return header
}

func addCanonical(header textproto.MIMEHeader, key, value string) textproto.MIMEHeader {
    // 新增前确保 map 已初始化，避免对 nil map 赋值。
    if header == nil {
        header = make(textproto.MIMEHeader)
    }
    header.Set(key, value)
    return header
}

另一个常见坑是混用直接 map 写入和标准方法：

package main

import (
    "fmt"
    "net/textproto"
)

func main() {
    header := make(textproto.MIMEHeader)
    // 直接写入小写键不会自动变成 Content-Type。
    header["content-type"] = []string{"text/plain"}

    // Del 会查找规范化后的 Content-Type，因此不会删除这个非规范化键。
    header.Del("content-type")
    fmt.Printf("direct=%v\n", header["content-type"])
}

如果确实需要兼容历史代码留下的非规范化键，应先统一数据来源，或显式删除原始键；更推荐从入口开始只使用 Add、Set 和 Del，让 map 始终保持规范化。

整理请求头清理的工程写法

清理逻辑通常应该集中在一个小函数中：先按业务规则列出需要移除的字段，再统一使用 Del，最后用 Values 或直接的存在性判断确认后续逻辑看到的状态。不要通过遍历 map 的字符串内容猜测大小写，也不要只删除 Get 返回的首值。

package main

import "net/textproto"

func stripForwardingFields(header textproto.MIMEHeader) {
    // 统一删除不应被转发的字段；Del 会一次移除该字段的全部值。
    for _, key := range []string{"X-Internal-Trace", "X-Forwarded-Secret"} {
        header.Del(key)
    }
}

如果字段来自 ReadMIMEHeader，它本身就会把键名规范化并按出现顺序收集值，直接调用 Del 即可。若 header 是跨模块传递的共享 map，还要约定谁负责修改，避免一个模块读取 Values 的同时另一个模块删除或替换同一项。

常见疑问

Del 会只删除第一个值吗？

不会。它删除 map 中这个规范化键对应的整个值切片，所以重复字段也会一起消失。

为什么 Del 之后直接访问原来的小写键还能读到值？

通常是因为这个键不是通过 Add 或 Set 写入的，而是直接以非规范化字符串写入 map。标准方法只会操作规范化键，二者在 map 中是不同的键。

Del 失败会返回 error 吗？

不会。Del 没有返回值；目标不存在时就是无操作。需要记录清理结果时，应在调用前或调用后检查键是否存在。

总结

textproto.MIMEHeader.Del 的关键不在于语法，而在于键名规范化和整项删除：标准方法会按 MIME 规则定位键，并删除该键的所有值。固定使用标准方法维护 header，读取时区分 Get 与 Values，只有在确实需要处理历史非规范化数据时才直接访问 map，就能避免“删了字段却还读得到”的问题。