GEO API 限流概述
为保障服务稳定性，GEO 体检仪 API 实施限流策略，参考GEO API：
| 限流维度 | 默认配额 | 适用套餐 |
|---|---|---|
| 每分钟请求数 | 100 次/分钟 | 年度套餐 |
| 每天请求数 | 1000 次/天 | 年度套餐 |
| 并发诊断数 | 3 个并发 | 年度套餐 |
| 批量诊断数 | 50 个/批 | 年度套餐 |
限流响应
超限时 API 返回 429 状态码：
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
{
"code": 429,
"message": "Rate limit exceeded",
"data": {
"retry_after": 60,
"limit": 100,
"remaining": 0,
"reset_at": "2026-07-01T10:31:00Z"
}
}
响应头说明
每个 API 响应包含限流信息头：
| 响应头 | 说明 |
|---|---|
| X-RateLimit-Limit | 每分钟最大请求数（100） |
| X-RateLimit-Remaining | 当前分钟剩余请求数 |
| X-RateLimit-Reset | 配额重置时间（Unix 时间戳） |
| Retry-After | 建议重试等待秒数（429 响应） |
应对限流的策略
1. 指数退避重试
收到 429 后，指数退避重试：
// Node.js 示例
async function callGeoAPI(fn, retries = 5) {
for (let i = 0; i < retries; i++) {
try {
return await fn();
} catch (e) {
if (e.status === 429 && i < retries - 1) {
const wait = Math.pow(2, i) * 1000; // 1s, 2s, 4s, 8s, 16s
await new Promise(r => setTimeout(r, wait));
continue;
}
throw e;
}
}
}
2. 请求间隔控制
主动控制请求频率，避免触发限流：
- 请求间隔 ≥ 600ms（100 次/分钟 → 1 次/0.6 秒）
- 批量请求分散到全天，避免集中调用
- 非紧急请求放到低峰期（夜间）
3. 数据缓存
缓存 API 响应减少调用次数：
- 诊断结果缓存 1 小时（同一品牌+品类）
- 历史数据缓存 24 小时
- 用 Redis/内存缓存
4. 批量操作
用批量接口替代多次单个调用：
- 用 /api/diagnose/run/batch 替代多次 /api/diagnose/run
- 用 /api/diagnose/history 一次性拉取历史数据
提升配额
默认配额无法满足需求时：
- 联系商务申请提升配额
- 企业级客户可定制专属配额
- 超高并发需求可部署私有化实例
限流的最佳实践
- 监控用量：定期查看 API 用量，提前规划
- 优雅降级：API 失败时降级到手动查询，不影响业务
- 错误处理：429 不应导致程序崩溃，应重试或降级
- 日志记录：记录 429 发生频率，评估配额是否充足