AppFolio SDK 模式 是做什麼的?
概述
適用於 AppFolio 物業管理 REST API 的生產就緒模式。AppFolio 使用 HTTP Basic Auth 搭配客戶端憑證,並針對物業、租戶、租約和工單回傳 JSON 回應。一個結構化的單例客戶端可防止憑證散落、強制執行一致的錯誤處理,並將所有物業管理端點的分頁邏輯集中管理。
先決條件
- 供應商已驗證的基礎 URL、驗證方法、端點範圍,以及目標投資組合的受管密碼注入路徑。
- 所有具備突變能力的服務方法都需進行架構驗證、設定請求逾時、端點特定的速率限制,以及使用冪等金鑰。
- 用於單元測試的合成測試資料;不得將生產環境的租戶、租約和付款負載作為預設的模擬資料、日誌或錯誤訊息內容。
指示
- 每個執行階段建立一個綁定合約的客戶端,並在請求開始前拒絕缺少或無效的配置。
- 在服務邊界驗證查詢邊界和回應形狀,然後僅將最小化的型別欄位傳遞給呼叫者。
- 將分類後的
429或未知寫入失敗回傳給呼叫者;僅在呼叫者記錄游標/金鑰和延遲後,才重試冪等操作。 - 將寫入工作流程保留在明確的授權、稽核和對帳控制之後,而不是將其嵌入通用的 SDK 便捷輔助函式中。
單例客戶端
import axios, { AxiosInstance } from 'axios';
let _client: AxiosInstance | null = null;
export function getClient(): AxiosInstance {
if (!_client) {
const clientId = process.env.APPFOLIO_CLIENT_ID;
const clientSecret = process.env.APPFOLIO_CLIENT_SECRET;
const baseURL = process.env.APPFOLIO_BASE_URL;
if (!clientId || !clientSecret || !baseURL) throw new Error('需要 APPFOLIO_CLIENT_ID、SECRET 和 BASE_URL');
_client = axios.create({ baseURL, auth: { username: clientId, password: clientSecret }, timeout: 30000 });
}
return _client;
}
錯誤包裝器
export class AppFolioError extends Error {
constructor(public status: number, public code: string, message: string) { super(message); }
}
export async function safeCall<T>(operation: string, fn: () => Promise<T>): Promise<T> {
try { return await fn(); }
catch (err: any) {
const status = err.response?.status ?? 0;
if (status === 429) {
const retryAfter = err.response?.headers?.['retry-after'];
throw new AppFolioError(429, 'RATE_LIMIT', `請在 ${retryAfter ?? '供應商指定的延遲'} 後重試;請勿自動重播未知的寫入操作`);
}
if (status === 401) throw new AppFolioError(401, 'AUTH', '無效的 APPFOLIO_CLIENT_ID 或 SECRET');
throw new AppFolioError(status, 'API_ERROR', `${operation} 失敗 [${status}]: ${err.message}`);
}
}
請求建構器
class AppFolioQuery {
private params: Record<string, string> = {};
status(s: 'active' | 'past' | 'future') { this.params.status = s; return this; }
propertyId(id: string) { this.params.property_id = id; return this; }
page(n: number) { this.params.page = String(n); return this; }
perPage(n: number) { this.params.per_page = String(Math.min(n, 200)); return this; }
since(date: string) { this.params.updated_since = date; return this; }
build() { return this.params; }
}
// 使用方式:new AppFolioQuery().status('active').perPage(50).build();
回應類型
interface Property {
id: string; name: string; property_type: 'residential' | 'commercial' | 'mixed';
address: { street: string; city: string; state: string; zip: string };
unit_count: number; status: string;
}
interface Tenant {
id: string; first_name: string; last_name: string;
email: string; phone: string; unit_id: string; lease_id: string;
}
interface Lease {
id: string; unit_id: string; tenant_id: string;
start_date: string; end_date: string; rent_amount: number; status: 'active' | 'expired' | 'future';
}
interface WorkOrder {
id: string; property_id: string; unit_id: string;
description: string; priority: 'low' | 'medium' | 'high' | 'emergency';
status: 'open' | 'in_progress' | 'completed';
}
測試工具
export function mockProperty(overrides: Partial<Property> = {}): Property {
return { id: 'prop-001', name: 'Maple Ridge Apts', property_type: 'residential',
address: { street: '100 Main St', city: 'Austin', state: 'TX', zip: '78701' },
unit_count: 24, status: 'active', ...overrides };
}
export function mockLease(overrides: Partial<Lease> = {}): Lease {
return { id: 'lease-001', unit_id: 'unit-001', tenant_id: 'ten-001',
start_date: '2025-01-01', end_date: '2026-01-01', rent_amount: 1500, status: 'active', ...overrides };
}
錯誤處理
| 模式 | 使用時機 | 範例 |
|---|---|---|
safeCall 包裝器 | 所有 API 呼叫 | 防止未捕獲的 4xx/5xx 導致流程崩潰 |
| 呼叫者擁有的 429 重試 | 受速率限制的冪等批次讀取 | 保留游標/金鑰,遵守 Retry-After,然後審慎重試 |
| 驗證驗證 | 客戶端初始化 | 若缺少憑證則提前拋出錯誤 |
| 分頁迴圈 | 列出物業/租戶 | 遞增 page 直到回傳空回應 |
輸出
- 一個經過驗證、綁定合約的 API 客戶端,具備集中的逾時和錯誤分類行為
- 為服務呼叫者提供有界的查詢參數和最小化的型別回應
- 明確的速率限制和未知寫入結果,要求呼叫者做出游標/冪等性/對帳決策
範例
對於物業列表讀取,使用設定了上限頁面大小的查詢建構器,透過 safeCall 執行,並針對合成測試資料驗證回傳的物業 ID 和計數。對於突變操作,在分派前先保存一個冪等金鑰,並將逾時或 429 視為暫停/對帳條件,而不是直接再次呼叫函式。如果客戶端配置、回應架構或寫入結果未經驗證,請停止工作流程並向擁有者顯示一個經過編輯的錯誤訊息。
資源
後續步驟
在 appfolio-core-workflow-a 中套用這些模式。