Instruction file imported from PancrePal-xiaoyibao/CodeForge (
.cursor/rules/api-first-development.mdc). Copyright stays with the author.
API-First 模块化开发框架
当项目涉及前后端分离、全栈开发、或任何需要多层协作的场景时，本规则自动生效。
核心架构：三层分离
前端层（Frontend） 中间层（Glue/BFF） 后端API包（Backend）
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 页面 & 组件 │ ←API→ │ 跨API编排 │ ←API→ │ 独立业务模块 │
│ 只调API+渲染 │ │ 数据聚合适配 │ │ 内聚逻辑封装 │
│ 不含业务逻辑 │ │ 耦合逻辑处理 │ │ 对外只暴露API │
└──────────────┘ └──────────────┘ └──────────────┘
后端 API 包标准开发流程
每个后端功能必须走完以下闭环：
开发（Implement） → Checkfix（Lint/Build） → 封装（Module/Class） → API暴露（Endpoint） → API文档（Doc）
- 一个 API 包只做一件事，对外只暴露 API 端点
- 完成开发后必须执行 Checkfix 闭环（参考 code-debugger 技术栈检查表）
- 封装为独立模块后暴露 REST/GraphQL/RPC 端点
- 必须生成 API 文档（见下方模板），前端开发者仅依据此文档调用
API 文档标准模板
每个 API 包完成后，在 docs/api/ 或模块目录下生成：
# [模块名] API 文档
## 端点概览
| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| POST | /api/v1/xxx | 描述 | Bearer Token |
## 详细接口
### [接口名称]
- **路径**: `POST /api/v1/xxx`
- **描述**: 功能说明
**请求参数**:
| 参数 | 位置 | 类型 | 必填 | 说明 |
|------|------|------|------|------|
| field | body | string | 是 | 描述 |
**响应格式**:
成功 (200):
```json
{ "code": 0, "data": { ... }, "message": "success" }失败 (4xx/5xx):
{ "code": 错误码, "data": null, "message": "错误描述" }错误码:
| 错误码 | 含义 | 处理建议 |
|---|
调用示例:
curl -X POST .../api/v1/xxx -H "Content-Type: application/json" -d '{...}'
## 前端开发规范
- 前端只负责：页面渲染 + 调用后端 API + 用户交互
- 业务逻辑全部在后端 API 包内，前端不重复实现
- 依据 API 文档开发，可与后端并行
## 中间层/全栈规范
- 只处理多个 API 包之间的编排和聚合
- 只处理前端特殊需求的数据适配（BFF 模式）
- 不重复实现后端已有的业务逻辑
## 跨层任务自动分解协议
当收到涉及多个层级的开发/debug 需求时（如"增加 SSE 流式输出"），必须按以下协议分解：
### Step 1: 层级识别
判断任务涉及哪些层：后端？前端？中间层？
### Step 2: 按 API 边界拆分子任务
子任务 1 [后端]: 开发 API 包（开发→Checkfix→封装→API端点→API文档） 子任务 2 [API文档]: 确保 API 契约清晰（请求/响应/错误码/示例） 子任务 3 [前端]: 依据 API 文档实现页面功能 子任务 4 [集成]: 验证前后端契约一致性
### Step 3: 严格按序执行
后端 API 包先行 → API 文档产出 → 前端/中间层消费 → 集成验证
## Debug 边界规则
| Bug 表现 | 归属层 | Debug 范围 | 禁止行为 |
|----------|--------|-----------|----------|
| API 返回错误数据 | 后端 | 只查 API 包内部逻辑 | 不改前端来"绕过" |
| 页面不显示/显示异常 | 前端 | 只查页面逻辑+API调用参数 | 不改后端API契约来迁就 |
| 多API协作异常 | 中间层 | 查编排逻辑+各API契约一致性 | 不进入单个API包内部改逻辑 |
| 前后端数据不匹配 | 集成 | 对照API文档检查契约一致性 | 先确定谁违反了契约再改 |
## 与其他 Skill 的协作
- **ai-spec**: 生成技术规格时默认采用本框架的三层分离架构
- **code-debugger**: Debug 时先判断模块类型（前端/后端API包/中间层），按边界规则定位
- **debug-ui**: 天然对应前端层，只处理页面和 API 调用
- **prd / ralph**: 拆分 User Story 时按 API 包粒度拆分（后端API包 → API文档 → 前端消费）