直接用golang.org/x/time/rate实现Gin限流需避免错用、漏配、不降级三大陷阱：全局复用或按key（IP/用户）缓存于sync.Map并清理，Wait必须带超时，Redis分布式限流须用Lua原子操作，健康接口需跳过，真实IP需正确提取且兜底。
限流不是加个 rate.Limiter 就完事——错用、漏配、不降级，三者任一都会让整套防护形同虚设。
rate.Limiter 实例不能在 handler 里 new
每次请求都调 rate.NewLimiter(10, 20)，等于给每个请求发一个独立桶。100 并发 = 100 个桶各自放行 10 QPS，实际吞吐直接飙到 1000 QPS。
- 全局复用：网关层总限流，直接定义
var globalLimiter = rate.NewLimiter(rate.Every(100*time.Millisecond), 10) - 按 key 复用：用户/IP/路径维度限流，必须用
sync.Map缓存，key 命名如"user:" + userID或"ip:" + realIP - 别忘了清理：对每个新 key 启动
time.AfterFunc(30 * time.Minute, func() { syncMap.Delete(key) })，否则内存持续上涨 - Gin 中取真实 IP 要配
engine.TrustedProxies，否则r.RemoteAddr是 Nginx 内网地址，限流对象全错
HTTP 中间件里必须用 Wait(ctx)，且带超时
Allow() 是非阻塞的，返回 false 后若继续执行业务逻辑，就等于没限流。而 Wait(ctx) 不设超时会永久挂起 goroutine，引发泄漏。
- 必须从请求上下文派生：
ctx := r.Context()，再套一层context.WithTimeout(ctx, 100*time.Millisecond) - 错误处理要立即中断：
if err := limiter.Wait(ctx); err != nil { http.Error(w, "", http.StatusTooManyRequests); return } - 健康检查路径（如
/health）必须提前跳过，否则 K8s probe 失败导致滚动重启 - 想返回标准限流头（
X-RateLimit-Remaining等），得用limiter.ReserveN(now, 1)预占再算，别直接减计数——并发下不准
多实例部署必须用 Redis + Lua，别信“本地缓存同步”
5 个 Pod 各跑一个 rate.Limiter(100, 200)，入口总流量就是 500 QPS。这不是 bug，是设计使然——它本就只管单机。
立即学习“go语言免费学习笔记（深入）”；
- Redis 方案必须用 Lua 脚本封装
INCR+EXPIRE+GET，拆成多次网络调用必然竞态 - 推荐滑动窗口：用
ZSET存时间戳，ZADD+ZCOUNT+ZREMRANGEBYSCORE三步原子执行 - key 要细粒度：
"limit:svc:user-get:12345"，而不是笼统的"user-get" - 连接池
PoolSize至少设为 50，Timeout控制在 100ms 内，超时建议直接放行（fail-open），避免限流逻辑自身成瓶颈
真正难的不是写限流逻辑，而是 key 提取和故障降级
限流失效往往不出在算法，而出在细节：X-Real-IP 拿不到真实地址、配置热重载时 sync.Map 正被读又被写、Redis 故障后没 fallback —— 这些不处理好，再准的算法也白搭。
- key 提取要兜底：
realIP := getRealIP(r); if realIP == "" { realIP = "unknown" } - 配置热加载需用双 map + 原子指针切换，禁止 reload 时直接写原 map
- Redis 不可用时，应降级为单机
rate.Limiter或直接放行，不能卡死或 panic - 别忽略时钟漂移：分布式环境下，各节点时间差 >100ms 就可能让滑动窗口统计失真，关键服务建议 NTP 对齐
