c.header()必须在响应体写入前调用，否则头信息会被忽略或panic；推荐在统一中间件中预存调试字段并末尾统一设置，避免硬编码；空value时c.header()自动删除头，而c.writer.header().set()会设为空字符串，多值头需用add()。
直接用 c.Header() 设置调试头，但要注意时机
必须在响应体写入前调用 c.Header()，否则会 panic 或被忽略。Gin 的 c.Writer 是惰性写入，一旦调用 c.JSON()、c.String() 等方法，底层 http.ResponseWriter 就可能已提交头信息。
常见错误现象：头没生效、日志里看到 http: superfluous response.WriteHeader call 错误、部分头（如 Content-Type）被覆盖。
- ✅ 正确顺序：先设头 → 再写响应体
- ❌ 错误顺序：先
c.JSON(200, data)→ 再c.Header("X-Debug-ID", "abc123") - ⚠️ 特别注意：如果用了
c.Render()或自定义Writer中间件，头设置逻辑可能被绕过
需要动态值时，避免在中间件里硬编码 c.Header()
比如想加请求 ID、处理耗时、路由名等动态调试信息，不能只在某个 handler 里写死 c.Header("X-Request-ID", "xxx") —— 这样维护成本高且易漏。
推荐在统一中间件中注入，但要确保它在所有业务 handler 之前执行，并且不干扰后续逻辑：
- 用
c.Request.Context().Value()或c.Set()预存调试字段（如"debug_info"map） - 在中间件末尾统一调用
c.Header()，例如：c.Header("X-Process-Time", fmt.Sprintf("%.2fms", elapsed)) - 不要在中间件里调用
c.Abort()后还设头，此时响应流程已中断
c.Header() 和 c.Writer.Header().Set() 的行为差异
两者最终都操作同一个 http.Header 对象，但语义和容错性不同：
-
c.Header("X-Trace-ID", id)：自动跳过空值，value 为空字符串时会删除该头 -
c.Writer.Header().Set("X-Trace-ID", id)：严格按标准库行为，value 为空时设为空字符串头（某些代理/客户端会拒绝） - 若需多值头（如
Access-Control-Allow-Headers），必须用c.Writer.Header().Add()，c.Header()总是覆盖 - 对大小写不敏感的头名（如
content-type），Gin 内部会规范化为首字母大写，但建议统一用 PascalCase 写法
调试头上线后容易被忽略的关键点
本地开发加了 X-Debug-* 头很爽，但上线后常因以下原因失效：
- Nginx / ALB 等反向代理默认过滤掉非标准头，需显式配置
proxy_pass_request_headers on;或白名单 - Kubernetes Ingress 控制器（如 nginx-ingress）可能 strip 掉带下划线的头名，改用短横线（
X-Debug-Id而非X-Debug_ID） - 浏览器开发者工具 Network 标签页默认隐藏响应头中的自定义字段，需右键表头勾选“Headers”列
- 如果启用了 gzip 压缩，某些旧版中间件会在压缩后才写头，导致调试头被压进 body 流——务必确认你用的是 Gin 原生
c.JSON()（它自带 gzip 支持且头写入正确）
