Go Header.Set 与 Add 造成重复字段的差异

Go 里响应头出现重复字段，通常不是 HTTP 自动“复制”了一份，而是同一个规范化键对应了多个值。判断 Header.Set 和 Header.Add 的关键只有一句：单值字段用 Set，确实允许多值的字段才用 Add。如果重复值没有业务意义，就先查写入来源，再决定是否 Del 后重新设置。

Header 的键值模型决定了重复字段是否成立

net/http.Header 的定义是 map[string][]string。也就是说，一个键天然可以关联多个值。Go 会对常见键名做规范化，调用时大小写不同并不会创建两个逻辑字段。

这也是重复问题容易被忽略的地方：下面的两次写入命中了同一个键，第二次不是“另一个 Content-Type”，而是把同一个键的值切片改成了两个元素。

package main

import (
    "fmt"
    "net/http"
)

func main() {
    h := make(http.Header)

    // Set 适合单值字段：再次设置会替换旧值。
    h.Set("Content-Type", "application/json")
    h.Set("content-type", "text/plain")

    // Values 展开完整切片；Get 只会返回第一个值。
    fmt.Println(h.Values("Content-Type"))
    fmt.Println(h.Get("Content-Type"))
}

这个示例的重点不是输出文本，而是检查方式：只调用 Get 可能让你误以为字段只有一个值。要确认是否发生了无意重复，优先看 Values，必要时直接检查规范化键对应的切片。

Set 覆盖单值，Add 保留多值

Set 的语义是把某个键的值设置成只有一个元素；Add 的语义是把新值追加到原有切片。选择方法时不要看字段名字是否常见，要看协议和业务是否允许多个值。

func setJSONHeader(h http.Header) {
    // 单值字段先删除再设置，明确清理前一个来源留下的状态。
    h.Del("Content-Type")
    h.Set("Content-Type", "application/json")
}

func addCookies(h http.Header, cookies ...string) {
    for _, cookie := range cookies {
        // Set-Cookie 允许多个独立值，因此使用 Add 保留每一项。
        h.Add("Set-Cookie", cookie)
    }
}

这里的边界很重要：Del 加 Set 不是所有字段的通用“去重器”。它适合你明确知道字段应该只有一个值的情况；对允许多值的字段强行覆盖，反而会丢数据。

把重复字段当成输入策略问题排查

我处理这类问题时，会先列出一个字段的所有写入点：默认响应头、中间件、错误分支、重试分支和最终发送前的补充逻辑。看到同一个字段在两个分支里都使用 Add，才有理由把它标记为重复来源；不要只盯着最后一行代码。

还要区分“多个头行”和“一个键的多个值”。Go 的容器层先保存值切片，真正写出时由 HTTP 头编码规则决定表现形式。排查阶段因此应该记录键名、值数量、写入位置和字段协议，而不是只复制浏览器里看到的一行文本。

• 单值字段：检查初始化是否使用 Set，业务分支是否又用 Add。
• 多值字段：确认每个值是否有独立语义，不能因为“看起来重复”就覆盖。
• 读取字段：调试时用 Values，不要用 Get 的首值代替完整状态。

发送前的四项检查清单

1. 确认键名：不同大小写是否其实指向同一个规范化键。
2. 确认协议：这个字段允许多值，还是业务上必须保持单值。
3. 确认来源：初始化、中间件和业务分支是否各写了一次。
4. 确认读取：用 Values 检查完整值数量，再决定是否需要清理。

这样处理后，Set 与 Add 就不再是“哪个函数更安全”的选择题，而是字段数据模型和写入责任的选择题。单值字段强调覆盖，多值字段强调保留，重复字段则回到来源链路解决。

常见问题

Header.Set 会不会把所有同名字段都合并成一个值？

它会把 Go 容器中该键的值切片替换为单元素切片；这适合单值策略，但不代表所有协议字段都应该被覆盖。

为什么 Header.Get 看不到重复值？

Get 返回第一个关联值。排查重复写入要改用 Values，或者检查规范化键对应的完整切片。

多个 Set-Cookie 应该用 Set 还是 Add？

如果每个 Cookie 都需要独立发送，应使用 Add；用 Set 会覆盖前面已经写入的 Cookie。