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 包
-
Mock first Frontend develops with MSW Mock Switch after backend is ready
-
Error code mapping table Backend error.code → frontend toast / field error
-
Integrate while writing Don't wait until everything is written to integrate
-
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
- Inconsistent field names——backend snake_case frontend camelCase
- Inconsistent types——backend string ID frontend number
- CORS not configured——blocked by browser
- Token location incorrect——Cookie vs Header
- Error codes not mapped——frontend displays "INTERNAL_ERROR"
- Pagination parameters incorrect——does page start from 0 or 1
- Inconsistent time format——ISO 8601 vs timestamp
- Empty array vs null——frontend .map() crashes
- Large number precision loss——JSON number > 2^53
- File upload Content-Type incorrect——not JSON
Collaboration with other skills
上游:
e2e-feature-delivery → 联调是交付的一部分
database-schema-impl → 字段来源
下游:
deploy-preview → 联调通过后部署