AppFolio CI 整合
概述
配置 CI 管線,以雙層策略驗證 AppFolio 物業管理 API 的整合。單元測試會模擬 AppFolio REST 用戶端,以驗證房客查詢、工單建立和房源列表邏輯,而不耗用 API 配額。整合測試僅在主分支合併時,針對 AppFolio 沙箱環境執行,並使用儲存為 GitHub Secrets 的基本認證。這使得 PR 回饋快速且免費,同時在部署至生產環境前,及早發現真實的 API 合約變動。
先決條件
- 一個啟用 Actions、具有鎖定的相依性安裝以及僅使用合成房客、房產和工單固定數據的單元測試的儲存庫。
- 一個獨立管理的 AppFolio 沙箱憑證,以及一個預先配置好的、整合擁有者被允許讀取的非生產固定數據記錄。
- 定義的 CI 擁有者、固定的請求預算,以及用於處理憑證輪換、供應商中斷或沙箱數據重設的事件處理路徑。
指示
- 保持 Pull Request 檢查僅使用模擬;不要將 AppFolio 憑證暴露給不受信任的程式碼或 Fork 的 Pull Request。
- 將即時沙箱任務限制在受保護的
main推送,並在 lint、型別和單元檢查通過後執行,且僅透過儲存庫 Secrets 注入憑證。 - 將整合執行限制在一個已知的唯讀固定數據、一個工作執行緒和所述請求預算內;僅記錄經過修訂的狀態和計數證據。
- 將失敗的身份驗證、速率限制或缺少固定數據視為阻斷釋出的條件,而不是從 CI 建立共享的沙箱數據。
GitHub Actions 工作流程
# .github/workflows/appfolio-tests.yml
name: AppFolio API 測試
on: [push, pull_request]
jobs:
unit-tests:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci
- run: npm run lint && npm run typecheck
- run: npm test -- --testPathPattern=unit # 不需要 API 憑證
integration-tests:
runs-on: ubuntu-latest
if: github.event_name == 'push' && github.ref == 'refs/heads/main'
needs: unit-tests
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: '20' }
- run: npm ci
- run: npm test -- --testPathPattern=integration
env:
APPFOLIO_CLIENT_ID: ${{ secrets.APPFOLIO_CLIENT_ID }}
APPFOLIO_CLIENT_SECRET: ${{ secrets.APPFOLIO_CLIENT_SECRET }}
APPFOLIO_BASE_URL: ${{ secrets.APPFOLIO_SANDBOX_URL }}
基於模擬的單元測試
// tests/unit/work-order-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { createWorkOrder } from '../../src/services/work-order-service';
import * as appfolioClient from '../../src/lib/appfolio-client';
vi.mock('../../src/lib/appfolio-client');
describe('WorkOrderService', () => {
it('為一個物業建立維修工單', async () => {
vi.mocked(appfolioClient.post).mockResolvedValue({
id: 'wo-4821',
property_id: 'prop-100',
category: 'Plumbing',
status: 'Open',
});
const result = await createWorkOrder('prop-100', 'Plumbing', 'Leaking faucet unit 3B');
expect(result.status).toBe('Open');
expect(appfolioClient.post).toHaveBeenCalledWith('/work_orders', {
property_id: 'prop-100',
category: 'Plumbing',
description: 'Leaking faucet unit 3B',
});
});
});
整合測試
// tests/integration/tenant-lookup.test.ts
import { describe, it, expect } from 'vitest';
import { AppFolioClient } from '../../src/lib/appfolio-client';
const canRun = process.env.APPFOLIO_CLIENT_ID && process.env.APPFOLIO_CLIENT_SECRET;
describe.skipIf(!canRun)('AppFolio 房客查詢 (即時沙箱)', () => {
const client = new AppFolioClient({
clientId: process.env.APPFOLIO_CLIENT_ID!,
clientSecret: process.env.APPFOLIO_CLIENT_SECRET!,
baseUrl: process.env.APPFOLIO_BASE_URL!,
});
it('列出已知物業的房客', async () => {
const tenants = await client.get('/tenants', { property_id: 'prop-100' });
expect(Array.isArray(tenants)).toBe(true);
expect(tenants[0]).toHaveProperty('lease_status');
});
});
CI 成本管理
// tests/helpers/api-budget.ts
let callCount = 0;
const MAX_CALLS_PER_RUN = 25; // AppFolio 沙箱有 100 req/min 的速率限制
export function trackApiCall(): void {
callCount++;
if (callCount > MAX_CALLS_PER_RUN) {
throw new Error(
`CI API 預算超額:已進行 ${callCount}/${MAX_CALLS_PER_RUN} 次呼叫。` +
'請減少整合測試範圍或將測試拆分到多個任務中。'
);
}
}
export function getCallCount(): number { return callCount; }
錯誤處理
| CI 問題 | 原因 | 修復方法 |
|---|---|---|
| 整合任務中的 401 未授權 | 沙箱憑證過期或輪換 | 在 GitHub Secrets 中重新產生 APPFOLIO_CLIENT_ID 和 APPFOLIO_CLIENT_SECRET |
| 429 請求過多 | 並行測試達到沙箱速率限制 (100 req/min) | 使用 --maxWorkers=1 執行整合測試 |
| 房客列表為空 | AppFolio 定期重設沙箱數據 | 停止任務並在 CI 外部還原預先配置的固定數據 |
| API 回應的型別檢查失敗 | AppFolio 架構未經通知即更新 | 從 OpenAPI 規範重新產生型別,更新介面 |
| 整合任務被跳過 | 分支保護規則與 refs/heads/main 不匹配 | 驗證工作流程的 if 條件是否符合您的預設分支名稱 |
產出
- 來自僅使用模擬的 lint、型別和單元檢查的 Pull Request 結果
- 一個受保護分支的沙箱收據,包含經過修訂的供應商狀態、固定資料身份識別、請求計數和整合測試結果
- 一個有界限的釋出決策,當憑證不可用、供應商錯誤、固定資料漂移或請求預算耗盡時,會阻斷釋出
示例
對於工單映射的變更,請新增一個合成的模擬回應,並在 PR 套件中驗證新欄位。合併後,受保護的主分支工作流程會讀取一個預先配置的沙箱工單,並確認標準化後的資料形狀,而不會建立新的房客、物業或工單。如果固定資料不可用、憑證失敗或請求預算超額,請標記為釋出受阻,並讓沙箱擁有者在重新執行即時流程之前,先還原固定資料或憑證。
資源
後續步驟
請參閱 appfolio-deploy-integration。