AppFolio 速率限制
概述
AppFolio 的 Stack API 对每个合作伙伴实施速率限制,以保护共享的物业管理基础设施。大批量操作(如批量租户导入、租金报表同步、工单批量更新)可能会迅速耗尽配额。跨数百个单元运行夜间组合同步的物业经理必须谨慎进行节流,尤其是在月末租赁续约和付款处理同时激增时。
前提条件
- 从当前的 AppFolio 合作伙伴合同或响应头中获取已验证的每个端点限制;不要依赖通用的速率值进行租户写入。
- 持久化的批处理游标、每个写入操作的幂等键,以及用于暂停月末或其他安全敏感工作负载的操作员策略。
- 一个沙箱环境 fixture 和请求预算负责人,能够在不影响生产租户的情况下证明重试、
429行为和未知写入处理。
指令
- 选择特定端点的限制器上限,并将并发度保持在最小适用的组合或合作伙伴限制以下。
- 在每个请求前获取令牌,遵守
Retry-After头,并通过抖动限制重试次数,以应对临时的服务提供商故障。 - 使用幂等键从持久化的游标处理写入;不要仅仅因为响应丢失就重放租户创建操作。
- 对于耗尽重试预算、遇到维护窗口或存在未知写入结果的批次,暂停并上报。
速率限制参考
| 端点 | 限制 | 窗口 | 范围 |
|---|---|---|---|
| 属性列表/获取 | 120 请求 | 1 分钟 | 每个合作伙伴密钥 |
| 租户创建/更新 | 30 请求 | 1 分钟 | 每个合作伙伴密钥 |
| 工单 | 60 请求 | 1 分钟 | 每个合作伙伴密钥 |
| 批量数据导出 | 5 请求 | 1 小时 | 每个合作伙伴密钥 |
| Webhook 注册 | 10 请求 | 1 分钟 | 每个合作伙伴密钥 |
速率限制器实现
class AppFolioRateLimiter {
private tokens: number;
private lastRefill: number;
private readonly maxTokens: number;
private readonly refillRate: number; // tokens per ms
constructor(maxPerMinute: number) {
this.maxTokens = maxPerMinute;
this.tokens = maxPerMinute;
this.lastRefill = Date.now();
this.refillRate = maxPerMinute / 60_000;
}
async acquire(): Promise<void> {
for (;;) {
this.refill();
if (this.tokens >= 1) {
this.tokens -= 1;
return;
}
// 等待直到下一个令牌可用;无需后续请求唤醒此调用者。
const waitMs = Math.max(1, Math.ceil((1 - this.tokens) / this.refillRate));
await new Promise(resolve => setTimeout(resolve, waitMs));
}
}
private refill() {
const now = Date.now();
this.tokens = Math.min(this.maxTokens, this.tokens + (now - this.lastRefill) * this.refillRate);
this.lastRefill = now;
}
}
const limiter = new AppFolioRateLimiter(25); // 根据端点合同配置
重试策略
async function appfolioRetry<T>(fn: () => Promise<Response>, maxRetries = 4): Promise<T> {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
await limiter.acquire();
const res = await fn();
if (res.ok) return res.json();
if (res.status === 429) {
const retryAfter = parseInt(res.headers.get("Retry-After") || "10", 10);
const delay = retryAfter * 1000 + Math.random() * 2000;
await new Promise(r => setTimeout(r, delay));
continue;
}
if (res.status >= 500 && attempt < maxRetries) {
await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000));
continue;
}
throw new Error(`AppFolio API ${res.status}: ${await res.text()}`);
}
throw new Error("超出最大重试次数");
}
批量处理
async function batchSyncTenants(tenants: any[], batchSize = 25) {
const results: any[] = [];
for (let i = 0; i < tenants.length; i += batchSize) {
const batch = tenants.slice(i, i + batchSize);
const batchResults = await Promise.all(
batch.map(t => appfolioRetry(() =>
fetch(`${BASE}/api/v1/tenants`, {
method: "POST", headers, body: JSON.stringify(t),
})
))
);
results.push(...batchResults);
if (i + batchSize < tenants.length) await new Promise(r => setTimeout(r, 2000));
}
return results;
}
错误处理
| 问题 | 原因 | 修复 |
|---|---|---|
| 429 请求过多 | 超出合作伙伴速率限制 | 使用 Retry-After 头进行退避 |
| 批量导出时 403 | 达到每小时导出上限 | 将导出排队,间隔 15 分钟 |
| 属性列表超时 | 大型组合(500+ 单元) | 使用 per_page=50 进行分页 |
| 租户更新时 409 冲突 | 同一租户的并发写入 | 使用新的 ETag 重试 |
| 维护期间 503 | 计划夜间窗口(太平洋时间凌晨 2-4 点) | 跳过请求,窗口结束后重试 |
输出
- 一个自我调度的、针对特定端点的限制器,不会导致排队工作被卡住
- 带有
Retry-After证据和脱敏失败数据的有界重试结果 - 一个持久化的批处理决策:已完成、暂停以待后续重试、或隔离以供操作员协调
示例
对于沙箱环境中的租户更新批处理,将限制器设置为低于记录的租户写入上限,每次使用幂等键处理一条记录,并在每个确认结果后保留游标。引发一个 429 来验证调用者会等待并恢复而无需额外的请求,然后引发一个丢失的响应来证明记录被隔离而不是盲目重放。如果速率标头与配置的上限冲突、重试耗尽或维护开始,则暂停批处理并将游标交给负责人。
资源
后续步骤
参阅 appfolio-performance-tuning。