用途:限制调用方访问接口的频率,适用于登录、密码重置、公开 API 及任何公开写入操作。
主要能力:支持滑动窗口、令牌桶、固定窗口三种算法;可按控制器属性、服务或全局事件订阅器应用限流;返回正确的 429 与 Retry-After;也可在令牌释放前阻塞等待而非直接拒绝。
使用方式:先明确被限对象与调用方身份,再按流量特征选择算法并确定速率与突发量;在 framework.rate_limiter 下为每个限流器声明一条策略;在请求被拒绝处应用,并返回 429 与 Retry-After;用测试验证通过、拒绝与重置三种情况。
限制与注意:调用方身份决定计数对象,位于代理后时不可信客户端地址会把所有人算作一个;限流器不是授权,只限速率不判定权限;拒绝必须用 429 与 Retry-After,不能静默丢弃或返回 500;存储按进程隔离的限流器无法跨多个 worker 生效;预留令牌会阻塞调用进程,不可用于 Web 请求。
输出约定:给出各限流器的算法、速率与突发量,应用位置与调用方身份,429 响应结构及响应头,以及覆盖通过、拒绝、重置的测试。
更多实现细节见 reference.md。