限流模块应置于 internal/middleware/ratelimit/ 独立包中，通过依赖注入集成到网关核心结构体，按业务维度复用 rate.limiter 实例，避免全局单例或请求级新建导致失效，并需校验 key、定期清理、设容量上限、优先使用 wait(ctx) 且支持降级。
限流模块不能做成“全局单例”或“每个请求 new 一个”，必须按业务维度复用 rate.Limiter 实例，否则限流完全失效。
限流模块该放在哪一层？
别塞进 main 包或 handler 闭包里——这会导致实例生命周期错乱。正确位置是：
-
internal/middleware/ratelimit/：独立包，只暴露NewRateLimiterMiddleware()和配置结构体 - 依赖注入到网关核心结构体（如
Gateway或Router），而非直接 import 使用 - 若用 Gin，中间件函数应接收预构建的限流器 map，不自己 new
如何避免 sync.Map 泛滥和内存泄漏？
攻击者构造随机 X-User-ID 会让 sync.Map 无限膨胀。必须加约束：
- key 校验：只接受 32 字符内、
^[a-zA-Z0-9_]+$的用户 ID；IP 地址需先做可信解析（优先取X-Real-IP，X-Forwarded-For需校验信任链） - 自动清理：用
time.AfterFunc或后台 goroutine 定期扫描，删除 5 分钟未访问的*rate.Limiter - 容量上限：当
sync.Mapsize > 10000 时，拒绝新 key 并记录告警，防止 OOM
Wait(ctx) 为什么比 Allow() 更适合 API 网关？
API 网关要保证 QPS 稳定、延迟可控，Allow() 无法满足：
-
Allow()只查当前令牌数，返回true后可能被其他 goroutine 瞬间抢走，导致实际超限 -
Wait(ctx)是阻塞排队逻辑，真正实现“等位”，且自动响应ctx.Done()—— 必须传入r.Context()，不能用context.Background() - 高并发下优先用
WaitN(ctx, n)（比如大模型批量请求），减少唤醒开销
分布式部署时怎么保持限流一致性？
单机 rate.Limiter 在多实例下天然失效，但别急着全切 Redis：
- 先评估场景：若只是“每用户每秒 5 次”，单机限流 + 一致性哈希路由（如按 user_id mod 实例数）已足够，成本低、延迟低
- 真需全局精确限流（如“全站 /api/pay 总 QPS ≤ 1000”），再上 Redis + Lua，脚本必须包含
INCR、EXPIRE、阈值判断三步原子执行 - Redis 不可用时要有降级：配置 fallback mode（如只限 IP 粒度，或临时关闭限流并告警）
最易被忽略的是限流维度与业务语义的对齐——比如把“支付接口限流”绑在路径前缀上，却没考虑同一用户跨设备发起多个支付请求时的实际冲击；或者用了 X-Forwarded-For 却没校验代理可信性，结果所有流量被当成同一个 IP。限流不是加个中间件就完事，它得嵌进业务规则里跑。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
