Communitygithub.com

AppFolio 速率限制处理

处理 AppFolio API 的速率限制,提供节流和退避策略。

AppFolio 速率限制处理 是什么?

本技能专门用于处理 AppFolio Stack API 的速率限制问题。它提供了一个完整的速率限制器实现,包括令牌桶算法、基于 Retry-After 头的退避策略、以及带有指数退避和抖动的重试逻辑。该技能还包含批量处理示例,支持将租户更新、工单同步等操作分批执行,并能在遇到 429 状态码、服务维护窗口或未知写入结果时暂停并上报。支持 TypeScript/JavaScript 平台,可直接集成到 Node.js 项目中。无论是物业管理公司批量导入租户、同步租金报表,还是处理月末高峰期的大量请求,该技能都能帮助开发者优雅地管理 API 配额,避免因超出速率限制而导致的中断。

兼容平台✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/jeremylongshore/tons-of-skills-marketplace/tree/HEAD/plugins/saas-packs/appfolio-pack/skills/appfolio-rate-limits

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

AppFolio 速率限制

概述

AppFolio 的 Stack API 对每个合作伙伴实施速率限制,以保护共享的物业管理基础设施。大批量操作(如批量租户导入、租金报表同步、工单批量更新)可能会迅速耗尽配额。跨数百个单元运行夜间组合同步的物业经理必须谨慎进行节流,尤其是在月末租赁续约和付款处理同时激增时。

前提条件

  • 从当前的 AppFolio 合作伙伴合同或响应头中获取已验证的每个端点限制;不要依赖通用的速率值进行租户写入。
  • 持久化的批处理游标、每个写入操作的幂等键,以及用于暂停月末或其他安全敏感工作负载的操作员策略。
  • 一个沙箱环境 fixture 和请求预算负责人,能够在不影响生产租户的情况下证明重试、429 行为和未知写入处理。

指令

  1. 选择特定端点的限制器上限,并将并发度保持在最小适用的组合或合作伙伴限制以下。
  2. 在每个请求前获取令牌,遵守 Retry-After 头,并通过抖动限制重试次数,以应对临时的服务提供商故障。
  3. 使用幂等键从持久化的游标处理写入;不要仅仅因为响应丢失就重放租户创建操作。
  4. 对于耗尽重试预算、遇到维护窗口或存在未知写入结果的批次,暂停并上报。

速率限制参考

端点限制窗口范围
属性列表/获取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。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page for positioning, plan a conversion-optimized page layout, or design a launch page. Examples: "landing page for product launch", "conversion-optimized layout for SaaS

jeremylongshore/tons-of-skills-marketplace

Use when asked to design growth-optimized landing pages, activation funnel layouts, or experiment-friendly page structures. Examples: "growth-optimized landing", "activation funnel layout", "A/B testable page

jeremylongshore/tons-of-skills-marketplace

Use when asked to structure a landing page, design page layout for conversion, or plan landing page information architecture. Examples: "landing page structure for SaaS", "conversion-optimized layout

jeremylongshore/tons-of-skills-marketplace

Generate polished demo videos from a single prompt. Use when the user asks to create a demo video, product walkthrough, feature showcase, or animated presentation. Trigger with "make a demo video", "create a product video", "demo walkthrough", or "feature showcase video".

jeremylongshore/tons-of-skills-marketplace

Track cryptocurrency portfolio with real-time valuations, allocation analysis, and P&L tracking. Use when checking portfolio value, viewing holdings breakdown, analyzing allocations, or exporting portfolio data. Trigger with phrases like "show my portfolio", "check crypto holdings", "portfolio allocation", "track my crypto", or "export portfolio".

jeremylongshore/tons-of-skills-marketplace

Runs the full release workflow for the current project. Commits any uncommitted changes, pushes to remote, creates and merges a PR if on a feature branch, determines the next semver version from conventional commits, creates an annotated git tag and GitHub release with generated notes, cleans up merged branches, and returns to a clean main. Use when the user says promote, ship, release, commit and push, tag and release, or get back to main.

jeremylongshore/tons-of-skills-marketplace

Agent skill at plugins/productivity/content-multiplier/skills/channel-formats/SKILL.md

jeremylongshore/tons-of-skills-marketplace

Operate an evidence-backed editorial queue, balance topic and format coverage, schedule approved drafts, and reconcile backlog state with the publishing system. Use when choosing or scheduling the next blog work. Trigger with "show the editorial calendar" or "pick the next topic".

jeremylongshore/tons-of-skills-marketplace

Configure CI/CD pipeline for AppFolio property management integrations. Trigger: "appfolio CI".

jeremylongshore/tons-of-skills-marketplace

Diagnose and fix common AppFolio API integration errors. Trigger: "appfolio error".

jeremylongshore/tons-of-skills-marketplace

Build property management dashboard with AppFolio API data. Trigger: "appfolio property dashboard".

jeremylongshore/tons-of-skills-marketplace

Automate tenant management and lease operations with AppFolio. Trigger: "appfolio tenant management".

jeremylongshore/tons-of-skills-marketplace

Collect AppFolio API debug evidence for support tickets. Trigger: "appfolio debug".

jeremylongshore/tons-of-skills-marketplace

Deploy AppFolio integration service to cloud infrastructure. Trigger: "deploy appfolio".

jeremylongshore/tons-of-skills-marketplace

Query AppFolio properties, units, and tenants via REST API. Trigger: "appfolio hello world".

jeremylongshore/tons-of-skills-marketplace

Configure AppFolio Stack API authentication with OAuth 2.0. Use when setting up property management API access, registering as an AppFolio Stack partner, or configuring client credentials for API calls. Trigger: "install appfolio", "setup appfolio", "appfolio auth", "appfolio API key".

jeremylongshore/tons-of-skills-marketplace

Set up local development for AppFolio property management API integration. Trigger: "appfolio local dev".

jeremylongshore/tons-of-skills-marketplace

Production readiness checklist for AppFolio integrations. Trigger: "appfolio production checklist".

jeremylongshore/tons-of-skills-marketplace

Reference architecture for AppFolio property management integration. Trigger: "appfolio architecture".

jeremylongshore/tons-of-skills-marketplace

Apply production-ready patterns for AppFolio REST API integration. Trigger: "appfolio patterns".

相关技能