冷启动时令牌桶初始满容导致突发流量穿透，需通过低频初始化、渐进扩容、保守模式、key归一化、清理闲置实例、禁用waitn裸调、暴露监控指标等策略实现平滑限流。
冷启动时令牌桶初始状态导致突发流量穿透
新服务刚上线或长时间空闲后，rate.NewLimiter 创建的桶默认是满的（burst 容量全在），第一波请求会瞬间耗尽所有令牌，等同于没限流。这不是 bug，而是令牌桶设计使然 —— 它本就允许突发，但冷启动阶段这个“突发”不是业务需要的，而是空转导致的误放行。
解决思路不是禁用突发，而是让桶“缓慢充能”，避免一上来就倾泻全部容量：
- 不用
rate.Every(100 * time.Millisecond)这类高频填充策略，改用低频 + 小 burst 初始化，例如rate.NewLimiter(rate.Limit(5), 5)（5 QPS，桶容量 5），再配合后台 goroutine 渐进扩容 - 启动时先用
time.AfterFunc(30*time.Second, func(){...})延迟提升桶容量：比如 30 秒后调用limiter.SetBurst(20)（需封装可变 burst 的 wrapper，因原生*rate.Limiter不暴露 set 方法） - 更稳妥的做法是启动后前 60 秒强制走“保守模式”：对所有请求调用
limiter.ReserveN(ctx, 1)并检查reservation.Delay()，若延迟 > 0，说明桶尚未稳定，主动返回 429 或加随机退避
sync.Map 缓存 limiter 实例时 key 失效不及时引发冷启动抖动
按 IP 或路径做细粒度限流时，常用 sync.Map 缓存 *rate.Limiter 实例。但新服务刚起来，大量不同 IP 首次访问会集中触发 sync.Map.LoadOrStore，而每个新实例都是满桶状态 —— 这批用户集体获得“免检通行权”，造成接口水位尖峰。
关键不是避免创建，而是控制创建节奏和初始容量：
- 不要直接用
c.ClientIP()作 key，先做归一化：IPv6 地址转为压缩格式，或只取前两段（如2001:db8::→2001:db8），减少 key 数量 - 初始化 limiter 时不给满 burst，统一设为 1～3，等该 key 第二次被访问时（说明有持续流量），再用 CAS 方式升级为正常容量（例如从 2 升到 20）
- 必须配清理逻辑：
time.AfterFunc或独立 goroutine 扫描sync.Map，对 lastAccess 时间 > 120s 的 key 执行Delete；否则冷启动后残留的空闲 limiter 会持续占内存，且下次命中仍用旧桶
Allow() 与 WaitN() 混用导致冷启动期间请求阻塞不可控
有些中间件在非冷启动场景下用 Allow() 快速失败，但为了“平滑”又在启动初期悄悄切到 WaitN(ctx, 1) —— 这反而更危险：一旦上游没传带 timeout 的 ctx，或者 timeout 设置过长（如 5s），请求就会卡死，连接堆积，触发级联超时。
冷启动期的等待策略必须显式、可观察、可中断：
- 永远不要在 handler 里裸调
limiter.WaitN(context.Background(), n)，至少用context.WithTimeout(c.Request.Context(), 200*time.Millisecond) - 如果要用排队策略，优先选
ReserveN()：它不阻塞，返回*rate.Reservation，你可以判断reservation.OK()和reservation.Delay()，再决定是放行、重试还是降级返回 - 对登录、下单等关键路径，冷启动阶段建议关闭排队，只保留
Allow()+ 固定低限流阈值（如 2 QPS），等监控确认流量平稳后再切回正常策略
没有监控埋点导致冷启动效果无法验证
限流中间件加了，但没人知道冷启动那几分钟到底压没压住。最常漏掉的是两个指标：桶当前剩余令牌数、每秒新建 limiter 实例数。
这两个值必须实时暴露，否则你无法区分是策略失效，还是只是“看起来像失效”：
- 用
prometheus暴露rate_limiter_burst{ip="xxx"}和rate_limiter_tokens_remaining{ip="xxx"}，注意后者需通过limiter.ReserveN预占再释放来估算，不能直接读（rate.Limiter不提供原子读接口） - 在
sync.Map.LoadOrStore分支里打日志或计数器：limiter_created_total{reason="cold_start"}，当该指标在启动后 10 秒内突增 > 100，就是冷启动抖动信号 - 别依赖
X-RateLimit-Remaining响应头做判断——它只反映单次请求后的剩余，无法体现桶的长期充能趋势
冷启动平滑不是加个 sleep 或 delay 就完事，本质是控制令牌生成节奏、限制新桶扩散速度、并让每个决策可测量。最容易被忽略的，是把“桶满了”当成健康信号 —— 其实那恰恰是风险起点。
