最稳妥方式是直接用c.Request.Header.Get("X-User-ID")读取单个自定义Header，它大小写不敏感、返回string、不存在时为空字符串，不会panic；误用c.Request.Header["X-User-ID"]可能panic，c.GetHeader只是别名无额外逻辑，ShouldBindHeader要求结构体tag必须匹配规范化key（如X-User-Id而非X-User-ID）。
直接用 c.Request.Header.Get 读取单个自定义 Header 最稳妥
别绕弯子，c.Request.Header.Get("X-User-ID") 是最直接、最可靠的方式。它底层调用 Go 标准库的 http.Header.Get，大小写不敏感，不存在时返回空字符串，不会 panic。
常见错误包括：
- 误写成
c.GetHeader("X-User-ID")—— 这个方法确实存在，但只是c.Request.Header.Get的 alias，名字容易让人以为它有额外逻辑，实际没区别； - 误用
c.Request.Header["X-User-ID"]—— 返回的是[]string，如果 header 不存在会返回 nil 切片，直接取[0]可能 panic； - 拼错 key，比如写成
X-USER-ID或x-user-id—— 虽然Get大小写不敏感，但前提是 key 拼写合法（如含非法字符或空格会导致匹配失败）。
建议调试时先打印真实 header：fmt.Printf("%+v", c.Request.Header)，看 Nginx/Cloudflare/客户端到底把你的自定义 header 存成了什么形式（比如 X-User-Id 还是 X-User-ID）。
ShouldBindHeader 绑定结构体时标签必须匹配规范化 key
用结构体绑定自定义 header 看起来干净，但极易失败，核心问题在 tag 值必须和 http.Header 内部存储的 key 完全一致 —— 而不是你发请求时写的原始名。
Go 标准库会把 header key 规范化：首字母大写，其余小写，连字符后首字母也大写。例如：
-
authorization→Authorization -
x-api-version→X-Api-Version -
x-user-id→X-User-Id（不是X-User-ID）
所以结构体 tag 必须写成：
type HeaderReq struct {
Token string `header:"Authorization"`
Version string `header:"X-Api-Version"`
UserID string `header:"X-User-Id"` // 注意这里是 X-User-Id，不是 X-User-ID
}
否则 c.ShouldBindHeader(&h) 会静默失败（字段保持零值），且不报错 —— 因为底层就是调 http.Header.Get，key 不匹配就查不到。
多个同名 Header 怎么处理？Get 只返回第一个，要全部得用 map 查
HTTP 允许同一 header 出现多次（虽然少见），比如反向代理透传时可能叠加 X-Forwarded-For 或自定义 trace header。
c.Request.Header.Get("X-Custom") 永远只返回第一个值；如果你需要全部，得直接访问 map：
values := c.Request.Header["X-Custom"] // 类型是 []string
if len(values) > 0 {
// values[0] 是第一个，values[1] 是第二个……
}
注意：c.Request.Header 是 map[string][]string，key 是规范化后的 name（如 X-Custom），不是原始小写形式；遍历时 key 名也是规范化的。
别指望中间件里塞进 c 的“虚拟 header” 能被 Get 或 ShouldBindHeader 读到
Gin 的 c.Request.Header.Get 和 ShouldBindHeader 都只读原始 HTTP 请求头，完全不感知你在中间件里用 c.Set("key", value) 存的任意数据。
如果想统一处理“逻辑 header”（比如从 JWT 解析出 user_id 后当作 header 透传），要么：
- 在后续 handler 中手动从
c.MustGet("user_id")取； - 或者封装一个辅助函数，优先查真实 header，查不到再 fallback 到
c.MustGet； - 但不要试图改
c.Request.Header—— 它是只读映射，修改无效，且破坏 HTTP 语义。
真正容易被忽略的点是：header 名规范化发生在标准库解析阶段，不是 Gin 控制的；你看到的 c.Request.Header 已经是“整理过”的结果，任何调试都应以它为准，而不是凭印象猜 key 形式。
