# Cursor API 令牌桶：允许短暂突发，超额时返回可验证的 Retry-After

真实HTTP并发10次只放行3次，返回7次429；按用户隔离、等待Retry-After后放行，虚拟时钟边界也核对。

## 环境

- Python 3；此题标准库脚本或README指定的外部CLI。

## 启动

~~~sh
cd reference
python3 server.py --port 8787
~~~

## 七步操作

1. 设定容量补速

容量为3，每秒补充2个令牌，起始桶满。先用可控时钟验证同一时刻只能消费三次，0.49秒不足一次，0.5秒可再消费一次。

2. 实现原子扣减

服务器在同一把锁内完成时间补充、容量上限和扣减。先检查后异步扣减会在并发时多放行，必须把状态变更作为完整临界区。

3. 发起真实突发

点击Alice并发10次，真实本机HTTP请求中只有3次200、7次429。输入是短暂突发，允许容量内请求不会被一律拒绝。

4. 读取429响应

429带Retry-After，由当前令牌缺口与补充速度计算并向上取整。表里同时保留剩余令牌，不能拿固定等待时间冒充算法结果。

5. 隔离用户桶

Bob使用自己的桶，Alice耗尽后Bob的首个请求仍能200。这验证的是按用户隔离，不是所有用户共享一个全局配额。

6. 按时间补充

等待响应中的Retry-After再请求Alice，真实返回200。客户端等待只是演示；后端仍要在每次请求独立验证令牌。

7. 核对令牌不负

保存虚拟时钟与真实并发两侧记录，检查没有负令牌或超额放行。本文为本机单进程原子桶，没有接AWS账号，也不重复上游429客户端重试教程。

## 目录身份

- starter：待完成的任务接口与原创输入，TODO不是已完成实现。
- reference：作者原生完成参考和实际产物。records.json/browser-result.json为本地实测记录，不是AI助手回复。
- TASK.md：可交给相应AI助手的原始任务合同。该助手账号生成会话未运行。

## 依赖与许可

原创教学代码以MIT许可提供。第三方项目、模型及浏览器遵循其自身许可。第三方依赖由本地安装获取，不包含node_modules、模型权重、WASM运行时、数据库、缓存或凭据。

## 官方依据

- https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-request-throttling.html