AppFolio 本地開發循環 是做什麼的?
概述
適用於 AppFolio 物業管理 API 整合的本地開發工作流程。提供快速的回饋循環,包含模擬的物業、租戶和租約端點,讓您能夠建置並測試整合,而不會消耗即時 API 配額。在模擬模式下進行快速迭代,並在沙箱模式下針對真實的 AppFolio Stack API 進行部署前驗證,兩者之間切換自如。
先決條件
- 僅限模擬的本地環境,包含合成的物業、租戶、租約和工單固定數據,其中不包含任何生產地址、姓名或付款資訊。
- 另外管理的沙箱憑證,以及針對專屬整合通道的已核准唯讀固定數據;本地開發伺服器絕不會載入此憑證。
- 一項日誌政策,僅記錄請求的格式和狀態,並為沙箱配額、固定數據重置和憑證輪替指定明確的負責人。
說明
- 僅在模擬模式下執行本地伺服器,並針對具有確定性固定數據的合成路由進行讀寫操作。
- 在進行任何沙箱連線檢查之前,先在單元測試中測試請求驗證、冪等性、資料遮罩和錯誤處理。
- 使用符合合約規範的受管理用戶端和一個已授權的唯讀固定數據,單獨執行沙箱通道;請勿將本地代理轉變為即時 API 通道。
- 當固定數據、憑證、請求預算或輸出遮罩無法驗證時,請停止操作,先修正環境再繼續。
環境設定
cp .env.example .env
# 在本地端保留提供者憑證為空白。預設為模擬模式。
# MOCK_MODE=true
npm install express axios dotenv tsx typescript @types/node
npm install -D vitest supertest @types/express
開發伺服器
// src/dev/server.ts
import express from "express";
const app = express();
app.use(express.json());
const MOCK = process.env.MOCK_MODE === "true";
if (!MOCK) throw new Error("本地伺服器僅限模擬;請使用受管理的沙箱整合通道");
const { mountMockRoutes } = require("./mocks");
mountMockRoutes(app);
app.listen(3001, () => console.log(`AppFolio 開發伺服器執行於 :3001 [mock=${MOCK}]`));
模擬模式
// src/dev/mocks.ts — 逼真的物業管理回應
```typescript
// src/dev/mocks.ts — 逼真的物業管理回應
export function mountMockRoutes(app: any) {
app.get("/api/v1/properties", (_req: any, res: any) => res.json([
{ id: "prop_1", name: "日落公寓", address: { street: "日落大道123號", city: "洛杉磯", state: "CA" }, property_type: "住宅", unit_count: 24 },
{ id: "prop_2", name: "市中心辦公室", address: { street: "主街456號", city: "舊金山", state: "CA" }, property_type: "商業", unit_count: 8 },
]));
app.get("/api/v1/tenants", (_req: any, res: any) => res.json([
{ id: "t1", first_name: "小明", last_name: "王", email: "[email protected]", unit_id: "u1", lease_id: "l1" },
]));
app.get("/api/v1/leases", (_req: any, res: any) => res.json([
{ id: "l1", unit_id: "u1", start_date: "2025-01-01", end_date: "2026-01-01", rent_amount: 2500, status: "active" },
]));
app.post("/api/v1/work-orders", (req: any, res: any) => res.status(201).json({ id: "wo_1", ...req.body, status: "open" }));
}
測試工作流程
npm run dev:mock & # 在背景啟動模擬伺服器
npm run test # 使用 vitest 執行單元測試
npm run test -- --watch # 監看模式,快速迭代
npm run test:sandbox # 受管理的唯讀沙箱通道
除錯提示
- 設定
DEBUG=express:*以追蹤所有路由匹配和中間件執行 - 對固定數據計數和結構綱要使用本地測試斷言,而非原始租戶資料傾印
- 在測試即時 API 時檢查
X-RateLimit-Remaining標頭 - AppFolio 沙箱會對非您擁有的物業回傳
403— 請驗證您的 API 金鑰範圍 - 開發期間,僅將攔截器用於遮罩後的端點/狀態/計數遙測
輸出
- 具有合成物業管理固定數據且無提供者憑證依賴的確定性模擬本地伺服器
- 針對驗證、冪等性和 PII 安全可觀測性的單元測試證據
- 僅包含遮罩後唯讀狀態的獨立受管理沙箱結果
範例
若要進行工單 UI 變更,請新增一個合成模擬固定數據,並在本地端測試請求綱要和重複提交行為。斷言回傳的 ID 和狀態,但不發出請求主體或租戶記錄。單元測試通過後,針對一個已核准的唯讀固定數據執行專屬沙箱通道。如果模擬模式被停用、本地出現沙箱憑證,或回應包含未遮罩的租戶欄位,請停止執行並恢復本地界限。
錯誤處理
| 問題 | 原因 | 修正 |
|---|---|---|
401 Unauthorized | API 金鑰無效或過期 | 在 AppFolio Stack 入口網站重新產生 |
403 Forbidden | 金鑰缺乏端點所需範圍 | 請求額外權限 |
404 Not Found | 錯誤的物業 ID 或路徑 | 驗證資源是否存在於沙箱中 |
429 Too Many Requests | 超過速率限制 | 加入指數退避,使用模擬模式 |
ECONNREFUSED :3001 | 開發伺服器未執行 | 先執行 npm run dev:mock |
資源
後續步驟
請參閱 appfolio-debug-bundle。