API速率限制策略模拟器

--- name: api-rate-limit-policy-simulator description: 在发布前模拟API速率限制 - 令牌桶、固定窗口、滑动日志和滑动计数器，按客户端、端点、层级或全局 - 针对生成或记录的流量，并带有重试客户端。显示谁收到429以及持续多久，固定窗口边界突发、重试群体、嘈杂邻居、仍能通过的滥用客户端以及超过后端容量的峰值。包含离线标准库Python模拟器，支持--self-test。 --- # API速率限制策略模拟器 你帮助后端和平台工程师基于证据而非整数选择速率限制。一个在纸面上看起来安全的限制（“每个密钥每分钟300次”）仍可能在窗口边界让1.8倍流量通过，限制一个数千用户共享一个API密钥的移动应用，在重置秒释放重试群体，并且对保持在限制以下的爬虫毫无作用。你在一个小JSON文件中描述策略和流量，重放它，并逐客户端和逐策略读取结果。 ## 此技能中的文件 - `scripts/rate_sim.py` - 模拟令牌桶、固定窗口、滑动日志和滑动计数器限制器，按键为客户端、端点、客户端+端点或全局，范围限定到端点和客户端层级；生成稳定、泊松或突发流量（或重放CSV轨迹），让客户端立即重试、带退避或遵循Retry-After，并报告429、延迟、失败、最坏情况和观察到的窗口计数、峰值与容量对比、发现RL01-RL10以及示例429响应（仅Python 3.8+标准库） - `references/algorithms.md` - 每种算法的行为、最坏情况、内存成本和选择时机 - `references/policy-design.md` - 选择键、层级、数字、头部和客户端重试规则；发现代码的含义 - `templates/rate-limit-review.md` - 要交回的审查 - `examples/orders-api.json` - 一个公共订单API，带有按密钥固定窗口、登录限制和全局固定窗口；五个客户端，包括共享移动密钥、批量合作伙伴、爬虫和凭证填充器 - `examples/orders-api-report.md` - 该文件上的真实模拟器输出 - `examples/orders-api-tuned.json` - 修复后的同一API：按层级令牌桶、按容量调整大小的全局令牌桶 ## 工作流程 ### 1. 收集输入 询问：当前配置或提议的限制（算法、键、数字、哪些端点和哪些客户端），它们在何处执行（网关、CDN、应用、Redis），后端可承受的每秒请求数容量，以及流量：最大的合法客户端及其形态（稳定、突发批量作业、一个密钥或一个NAT IP后的许多用户），每个客户端如何重试，以及日志中看到的任何滥用。真实访问日志优于猜测：导出繁忙5-15分钟的`t,client,endpoint`，并用`--trace`传递。 ### 2. 运行模拟器 ``` python3 scripts/rate_sim.py examples/orders-api.json python3 scripts/rate_sim.py examples/orders-api-tuned.json python3 scripts/rate_sim.py policies.json --trace access-sample.csv python3 scripts/rate_sim.py policies.json --json python3 scripts/rate_sim.py --self-test ``` 退出0 = 无高风险发现，1 = 高风险发现（合法客户端被限制或允许流量超过容量），2 = 输入错误。没有shell时，用`references/algorithms.md`推理：按密钥，比较客户端每窗口峰值与限制，最坏情况（固定窗口2倍限制，桶突发+速率）与容量，并思考每个客户端在429后做什么。 ### 3. 读取结果 - 首先合法客户端（RL01）：任何失败或延迟的请求，以及它们等待了多久。一个应用用户共享的密钥需要自己的层级或按用户密钥。 - 容量（RL03）：允许的峰值每秒与后端可承受的对比。全局限制是唯一保护容量的东西；按密钥限制乘以密钥数量。 - 形态（RL04，RL10）：固定窗口让突发在边界通过，并一次性发放整个窗口；没有抖动的重试都在同一秒回来。 - 滥用（RL02）：按密钥限制以下的爬虫不会被限制阻止；它需要检测、认证或按端点限制。 - 重试（RL05）：每个逻辑请求的尝试次数超过1.5意味着客户端在受限时放大负载。 ### 4. 调整并重新运行 一次更改一件事，并用相同流量重新运行：将固定窗口切换为令牌桶或滑动计数器，用`clients` / `exclude_clients`添加层级，将全局桶调整到容量（速率 = 可持续rps，突发 = 后端一秒内吸收的），为登录和昂贵调用添加端点限制，并与批量合作伙伴商定节奏。数字用`references/policy-design.md`。 ### 5. 交付 填写`templates/rate-limit-review.md`：结论、每个客户端的之前/之后表格、作为配置的策略更改、429响应和头部、客户端指南（Retry-After、带抖动的退避、最大重试次数）以及发布后要监控的内容。 ## 示例结果 在`examples/orders-api.json`上，共享的`mobile-app`密钥达到300/分钟按密钥窗口：其1，839个请求中的1，042个仅在等待最多60秒后成功（RL01，高）。遵循Retry-After而不抖动在第240秒释放289个重试，因此允许流量峰值达到313 req/s，而容量为80（RL03，RL10）。按密钥固定窗口让544个请求在一个滚动分钟内通过（1.8倍，RL04），爬虫仍让45%的调用通过，而其立即重试将其推到每个请求2.67次尝试。登录限制阻止凭证填充器（480中的40）。在`examples/orders-api-tuned.json`中（层级令牌桶，全局桶50 req/s + 30突发，合作伙伴节奏2 req/s），合法客户端看不到429，峰值是27 req/s，只有爬虫发现仍然存在。 ## 规则 - 用你实际拥有的流量（或轨迹）模拟，而不是平均值；突发和重试是限制失败的地方。 - 除非全局限制约束总数，否则不要称限制对容量安全。 - 将合法客户的延迟请求视为伤害，而非成功。 - 始终返回带Retry-After的429，添加抖动，并告诉客户端如何退避。 - 速率限制本身不是滥用保护；说明何时需要认证、机器人检测或WAF规则。 - 结果是模型：发布后用网关指标确认，并将限制保留在配置中，而非代码中。