Gin中间件是记录行为流水的首选位置，因请求全生命周期可控且不侵入业务逻辑；直接在handler写日志易漏panic、超时等边缘情况，而Use()中间件可统一捕获Request、Writer.Status()及耗时、IP等字段。
为什么 Gin 的中间件是记录行为流水的首选位置
因为用户请求的完整生命周期都在中间件里可控，且不会侵入业务逻辑。直接在 handler 里写日志容易漏掉 panic、超时、重定向等边缘情况；而 Gin 的 Use() 中间件能统一捕获 c.Request 和 c.Writer.Status()，还能拿到耗时、IP、User-Agent 等关键字段。
常见错误是把日志逻辑塞进某个具体路由 handler，结果登录、文件上传、健康检查接口的日志格式不一致，后期查问题要拼凑多份日志。
- 必须用
c.Next()包裹实际处理逻辑，否则c.Writer.Status()永远是 0 - 别在中间件里调
c.Abort()后还继续写日志——状态码可能已失效 - 如果用了
gin.Recovery()，确保你的日志中间件注册在它前面，否则 panic 时拿不到响应状态
如何提取真实客户端 IP 而不是反向代理的内网地址
Gin 默认的 c.ClientIP() 在 Nginx 或 Cloudflare 后会返回 127.0.0.1 或代理 IP。必须显式配置信任的代理网段，并从特定 header 解析。
典型场景：服务部署在 Kubernetes Ingress 后，或前端套了 CDN。这时 X-Forwarded-For 可能被伪造，不能无条件信任。
立即学习“go语言免费学习笔记（深入）”；
- 启动时设置信任代理：
router.ForwardedByClientIP = true，再调用c.ClientIP()才有效 - 手动解析更稳妥：
c.GetHeader("X-Real-IP")（Nginx 配置proxy_set_header X-Real-IP $remote_addr;） - Cloudflare 用户应优先读
X-Forwarded-For最右非私有 IP，但需校验Cf-Connecting-Ipheader 是否存在且匹配签名
怎样避免日志中泄露敏感参数（如 password、token）
直接打印 c.Request.URL.RawQuery 或 c.PostForm("password") 是高危操作。Gin 不会自动过滤，得自己做白名单或脱敏。
常见错误是用正则全局替换所有 “password=xxx”，结果把 password_reset_token 也抹掉，或漏掉 JSON body 里的字段。
- 对 query string 做 key-value 解析后，只记录白名单参数：
url.Values{"uid": ..., "action": ...} - POST/PUT 的 JSON body 要先
json.Unmarshal再删敏感字段，不要用字符串替换 - 敏感字段名列表建议硬编码：
[]string{"password", "token", "auth_key", "card_no"}，避免正则误杀 - 如果用了
c.ShouldBindJSON(&req)，就在结构体 tag 里加json:"-" gorm:"-" log:"omit"标记，后续反射跳过
性能瓶颈在哪？日志写入方式怎么选
同步写文件或 stdout 在高并发下会阻塞 HTTP 处理协程，尤其当磁盘慢或日志量大时，c.Next() 返回延迟明显。这不是 Gin 的问题，而是 I/O 模式选择失误。
容易被忽略的是：即使用了异步日志库（如 zap），如果没配 buffer 或队列满时丢弃策略，照样拖垮接口。
- 别用
log.Printf直接打屏——它锁全局 mutex，QPS 过千就明显卡顿 - zap 的
zapcore.Lock(zapcore.AddSync(...))必须配zapcore.NewMultiWriteSyncer+ 文件轮转，否则单文件写死 - 高频行为（如点击、曝光）建议先写 Kafka 或本地 ring buffer，再异步落盘；低频操作（如支付、登出）可同步记
- 注意
c.Request.Body只能读一次，想记 body 又要 bind，得先用c.Request.Body = ioutil.NopCloser(bytes.NewReader(data))回填
真正难的不是记下哪几行字段，而是让日志既不丢、不慢、不泄密，又能在凌晨三点快速定位是哪个用户、哪个设备、哪个版本触发了异常路径。这需要每条日志自带 trace_id，且中间件和业务层共用同一上下文传递机制。
