SuperAPI AI Directory

api-frontend-integration

Coding & development

View repository

Updated 10-16 09:30

About this skill

Frontend-Backend Integration (API-Frontend Integration)

Applicable Scenarios

  • Switching from Mock to real API
  • Frontend-backend field name / type alignment
  • Error code → frontend prompt mapping
  • Token / Cookie passing verification
  • Pagination / filtering / sorting parameter integration
  • File upload integration
  • WebSocket / SSE integration

Core Principles

1. 类型共享(TypeScript 端到端)
   tRPC / OpenAPI 生成 / 共享 types 包
  1. Mock first Frontend develops with MSW Mock Switch after backend is ready

  2. Error code mapping table Backend error.code → frontend toast / field error

  3. Integrate while writing Don't wait until everything is written to integrate

  4. Integration checklist Verify each endpoint one by one


## 类型共享方案

### tRPC(最佳,端到端类型安全)

```typescript
// server/router.ts
export const appRouter = router({
  orders: {
    list: publicProcedure
      .input(z.object({ page: z.number(), status: z.string().optional() }))
      .query(async ({ input }) => {
        return await db.order.findMany({ where: { status: input.status } });
      }),
    create: publicProcedure
      .input(createOrderSchema)
      .mutation(async ({ input }) => {
        return await db.order.create({ data: input });
      }),
  },
});

export type AppRouter = typeof appRouter;

// client(自动类型推导)
const { data } = trpc.orders.list.useQuery({ page: 1 });
// data 类型自动推导,无需手写

OpenAPI generated types

# 从 OpenAPI spec 生成 TypeScript 类型
npx openapi-typescript api.yaml -o src/types/api.ts

# 或用 orval 生成 hooks
npx orval --input api.yaml --output src/api/

Shared types package (Monorepo)

packages/
├── types/           ← 共享类型
│   └── src/
│       ├── order.ts
│       └── user.ts
├── api/             ← 后端
└── web/             ← 前端

Mock → real switching

// 1. 开发时用 MSW
// mocks/handlers.ts
export const handlers = [
  http.get('/api/orders', () => HttpResponse.json(mockOrders)),
];

// 2. 后端就绪后关闭 MSW
// 环境变量控制
if (import.meta.env.VITE_ENABLE_MOCKS === 'true') {
  const { worker } = await import('./mocks/browser');
  worker.start();
}

// 3. 切换后逐条验证

Integration checklist (each endpoint)

□ URL 路径一致
□ HTTP 方法一致
□ 请求字段名一致(snake_case / camelCase)
□ 请求字段类型一致
□ 响应字段名一致
□ 响应字段类型一致
□ 分页参数(page / limit / cursor)
□ 排序参数(sort / order)
□ 筛选参数
□ 错误码 → 前端处理
□ Token 传递(Header / Cookie)
□ CORS 配置
□ Content-Type 正确
□ 文件上传(multipart)
□ 空结果处理
□ 大数据量(分页正确)

Error code mapping

// 后端返回
{ "error": { "code": "INSUFFICIENT_STOCK", "message": "库存不足" } }

// 前端映射
const ERROR_MESSAGES: Record<string, string> = {
  VALIDATION_ERROR: '请检查输入',
  INSUFFICIENT_STOCK: '库存不足,请减少数量',
  RESOURCE_NOT_FOUND: '数据不存在',
  FORBIDDEN: '无权限',
  RATE_LIMITED: '操作过于频繁,请稍后重试',
};

function handleApiError(error: ApiError) {
  const message = ERROR_MESSAGES[error.code] ?? '操作失败,请重试';
  toast.error(message);
  
  // 字段级错误
  if (error.code === 'VALIDATION_ERROR' && error.details) {
    error.details.forEach(d => form.setError(d.field, { message: d.message }));
  }
}

Supporting templates

  • templates/integration-checklist.md — Integration checklist + error mapping + type sharing solution

Quality self-check

□ 类型共享(tRPC / OpenAPI / 共享包)
□ Mock 先行(MSW)
□ 每个端点逐条联调
□ 错误码映射完整
□ Token 传递正确
□ CORS 配置正确
□ 分页 / 筛选对接
□ 空结果处理
□ 文件上传(如有)
□ 联调后 Mock 可关闭

Common pitfalls

  1. Inconsistent field names——backend snake_case frontend camelCase
  2. Inconsistent types——backend string ID frontend number
  3. CORS not configured——blocked by browser
  4. Token location incorrect——Cookie vs Header
  5. Error codes not mapped——frontend displays "INTERNAL_ERROR"
  6. Pagination parameters incorrect——does page start from 0 or 1
  7. Inconsistent time format——ISO 8601 vs timestamp
  8. Empty array vs null——frontend .map() crashes
  9. Large number precision loss——JSON number > 2^53
  10. File upload Content-Type incorrect——not JSON

Collaboration with other skills

上游:
  e2e-feature-delivery → 联调是交付的一部分
  database-schema-impl → 字段来源

下游:
  deploy-preview → 联调通过后部署