AppFolio CI 集成
概述
配置 CI 流水线,使用双层策略验证 AppFolio 物业管理 API 集成。单元测试模拟 AppFolio REST 客户端,在不消耗 API 配额的情况下验证租户查询、工单创建和物业列表逻辑。集成测试仅在主分支合并时针对 AppFolio 沙箱环境运行,使用存储为 GitHub Secrets 的基本认证凭据。这使 PR 反馈保持快速且免费,同时在生产部署前捕获真实的 API 契约漂移。
前提条件
- 一个已启用 Actions、依赖安装已锁定,并且单元测试仅使用合成租户、物业和工单夹具的仓库。
- 一个单独管理的 AppFolio 沙箱凭据,以及一个由集成负责人授权读取的、预配的非生产夹具记录。
- 定义好的 CI 负责人、固定的请求预算,以及用于凭据轮换、提供商故障或沙箱数据重置的事件处理路径。
说明
- 保持拉取请求检查仅使用模拟;不要将 AppFolio 凭据暴露给不可信代码或复刻的拉取请求。
- 在 lint、类型检查和单元检查通过后,将实时沙箱作业限制为受保护的
main推送,并仅通过仓库 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 次请求/分钟的速率限制
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 次请求/分钟) | 使用 --maxWorkers=1 运行集成测试 |
| 租户列表为空 | AppFolio 定期重置沙箱数据 | 停止作业并在 CI 外部恢复预配的夹具 |
| API 响应类型检查失败 | AppFolio 架构未经通知已更新 | 从 OpenAPI 规范重新生成类型,更新接口 |
| 集成作业被跳过 | 分支保护规则与 refs/heads/main 不匹配 | 验证工作流的 if 条件是否与您的默认分支名称匹配 |
输出
- 来自仅模拟的 lint、类型和单元检查的拉取请求结果
- 一个受保护分支的沙箱收据,包含脱敏的提供商状态、夹具身份、请求计数和集成测试结果
- 一个有限的发布决策,在凭据不可用、提供商错误、夹具漂移或请求预算耗尽时阻塞
示例
对于工单映射更改,添加一个合成模拟响应并在 PR 套件中验证新字段。合并后,受保护的 main 工作流读取一个预配的沙箱工单并确认标准化形状,而无需创建租户、物业或工单。如果夹具不可用、凭据失败或请求预算超出,则将发布标记为阻塞,并在重新运行实时通道之前由沙箱所有者恢复夹具或凭据。
资源
后续步骤
参见 appfolio-deploy-integration。