微信扫一扫API-First 模块化开发框架
你现在遵循 API-First 模块化开发方法论。这是一套适用于所有 AI 辅助开发场景的基础架构规范，确保代码的可维护性、可调试性和前后端解耦。
核心理念
后端每个功能 = 一个独立 API 包。前端只调 API + 渲染页面。全栈只做多个 API 包之间的编排。
这不是建议，是强制约束。所有涉及前后端的开发和调试任务都必须遵循此框架。
一、三层架构模型
┌─────────────────────────────────────────────────────────────────────┐
│ 项目整体架构 │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 前端层 │ │ 中间层 │ │ 后端API包 │ │
│ │ Frontend │◄───►│ Glue / BFF │◄───►│ Backend │ │
│ │ │ │ │ │ │ │
│ │ 职责: │ │ 职责: │ │ 职责: │ │
│ │ • 页面渲染 │ │ • 跨API编排 │ │ • 业务逻辑 │ │
│ │ • 用户交互 │ │ • 数据聚合 │ │ • 数据处理 │ │
│ │ • API调用 │ │ • 适配转换 │ │ • API暴露 │ │
│ │ • 状态管理 │ │ • 鉴权中继 │ │ • API文档 │ │
│ │ │ │ │ │ │ │
│ │ 禁止: │ │ 禁止: │ │ 禁止: │ │
│ │ • 业务逻辑 │ │ • 重复后端 │ │ • 关心前端 │ │
│ │ • 直连数据库 │ │ 已有逻辑 │ │ 如何渲染 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────┘
层级判断规则
| 如果任务涉及… | 归属层 | 谁来做 | |---------------|--------|--------| | 页面布局、组件、样式、用户交互 | 前端 | 前端开发 / debug-ui | | 数据库操作、算法、业务规则 | 后端API包 | 后端开发 / code-debugger | | 多个API的组合调用、数据聚合 | 中间层 | 全栈开发 | | 前后端数据格式不匹配 | 集成问题 | 先查API文档契约 |
二、后端 API 包标准开发流程
每个后端功能必须走完以下 5 步闭环：
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 1.开发 │───►│2.Checkfix│───►│ 3.封装 │───►│ 4.API │───►│5.API文档 │
│ Implement│ │Lint/Build│ │Module/Cls│ │Endpoint │ │Document │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
Step 1: 开发 (Implement)
- 实现核心业务逻辑
- 编写单元测试
- 遵循单一职责原则
Step 2: Checkfix 闭环
- 根据技术栈执行自动检查（参考 code-debugger 的技术栈检查表）
- 失败则修复并复跑，直至通过
- 结果记录到
.debug文档
Step 3: 封装 (Encapsulate)
- 将逻辑封装为独立模块/类/包
- 明确模块的输入输出接口
- 对外隐藏内部实现细节
Step 4: API 暴露 (Expose API)
- 创建 API 端点（REST / GraphQL / RPC / WebSocket / SSE）
- 统一响应格式
- 添加输入验证、错误处理、鉴权中间件
Step 5: API 文档 (Document)
- 按下方模板生成 API 文档
- 文档是前端开发的唯一依据
- 文档与代码必须同步更新
三、API 文档标准模板
每个 API 包完成后，必须在 docs/api/ 或模块目录下生成以下文档：
# [模块名] API 文档
> 最后更新: [YYYY-MM-DD]
> 版本: v1.0
> 维护者: [开发者/AI]
## 概览
[模块的业务功能简介，1-2 句话]
## Base URL
`/api/v1/[module-name]`
## 认证方式
[Bearer Token / API Key / Session / 无认证]
## 端点列表
| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
| GET | /api/v1/xxx | 查询XXX | 是 |
| POST | /api/v1/xxx | 创建XXX | 是 |
## 详细接口
### 1. [接口名称]
- **路径**: `[METHOD] /api/v1/xxx`
- **功能**: [功能描述]
- **认证**: [是/否]
#### 请求参数
**Headers**:
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| Authorization | string | 是 | Bearer {token} |
**Query Parameters** (GET) / **Request Body** (POST/PUT):
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| field1 | string | 是 | - | 描述 |
| field2 | number | 否 | 10 | 描述 |
#### 响应格式
**成功 (200)**:
```json
{
"code": 0,
"data": {
"id": "xxx",
"field1": "value"
},
"message": "success"
}
失败 (4xx/5xx):
{
"code": 40001,
"data": null,
"message": "参数错误：field1 不能为空"
}
错误码
| 错误码 | HTTP状态码 | 含义 | 处理建议 | |--------|-----------|------|----------| | 40001 | 400 | 参数校验失败 | 检查请求参数 | | 40101 | 401 | 未授权 | 检查Token | | 50001 | 500 | 服务内部错误 | 联系后端/查日志 |
调用示例
curl -X POST https://host/api/v1/xxx
-H "Content-Type: application/json"
-H "Authorization: Bearer {token}"
-d '{"field1": "value"}'
特殊协议
[如有 WebSocket / SSE / 长轮询等非标准 HTTP 协议，在此描述连接方式、事件格式、重连策略]
---
## 四、前端开发规范
### 允许做的事
- 页面渲染和组件开发
- 调用后端 API（依据 API 文档）
- 前端状态管理（UI 状态、表单状态）
- 用户交互处理（事件绑定、路由）
- 错误展示（将 API 错误码翻译为用户友好提示）
### 禁止做的事
- 在前端实现业务逻辑（计算、校验规则应在后端）
- 直接连接数据库
- 绕过 API 层直接访问后端内部接口
- 在前端硬编码本应由后端提供的配置/数据
### 前端调用 API 的标准模式
```typescript
// 推荐：封装统一的 API 调用层
// src/api/[module-name].ts
import { request } from '@/utils/request'; // 统一请求工具
export const moduleNameApi = {
getList: (params: ListParams) => request.get('/api/v1/xxx', { params }),
create: (data: CreateData) => request.post('/api/v1/xxx', data),
update: (id: string, data: UpdateData) => request.put(`/api/v1/xxx/${id}`, data),
delete: (id: string) => request.delete(`/api/v1/xxx/${id}`),
};
五、中间层 / 全栈规范
中间层（也叫 BFF - Backend For Frontend）只在以下场景存在：
| 场景 | 中间层职责 | 示例 | |------|-----------|------| | 多API聚合 | 将多个后端API的结果组合为一个前端需要的数据结构 | Dashboard 需要同时请求用户API+订单API+统计API | | 协议转换 | 将后端的 gRPC/消息队列 转为前端可用的 REST/WebSocket | 后端用 Kafka 推送，前端需要 SSE 接收 | | 鉴权网关 | 统一处理 Token 校验、权限检查 | API Gateway 层 | | 数据适配 | 针对特定前端（Web/Mobile/小程序）做数据裁剪 | 移动端不需要桌面端的完整字段 |
禁止做的事
- 重复实现后端 API 包内已有的业务逻辑
- 在中间层做数据库直连操作
- 把中间层写成一个"超级后端"
六、跨层任务自动分解协议（核心）
这是本框架最关键的部分。 当 AI 收到一个涉及多个层级的开发或调试需求时，必须执行以下分解协议：
分解流程
┌────────────────────────────────────────────────┐
│ 收到跨层开发/调试需求 │
│ 例如: "增加前端 SSE 流式输出功能" │
└──────────────────────┬─────────────────────────┘
│
▼
┌────────────────────────────────────────────────┐
│ Step 1: 层级识别 │
│ 该任务涉及哪些层？ │
│ → 后端 ✓ (SSE 端点) │
│ → 前端 ✓ (EventSource 消费 + UI 渲染) │
│ → 中间层 ? (可能需要代理/CORS 配置) │
└──────────────────────┬─────────────────────────┘
│
▼
┌────────────────────────────────────────────────┐
│ Step 2: 按 API 边界拆分为有序子任务 │
│ │
│ ① [后端] 开发 SSE API 包 │
│ 开发 → Checkfix → 封装 → SSE端点 → API文档 │
│ │
│ ② [API文档] 编写 SSE 接口文档 │
│ 事件格式、数据结构、重连策略、错误处理 │
│ │
│ ③ [前端] 依据 API 文档实现前端消费 │
│ EventSource/fetch → 流式渲染 → 错误处理 │
│ │
│ ④ [集成] 端到端验证 │
│ 前后端契约一致性 → 异常场景 → 性能 │
└──────────────────────┬─────────────────────────┘
│
▼
┌────────────────────────────────────────────────┐
│ Step 3: 严格按序执行 │
│ 后端先行 → 文档产出 → 前端消费 → 集成验证 │
│ 每个子任务内部遵循各层的开发规范 │
└────────────────────────────────────────────────┘
典型跨层场景分解示例
场景 1: "增加 SSE 流式输出功能"
| 序号 | 层级 | 子任务 | 产出 |
|------|------|--------|------|
| 1 | 后端 | 创建 SSE 端点 API 包：实现数据推送逻辑、心跳机制、连接管理 | SSE API 包 + Checkfix 通过 |
| 2 | API文档 | 编写 SSE 接口文档：事件类型、数据格式、重连策略、错误码 | docs/api/sse-stream.md |
| 3 | 前端 | 实现 EventSource 调用 + 流式 UI 渲染 + 断线重连 + 加载状态 | 前端组件 + Checkfix 通过 |
| 4 | 集成 | 端到端测试：正常推送、中断恢复、错误处理、并发连接 | 集成测试通过 |
场景 2: "增加用户认证功能"
| 序号 | 层级 | 子任务 | 产出 |
|------|------|--------|------|
| 1 | 后端 | 用户认证 API 包：注册/登录/Token刷新/登出 | Auth API 包 |
| 2 | 后端 | 认证中间件 API 包：Token校验/权限检查 | Middleware 包 |
| 3 | API文档 | 认证接口文档：端点、Token格式、过期策略、错误码 | docs/api/auth.md |
| 4 | 前端 | 登录/注册页面 + Token管理 + 路由守卫 + 自动刷新 | 前端 Auth 模块 |
| 5 | 中间层 | 将认证中间件集成到 API 网关/路由 | 网关配置 |
| 6 | 集成 | 完整认证流程测试 | E2E 测试通过 |
场景 3: "Dashboard 数据加载太慢"（性能调试）
| 序号 | 层级 | 子任务 | 产出 | |------|------|--------|------| | 1 | 诊断 | 定位瓶颈在哪层：前端渲染？API响应？数据库查询？ | 瓶颈定位报告 | | 2 | 后端 | （若后端慢）优化 API 包内部：查询优化/缓存/索引 | 优化后的 API 包 | | 3 | 前端 | （若前端慢）优化渲染：虚拟滚动/懒加载/缓存策略 | 优化后的组件 | | 4 | 中间层 | （若聚合慢）优化编排：并行请求/缓存聚合结果 | 优化后的BFF |
七、Debug 边界规则
分层定位原则
Bug 出现
│
├─ API 返回错误数据？ ──────► 后端 Debug（只查 API 包内部）
│ 修复后 API 契约不变
│
├─ 页面显示异常？ ──────────► 前端 Debug（只查页面 + API调用参数）
│ 确认 API 返回数据是否正确
│
├─ 多 API 协作异常？ ──────► 中间层 Debug（查编排逻辑）
│ 各 API 单独调用是否正常？
│
└─ 前后端数据不匹配？ ─────► 契约 Debug（对照 API 文档）
谁违反了契约？改违反方
Debug 禁止行为
| 禁止 | 原因 | |------|------| | 改前端代码来绕过后端 Bug | 治标不治本，后端 Bug 依然存在 | | 改后端 API 契约来迁就前端 Bug | 影响所有调用方，破坏契约 | | 在前端做本应在后端的数据校验 | 违反职责分离 | | Debug 时不确认问题归属层就动手 | 可能在错误的层浪费时间 |
.debug 文档扩展
在使用 code-debugger 时，.debug 文档的元信息中应增加：
## 元信息
| 字段 | 值 |
|------|-----|
| **模块名称** | [Module Name] |
| **模块类型** | 前端模块 / 后端API包 / 中间层 / 全栈集成 |
| **API文档路径** | （后端API包时填写）docs/api/xxx.md |
| **API契约版本** | v1.0 |
八、与 PRD / Ralph 的协作
当使用 PRD + Ralph 自主循环开发时，User Story 应按本框架拆分：
正确的 Story 拆分（API 包粒度）
US-001: [后端] 创建用户认证 API 包（注册/登录端点 + 单元测试）
US-002: [后端] 创建认证中间件包（Token校验 + 权限检查）
US-003: [文档] 编写认证模块 API 文档
US-004: [前端] 实现登录/注册页面（依据 API 文档调用）
US-005: [前端] 实现路由守卫和 Token 自动刷新
US-006: [集成] 端到端认证流程验证
错误的 Story 拆分
US-001: 实现用户认证功能（包括前后端） ← 太大，跨层
US-002: 优化认证体验 ← 太模糊，不可验证
九、适用边界
本框架适用于
- 前后端分离项目（SPA + API）
- 全栈项目（SSR + API）
- 微服务/微前端架构
- 任何需要多人/多AI协作的项目
本框架不强制适用于
- 纯脚本/CLI 工具（无前后端概念）
- 纯数据处理/ETL 管道
- 嵌入式/系统级编程
- 原型验证/快速实验阶段（可简化流程但保留 API 文档习惯）
遇到不适用的场景时，不要强行套用，但可以借鉴"模块封装 + 接口文档"的核心思想。