API 网关限流的三层设计：从单机到分布式的取舍

限流是网关侧最古老的职能，但「配一个 QPS 上限」和「设计一个限流体系」之间差着三层架构。这篇把三层设计的适用边界和典型坑过一遍。

第一层：单机限流（算法层）

单机限流的核心是算法选型，三个主流算法的脾气完全不同：

• 固定窗口计数器：实现最简单，致命伤是窗口边界突刺——两个窗口交界处可能通过 2 倍流量。适合「大致限一下」的非关键场景
• 滑动窗口：解决边界突刺，内存开销略高（要存窗口内每个请求的时间戳或分桶）。大多数场景的默认选择
• 令牌桶：允许突发（桶里攒的令牌一次性放出），适合「平时限速、高峰放行」的业务。坑在于令牌补充速率和桶容量要分开理解——很多配置事故源于把两者设成同一个数

单机层的黄金法则：限流的 key 要选业务维度（用户 ID / API key），不要选 IP——公司出口 IP 几百人共享，按 IP 限流等于随机误伤。

第二层：分布式限流（协调层）

多实例部署后单机限形同虚设（每台都放 N，总量 N×实例数）。分布式限流需要共享计数器，主流方案两种：

Redis 集中计数：Lua 脚本原子地「读-判-增」。优点精确，缺点是每个请求多一次 Redis 往返——限流组件自己成了延迟大户，且 Redis 抖动时代理全挂（限流系统要有「Redis 不可用时放行还是拒绝」的预案，通常选放行+告警，否则限流器变成单点故障源）。

本地分片配额：中心把总配额切成 N 份下发各实例，各自本地限。优点零额外延迟，缺点是不均衡（某实例流量热点时提前触顶而其他实例还有余量）。改进版是配额借用（实例间异步再平衡），复杂度上一个台阶。

实践建议：默认用本地分片（牺牲 10% 精度换零依赖），只有配额本身很贵（比如第三方 API 按次计费）才值得上 Redis 精确限。

第三层：分级与熔断联动（策略层）

限流不该只有一个阈值。成熟的设计是三级响应：

1. 软限（80%）：正常放行，但触发告警+开始记录溢出请求样本（下一容量评审的依据）
2. 硬限（100%）：拒绝，返回限流码。响应体里带 Retry-After 和限流维度说明——调用方有能力做退避，别让他猜
3. 熔断（120% 或错误率联动）：持续超限时直接短路，不再逐请求判断（保护后端不被半死不活的流量拖着）

另一个容易被忽略的点：限流响应要可观测。被拒请求的数量、维度分布、重试风暴迹象，都要有指标——限流不是拒绝完就结束了，它是容量规划的数据输入。

常见翻车清单

• 限流 key 选了 IP，大客户出口被误伤
• Redis 挂了限流器全拒绝，制造全站故障
• 只有限流没有分级，80% 容量时毫无预警直接 100% 拒绝
• Retry-After 没带，调用方疯狂立即重试形成放大
• 网关限了但后端服务自己没限，绕过网关的内部调用打穿后端

结语

三层设计一句话总结：算法层选对 key 和算法，协调层在精确性和依赖风险间取舍，策略层让限流从「一刀切拒绝」进化成「分级响应+数据回流」。限流系统的终极形态不是拦住流量，是告诉容量规划该扩容了。