c.Header() 必须在任何响应体写入操作（如c.JSON）前调用，否则失效或panic；正确做法是全局中间件中预存调试信息、c.Next()后统一设头，并注意执行顺序与空值/多值头差异。
c.Header() 必须在写响应体前调用，否则失效或 panic
常见错误是 handler 里先调用 c.JSON(200, data)，再补一句 c.Header("X-Debug-ID", "abc123")——这时头已经随响应体一起提交，c.Header() 不会生效，还可能触发 http: superfluous response.WriteHeader call 错误。
根本原因是 Gin 的 c.Writer 是惰性写入：一旦调用 c.JSON、c.String、c.Render 等方法，底层 http.ResponseWriter 就可能已发送状态码和头信息。后续再设头，要么被忽略，要么 panic（取决于是否已 flush）。
- ✅ 正确顺序：所有
c.Header()调用必须出现在任何响应体写入操作之前 - ⚠️ 特别注意：如果用了自定义
Writer中间件（比如压缩、加密 wrapper），它可能提前触发写入，导致头设置逻辑被绕过 - ❌ 不要依赖
c.Abort()后设头——此时响应流程已中断，设头无意义
用中间件统一注入调试字段，避免硬编码和遗漏
把 c.Header("X-Process-Time", "12.34ms") 写在每个 handler 里，既难维护又容易漏。更可靠的方式是在一个全局中间件中预存调试数据，末尾统一设头。
推荐做法是：在中间件开头记录起始时间、生成 trace ID、提取路由名等；用 c.Set("debug_info", debugMap) 存入上下文；在中间件末尾（c.Next() 之后）读取并设头。
- 用
c.Set()而非c.Request.Context().Value()：前者更轻量，且生命周期与请求一致，无需类型断言 - 动态值（如耗时）必须在
c.Next()之后计算，否则拿不到真实处理时长 - 不要在中间件里对
c.Abort()的请求再设头——这类请求通常走错误响应路径，应由错误处理逻辑单独控制
c.Header() vs c.Writer.Header().Set()：空值行为和多值头差异
两者最终都操作同一个 http.Header 对象，但语义不同，尤其在边界场景下表现不一。
-
c.Header("X-Trace-ID", id)：value 为空字符串时，自动删除该 header；适合调试 ID 这类“有则设、无则删”的场景 -
c.Writer.Header().Set("X-Trace-ID", id)：严格按标准库行为，value 为空时仍会写入空字符串 header；某些反向代理或客户端会拒绝空值头 - 多值头（如
Access-Control-Allow-Headers）必须用c.Writer.Header().Add()；c.Header()总是覆盖，无法追加 - 头名大小写不敏感，Gin 内部会规范化为首字母大写（如
content-type→Content-Type），建议代码里统一用 PascalCase 写法
调试头应在日志中间件之后、业务 handler 之前注册
调试中间件的执行顺序很关键。它需要能读到完整请求信息（如 path、method），又要确保在业务 handler 修改响应前完成头设置。
典型注册顺序应为：Logger → RequestID → DebugHeader → Recovery → 业务 handler。其中 DebugHeader 必须在 Recovery 之后，否则 panic 恢复路径下的错误响应也会被注入调试头（可能暴露内部信息）。
- 不要把调试中间件放在
Recovery前面——那样 panic 后的 500 响应也会带调试头 - 如果用了
gin.Default()，它默认包含Logger和Recovery，需显式替换为自定义链：用gin.New()+ 手动Use() - 调试头内容尽量精简：只放 trace_id、process_time、route 等必要字段；避免塞入原始请求体或敏感上下文
