Go 的 net/http Header 操作大小写不敏感但写入时保留原始大小写：读取应始终用 Header.Get()（自动标准化键名），写入单值头用 Set()、多值头用 Add()，且必须在 WriteHeader() 或首次 Write() 前完成。
Go 的 net/http 包对 Header 的操作是大小写不敏感但写入时保留原始大小写的——这是最常被误解的起点，直接决定你能否正确读取第三方服务返回的自定义头（比如 X-Request-ID）或避免被反爬拦截。
Header 读取：用 Header.Get() 而不是直接访问 map
Header 类型本质是 map[string][]string，但直接读 req.Header["X-Forwarded-For"] 可能拿不到值，因为键名会被规范化为首字母大写、其余小写（X-Forwarded-For → X-Forwarded-For，但 x-forwarded-for 或 X-FORWARDED-FOR 也能命中）。而 Header.Get() 内部做了标准化处理，更安全。
常见错误现象：本地测试时用 curl 加 -H "x-custom: abc"，代码里却写 req.Header["X-Custom"] 为空；换成 req.Header.Get("X-Custom") 或 req.Header.Get("x-custom") 都能拿到。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 永远优先用
Header.Get(key)读单值头（如Content-Type、Authorization），它自动合并同名多值并用逗号分隔 - 需要获取所有同名头原始值（比如多个
Set-Cookie）时，才用Header.Values(key) - 不要依赖
req.Header[key]的 map 访问，它不触发规范化，且可能 panic（当 key 不存在时返回 nil slice，但若误判为非 nil 会出错）
Header 写入：用 Header.Set() 和 Header.Add() 区分覆盖与追加
Header.Set(key, value) 会**清空所有同名头再写入一个新值**；Header.Add(key, value) 是**追加**，适合 Cookie、Warning 这类允许多值的头。混淆两者会导致下游服务收不到预期的多个 Accept 或漏掉 Set-Cookie。
使用场景举例：代理请求时透传上游的多个 X-Forwarded-For 值，必须用 Add()；设置 Content-Type 则必须用 Set()，否则可能残留旧值引发 MIME 解析失败。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 写单值头（
Content-Type、Location、Cache-Control）→ 用Set() - 写多值头（
Set-Cookie、WWW-Authenticate、自定义重复头）→ 用Add() - 不要用
Header[key] = []string{...}直接赋值，这绕过规范化逻辑，且在某些 HTTP/2 场景下被忽略
Case-Sensitive 写入陷阱：为什么 X-My-Header 变成了 X-My-Header 但 x-my-header 也生效？
Go 的 Header 在存储时会将键名标准化为“每个单词首字母大写”，例如 x-forwarded-for → X-Forwarded-For，content-type → Content-Type。但这个过程是**只读标准化**：你用 Set("x-custom", "123")，实际存的是 X-Custom: 123；后续 Get("x-custom") 或 Get("X-Custom") 都能取到。
容易踩的坑：
-
前端发来
X-API-Key，后端用req.Header.Get("x-api-key")没问题，但若你手动拼接字符串做日志（如"header: " + key），显示的仍是原始小写键名，容易误导排查 - 某些老旧中间件（如部分 nginx 配置）严格匹配头名大小写，此时需确保客户端发送的原始格式符合预期，Go 侧无法强制“还原”原始大小写
-
Header.Clone()会复制标准化后的键名，不会保留原始输入大小写
ResponseWriter.WriteHeader() 后不能再修改 Header
一旦调用 http.ResponseWriter.WriteHeader(statusCode) 或首次调用 Write()（隐式触发 200 状态），Header 就被冻结。此时再调用 w.Header().Set("X-Log-ID", "abc") **完全无效**，也不会报错——这是线上调试中最难发现的 Header 丢失原因。
性能影响：Header 必须在响应体写入前完成设置，否则 Go 会丢弃修改并静默降级为 HTTP/1.1 的 chunked 编码，影响 CDN 缓存判断和浏览器解析。
实操建议：
立即学习“go语言免费学习笔记（深入）”；
- 把 Header 设置逻辑放在 handler 开头，或封装进 middleware 中统一处理
- 避免在模板渲染、数据库查询之后才设置
Content-Disposition或ETag - 启用
http.Server{Handler: http.HandlerFunc(...), }时，可借助ResponseWriter的包装类型（如responsewriter.Wrap）做 Header 写入检测，但生产环境更推荐静态检查 + 单元测试断言
Header 的“大小写不敏感读、标准化存、写入时机敏感”这三点，比语法本身更容易导致线上问题。尤其在代理、鉴权、日志透传等场景，少一次 Get() 多一次 Set()，就可能让整个链路的 trace ID 断掉。
