API 限额（限流 / 配额），主要控制调用频次、查询数量、数据量、时间窗口，目的保护服务端、防止刷接口、保障多租户公平，常见分为频率限制、数量配额、结果集限制、业务自定义限制四大类。
一、常见限额维度
1. 时间窗口频率限制（QPS/RPM）
控制单位时间请求次数，最常用
维度：秒 (QPS)、分钟 (RPM)、小时、天
粒度：用户 ID /appKey/token / IP / 租户 ID
示例：
单 appKey：100 QPS（每秒最多 100 次请求）
单账号：1000 次 / 天，超出返回 429 Too Many Requests
两种算法：令牌桶（允许突发）、漏桶（平滑流量），API 网关大多用令牌桶。
2. 查询结果条数限额（分页限额）
控制单次查询返回的数据行数，防止一次性拉取全库拖垮 DB
单次最大 pageSize：例如最大
pageSize=100，传 200 强制截断为 100最大可查询总页数：例如最多允许查 100 页，禁止无限翻页导出全量数据
禁止不传分页参数：不允许 pageSize=-1（返回全部）
业务规则：批量导出接口单独做白名单，普通查询接口强制分页上限。
3. 时间范围查询限额
针对按时间筛选的查询接口，防止超大时间范围扫描数据库
示例：单次查询时间跨度最大 31 天；传超过 1 年直接拒绝
规则：
start_time~end_time间隔校验，超限返回参数错误，提示缩小时间区间
4. 数据量级 / 权重配额
复杂查询（多条件、多表关联、统计聚合）消耗资源更高，不用单纯按请求数。
简单查询：计 1 点；统计聚合、大表查询：计 5~10 点
按每日消耗点数做配额，不是按请求次数。
5. 租户 / 角色分级限额
不同客户权限不一样
免费版：50QPS，1 万次 / 天
企业版：500QPS，100 万次 / 天
内部管理员账号：白名单，不受限流约束
二、限额触发后返回规范
HTTP 状态码：429 Too Many Requests（频率超限）
Response Body 示例
{
"code":429,
"msg":"API调用次数已达限额，请稍后再试",
"data":{
"reset_timestamp":1782334560,
"retry_after":60
}
}
Response Header 标准（推荐带上）
X-RateLimit-Limit: 1000 #总配额
X-RateLimit-Remaining: 0 #剩余次数
X-RateLimit-Reset: 1782334560
Retry-After:60
三、业务层面配置规则（产品设计）
区分接口类型
普通查询接口：严格 QPS + 分页 + 时间范围限制
统计 / 报表接口：更低 QPS，更严格时间跨度
写入接口：额外防重复、防爆破；和查询分开配额
导出接口：单独配额，异步任务模式，禁止同步返回海量数据
白名单机制 指定 appKey/IP 跳过限流，用于内部系统、对接大客户；白名单需要审批记录。
超限告警
剩余配额低于 20% 推送告警；
短时间大量 429，监控告警，识别是否爬虫 / 恶意调用。
配额重置规则
按自然时间重置：每日 0 点重置日配额
滑动窗口重置：例如 1 分钟滑动窗口，不是整分重置。
四、数据库层配套限制（容易忽略）
API 限额不止网关层，还要防绕过网关直接压 DB：
MyBatis/JPA 设置最大返回行数；
SQL 增加 limit 上限，不依赖前端传入 pageSize；
禁止不带条件全表查询。
五、典型完整示例规则模板
app_key 维度：
QPS 上限：20 次 / 秒（令牌桶）
每日最大请求：20000 次
单请求 pageSize 最大 100，最大查询 500 页
时间查询区间最大 90 天
聚合统计接口 QPS 降为 5 次 / 秒
超限返回 429，携带 retry‑after，提供 header 配额信息
内部白名单 app_key 不受以上约束
六、常见坑点
只用 IP 限流：多用户 NAT 共享同一个 IP，会误杀正常用户；优先 appKey/token。
只做网关限流，业务代码没有二次防护：绕过网关直接访问后端会击穿。
分页只限制 pageSize，不限制最大页码：攻击者 page=10000，pageSize=100，仍然压库。
时间窗口使用固定窗口，出现临界瞬间流量翻倍，优先滑动窗口 / 令牌桶。
本文原创作者：易君召，详见：https://www.yijunzhao.cn/authors/yijunzhao，转载请注明出处。
原文链接
欢迎访问 小易撩挨踢