核心是统一“准入判断”“状态维护”“拒绝响应”和“可观测性”四环节语义，要求限流组件实现统一tryAcquire方法、区分本地/集群状态、标准化429响应与日志、暴露对齐的Prometheus指标。
在 API 网关中规范限流算法的行为契约，核心是统一“准入判断”“状态维护”“拒绝响应”和“可观测性”四个环节的语义，而非仅关注算法内部实现。不同算法（如令牌桶、漏桶）可以共用同一套契约接口，让网关层解耦具体策略，便于切换、组合与治理。
限流行为必须定义清晰的准入契约
所有限流组件需实现统一的 boolean tryAcquire(String key, long permits) 方法：
-
key 表示限流维度（如
user:1001、api:/order/create、ip:192.168.1.100），由网关路由规则动态提取并传入 - permits 表示本次请求消耗的配额单位（HTTP 请求默认为 1；大文件上传可设为字节数或分片数）
- 返回 true 表示放行，false 表示拒绝——不抛异常、不重试、不隐式排队，由上层决定是否降级或返回 429
- 禁止在该方法内执行耗时操作（如远程调用、日志刷盘），保证网关路径低延迟
状态管理需区分本地与全局语义
网关常以多实例部署，限流状态需按场景明确归属：
-
单实例限流（如 Guava RateLimiter）：状态完全内存化，适用于灰度流量隔离或开发环境快速验证；契约中须标注
@Scope("local")注解或配置标识 -
集群限流（如 Redis + Lua 实现令牌桶）：状态中心化，key 必须含唯一网关实例标识（如
gateway:us-east-1a:rate:user:1001），避免跨实例计数漂移 -
混合限流：先走本地预判（快路径），再异步同步到中心（慢路径），契约需支持
tryAcquireWithAsyncSync()扩展方法，并明确定义“预判成功但中心拒绝”时的回滚语义
拒绝策略与响应体必须标准化
无论底层是令牌桶还是漏桶，网关对外暴露的限流拒绝行为应一致：
立即学习“Java免费学习笔记（深入）”；
- HTTP 响应码统一为 429 Too Many Requests
- 响应头必须包含
X-RateLimit-Limit（窗口总配额）、X-RateLimit-Remaining（当前剩余）、X-RateLimit-Reset（时间戳，秒级）——漏桶算法可推算剩余流出能力，令牌桶可读取桶中当前令牌数 - 拒绝日志格式统一：
[LIMIT][ALGO:leaky|token][KEY:user:1001][WINDOW:60s][REJECTED]，便于 ELK 聚合分析 - 禁止算法实现自行决定是否重定向、是否写入缓存、是否触发告警——这些由网关策略引擎统一编排
可观测性字段需对齐监控指标体系
每种算法实现必须暴露相同维度的运行时指标，供 Prometheus 或 Micrometer 采集：
ratelimiter.acquired_total{algorithm="token", scope="cluster", key="api:/pay"}ratelimiter.rejected_total{algorithm="leaky", scope="local", reason="bucket_full"}-
ratelimiter.bucket_utilization_ratio{algorithm="token"}（当前令牌数 / 桶容量） -
ratelimiter.leak_rate_seconds{algorithm="leaky"}（实际漏出速率，用于对比配置值偏差）
