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}]`));
模拟模式
// 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 Sunset Blvd", city: "洛杉矶", state: "加利福尼亚州" }, property_type: "住宅", unit_count: 24 },
{ id: "prop_2", name: "市中心办公楼", address: { street: "456 Main St", city: "旧金山", state: "加利福尼亚州" }, 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。