在 Gin 中应使用 Use() 注册自定义请求头校验中间件，校验逻辑须置于 c.Next() 前，通过 c.Request.Header.Get() 获取头字段（注意大小写），失败时调用 c.AbortWithStatusJSON() 终止流程，避免硬编码密钥、忽略代理透传及 body 重放等生产问题。
如何在 Gin 框架中编写请求头校验中间件
直接用 Gin 的 Use 注册中间件是最轻量、最可控的方式。别碰全局注册或依赖第三方插件，校验逻辑简单时自己写几行更稳。
常见错误是把校验写在路由 handler 里，导致每个接口重复写；或者用 gin.BasicAuth() 这类现成函数硬套，结果发现它只认 Authorization 头、不支持自定义字段（比如 X-Api-Key 或 X-Request-ID）。
- 校验逻辑必须放在
c.Next()前，否则请求已向下传递，再拦就晚了 - 用
c.Request.Header.Get("X-Api-Key")取值，注意大小写不敏感但 Go 默认按原样匹配，建议统一转小写再比对 - 校验失败必须显式调用
c.AbortWithStatusJSON(401, ...)，否则会继续执行后续 handler - 若需兼容空值或可选头，别用
== ""判空，改用len(c.Request.Header.Get("X-Api-Key")) == 0
func AuthHeaderMiddleware() gin.HandlerFunc {
return func(c *gin.Context) {
key := c.Request.Header.Get("X-Api-Key")
if key == "" {
c.AbortWithStatusJSON(http.StatusUnauthorized, gin.H{"error": "missing X-Api-Key"})
return
}
if key != "secret-123" { // 实际应查 DB 或 Redis
c.AbortWithStatusJSON(http.StatusForbidden, gin.H{"error": "invalid API key"})
return
}
c.Next()
}
}
为什么不能直接用 net/http 的 ServeMux 做头校验
因为 Gin 是基于 net/http 构建的，但它的上下文（*gin.Context）和路由匹配机制与原生 http.Handler 不兼容。你写一个标准 http.HandlerFunc，传给 gin.Engine.Use() 会编译报错 —— 类型不匹配。
典型错误信息：cannot use myHandler (type func(http.ResponseWriter, *http.Request)) as type gin.HandlerFunc。
立即学习“go语言免费学习笔记（深入）”；
- 必须用
gin.HandlerFunc类型，即func(*gin.Context) - 如果已有
net/http风格的校验函数，得包一层：用c.Writer和c.Request显式透传 - 不要试图在
http.ServeMux上做校验再转发到 Gin，这会破坏 Gin 的中间件链、日志、panic 恢复等机制
多个请求头联合校验的写法要点
实际项目常要同时检查 X-Api-Key + X-Timestamp + X-Signature，且有顺序依赖（比如时间戳过期就不用验签名）。这时候别堆 if 嵌套，用早返回更清晰。
- 先取所有头，统一做非空判断，避免重复调用
Get() - 时间戳建议用
time.Parse(time.RFC3339, tsStr)，别用strconv.ParseInt直接转 Unix 时间戳 —— 容易忽略时区和精度问题 - 签名验证务必在最后，且要确保原始 body 可重放（Gin 默认读一次就丢，需提前用
c.Request.Body缓存或用c.ShouldBindBodyWith()） - 错误响应尽量保持一致字段名，比如都用
code和message，方便前端统一处理
生产环境必须绕开的坑
本地测试能跑通，上线后突然 401，大概率是反向代理（Nginx / ALB）没透传自定义头。Go 的 http.Request.Header 默认只保留标准头，X- 开头的头需要 Nginx 显式放开。
- Nginx 配置里漏了
proxy_set_header X-Api-Key $http_x_api_key;，会导致 Go 收不到该头 - 某些云服务（如 AWS API Gateway）默认过滤掉未声明的
X-头，需在集成请求映射模板中手动添加 - 用
c.Request.RemoteAddr做 IP 校验时，若前面有代理，实际拿到的是代理 IP 而非真实客户端 IP，得从X-Forwarded-For解析并信任可信跳数 - 校验逻辑里别直接写死密钥字符串，至少从
os.Getenv("API_KEY_SECRET")读，否则镜像一发布就全暴露
头校验看着简单，真正麻烦的是边界场景：代理透传、时钟漂移、body 重放、密钥轮换。写完一个中间件，先压测再上，别信“本地能过”。
