Go Header.Get 读不到手动写入的请求头怎么办

Go 里 Header.Get 读不到手动写入的请求头，最常见的原因不是大小写，而是写入方式或读取对象不对。推荐用 Header.Set、Header.Add 写入，再从同一个 Header 实例读取；如果代码直接执行 h["x-trace-id"] = []string{"..."}，这个非规范化键可能不会被 Get("X-Trace-Id") 找到。

先确认 Header.Get 的读取规则

http.Header 本质上是 map[string][]string。标准库会把请求头键按“首字母和连字符后的字母大写、其余字母小写”的形式规范化，例如 x-trace-id 会变成 X-Trace-Id。Get 对传入参数执行同样的规范化，并返回第一个值；没有值时才返回空字符串。

因此，下面两次读取都可以得到同一个值：

h := make(http.Header)
h.Set("X-Trace-Id", "req-20260906")

fmt.Println(h.Get("X-Trace-Id")) // 输出 req-20260906
fmt.Println(h.Get("x-trace-id")) // 仍然输出 req-20260906

如果这段代码返回空，优先检查 h 是否就是写入时的那个对象、键名里是否混入了空格，以及是否在读取前把切片设成了空切片。不要先把问题归因于大小写。

用 Header.Set 或 Header.Add 写入请求头

业务代码写单值请求头时使用 Set 最稳妥，它会替换该键已有的全部值；同一个请求头需要保留多个值时使用 Add。两者都会先规范化键名。

package main

import (
	"fmt"
	"net/http"
)

func main() {
	req, err := http.NewRequest(http.MethodGet, "https://api.example.test/items", nil)
	if err != nil {
		panic(err)
	}

	// Set 适合唯一值：重复设置会覆盖旧的 X-Trace-Id。
	req.Header.Set("x-trace-id", "req-20260906")
	// Add 适合需要保留多个值的字段；Get 只返回第一个值。
	req.Header.Add("X-Debug", "cache")
	req.Header.Add("x-debug", "timing")

	fmt.Println(req.Header.Get("X-Trace-Id")) // req-20260906
	fmt.Println(req.Header.Get("X-Debug"))    // cache
	fmt.Println(req.Header.Values("X-Debug")) // [cache timing]
}

这里的 Get 不是“把所有值拼接后返回”，它只取第一个；需要判断是否追加成功，用 Values 看完整切片。对于需要覆盖的追踪 ID、租户 ID、授权信息，通常不要误用 Add，否则旧值可能继续保留。

排查读错 Request 和 Response 的位置

请求头和响应头都使用 http.Header，这很容易让排查方向跑偏。客户端发出的请求头在 req.Header；服务端准备返回给客户端的响应头在 w.Header()；客户端收到的响应头则在 resp.Header。给响应写了值，再从请求对象读取，当然会得到空字符串。

func handler(w http.ResponseWriter, r *http.Request) {
	// 从客户端请求读取：请求头属于 r.Header。
	traceID := r.Header.Get("X-Trace-Id")
	if traceID == "" {
		traceID = "generated-trace"
	}

	// 写回客户端：响应头属于 w.Header()，不是 r.Header。
	w.Header().Set("X-Trace-Id", traceID)
	w.WriteHeader(http.StatusNoContent)
}

func readResponse(resp *http.Response) string {
	// 客户端收到的响应头要从 resp.Header 读取。
	return resp.Header.Get("X-Trace-Id")
}

若是 http.Client.Do 之后读取服务端返回的字段，看 resp.Header；若是进入处理器后读取客户端带来的字段，看 r.Header。先写一行日志打印对象和键，再检查值，比盲目更换大小写更快。

用 Values 和直接 map 访问定位异常

当 Get 仍然为空时，用 Values 判断规范化键下是否真的有值，再用直接 map 访问确认是否存在一个非规范化键。直接 map 访问只适合诊断，不应作为普通写入方式。

func debugHeader(h http.Header, key string) {
	// Values 使用和 Get 相同的规范化规则，并返回全部值。
	fmt.Printf("canonical values: %#v\\n", h.Values(key))

	canonical := http.CanonicalHeaderKey(key)
	// 直接 map 访问只用来发现手动写入的异常键。
	fmt.Printf("canonical map value: %#v\\n", h[canonical])
	fmt.Printf("raw lower-case value: %#v\\n", h["x-trace-id"])
}

如果 h["x-trace-id"] 有值，但 h.Values("X-Trace-Id") 为空，说明之前的代码绕过了 Set 或 Add。修复时把写入改为 h.Set("X-Trace-Id", value)，不要只在读取处加多个大小写分支。

还要留意两个边界：var h http.Header 是 nil map，读取会安全返回空，但写入会 panic；另外，Set(key, "") 得到的是一个存在但值为空的键，Get 仍然返回空，不能仅凭返回值判断“键不存在”。

常见问题

Header.Get 对大小写敏感吗？

按标准库的规范化规则，它对合法请求头键大小写不敏感；如果直接 map 写入了非规范化键，才可能出现看似大小写相关的空值。

Header.Set 和 Header.Add 怎么选？

唯一值用 Set，多值字段用 Add。读取多个值用 Values，不要期待 Get 返回完整列表。

为什么直接给 Header 赋值会 panic？

未初始化的 nil map 只能读不能写。先用 make(http.Header)，或者通过 http.NewRequest 创建带可写 Header 的请求。