samqin123 API-First 模块化开发框架
后端每个功能 = 一个独立 API 包。前端只调 API + 渲染页面。全栈只做多个 API 包之间的编排。
这是强制约束，所有涉及前后端的开发和调试任务都必须遵循。
三层架构模型
┌─────────────────────────────────────────────────────────────────┐
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 前端层 │ │ 中间层/BFF │ │ 后端API包 │ │
│ │ Frontend │◄─►│ Glue / BFF │◄─►│ Backend │ │
│ │ │ │ │ │ │ │
│ │ 职责: │ │ 职责: │ │ 职责: │ │
│ │ • 页面渲染 │ │ • 跨API编排 │ │ • 业务逻辑 │ │
│ │ • 用户交互 │ │ • 数据聚合 │ │ • 数据处理 │ │
│ │ • API调用 │ │ • 适配转换 │ │ • API暴露 │ │
│ │ • 状态管理 │ │ • 鉴权中继 │ │ • API文档 │ │
│ │ │ │ │ │ │ │
│ │ 禁止: │ │ 禁止: │ │ 禁止: │ │
│ │ • 业务逻辑 │ │ • 重复后端 │ │ • 关心前端 │ │
│ │ • 直连数据库 │ │ 已有逻辑 │ │ 如何渲染 │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
层级判断规则
| 如果任务涉及… | 归属层 | 处理方式 |
|---|---|---|
| 页面布局、组件、样式、用户交互 | 前端 | 前端开发 |
| 数据库操作、算法、业务规则 | 后端API包 | 后端开发 |
| 多个API的组合调用、数据聚合 | 中间层 | 全栈开发 |
| 前后端数据格式不匹配 | 集成问题 | 先查API文档契约 |
后端 API 包标准开发流程（5 步闭环）
每个后端功能必须走完以下 5 步：
开发 ──► Checkfix ──► 封装 ──► API端点 ──► API文档
- 开发 (Implement) — 实现核心业务逻辑，编写单元测试，遵循单一职责
- Checkfix 闭环 — 执行技术栈对应的 lint/build 检查，失败则修复并复跑直至通过
- 封装 (Encapsulate) — 封装为独立模块/类/包，明确输入输出接口，隐藏内部实现
- API 暴露 (Expose) — 创建 API 端点（REST/GraphQL/RPC/WebSocket/SSE），统一响应格式，添加输入验证、错误处理、鉴权
- API 文档 (Document) — 按标准模板生成文档，文档是前端开发的唯一依据，必须与代码同步
API 文档标准模板
每个 API 包完成后，在 docs/api/ 或模块目录下生成：
# [模块名] API 文档
> 最后更新: [YYYY-MM-DD] | 版本: v1.0
## 概览
[模块的业务功能简介，1-2 句话]
## Base URL
`/api/v1/[module-name]`
## 认证方式
[Bearer Token / API Key / Session / 无认证]
## 端点列表
| 方法 | 路径 | 功能 | 认证 |
|------|------|------|------|
## 详细接口
### [接口名称]
- **路径**: `[METHOD] /api/v1/xxx`
- **功能**: [功能描述]
- **认证**: [是/否]
#### 请求参数
| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
#### 响应格式
**成功 (200)**:
{ "code": 0, "data": {...}, "message": "success" }
**失败 (4xx/5xx)**:
{ "code": 40001, "data": null, "message": "参数错误：field1 不能为空" }
#### 错误码
| 错误码 | HTTP状态码 | 含义 | 处理建议 |
|--------|-----------|------|----------|
#### 调用示例
[curl 示例]
## 特殊协议
[WebSocket / SSE / 长轮询等非标准协议的连接方式、事件格式、重连策略]
前端开发规范
允许：页面渲染、组件开发、调用后端 API（依据文档）、前端状态管理、用户交互处理、错误展示
禁止：在前端实现业务逻辑、直接连接数据库、绕过 API 层、硬编码本应由后端提供的数据
前端统一封装 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 规范
仅在以下场景存在：
| 场景 | 职责 | 示例 |
|---|---|---|
| 多API聚合 | 组合多个后端API结果 | Dashboard 聚合用户+订单+统计 |
| 协议转换 | gRPC/消息队列 → REST/WebSocket | Kafka 推送 → SSE |
| 鉴权网关 | 统一 Token 校验、权限检查 | API Gateway |
| 数据适配 | 针对特定前端裁剪数据 | 移动端精简字段 |
禁止：重复后端已有逻辑、中间层直连数据库、把中间层写成"超级后端"。
跨层任务自动分解协议（核心）
收到涉及多层的开发/调试需求时，必须执行：
分解流程
收到跨层需求
│
▼
Step 1: 层级识别 — 该任务涉及哪些层？（后端/前端/中间层）
│
▼
Step 2: 按 API 边界拆分为有序子任务
│
▼
Step 3: 严格按序执行 — 后端先行 → 文档产出 → 前端消费 → 集成验证
典型分解示例
"增加 SSE 流式输出功能"：
- [后端] 创建 SSE 端点 API 包 → Checkfix 通过
- [文档] 编写 SSE 接口文档 →
docs/api/sse-stream.md - [前端] EventSource 调用 + 流式 UI 渲染 + 断线重连
- [集成] 端到端测试
"增加用户认证功能"：
- [后端] 用户认证 API 包（注册/登录/Token刷新/登出）
- [后端] 认证中间件包（Token校验/权限检查）
- [文档] 认证接口文档
- [前端] 登录/注册页面 + Token管理 + 路由守卫
- [中间层] 认证中间件集成到网关
- [集成] 完整认证流程测试
Debug 边界规则
分层定位
Bug 出现
├─ API 返回错误数据？ ───► 后端 Debug（只查 API 包内部）
├─ 页面显示异常？ ────────► 前端 Debug（确认 API 返回是否正确）
├─ 多 API 协作异常？ ────► 中间层 Debug（各 API 单独调用是否正常？）
└─ 前后端数据不匹配？ ──► 契约 Debug（对照 API 文档，改违反方）
Debug 禁止行为
| 禁止 | 原因 |
|---|---|
| 改前端代码来绕过后端 Bug | 治标不治本 |
| 改后端 API 契约来迁就前端 Bug | 影响所有调用方，破坏契约 |
| 在前端做本应在后端的数据校验 | 违反职责分离 |
| 不确认问题归属层就动手 | 在错误层浪费时间 |
与 PRD / Ralph 的协作
User Story 应按 API 包粒度拆分：
正确：
US-001: [后端] 创建用户认证 API 包（注册/登录 + 单元测试）
US-002: [后端] 创建认证中间件包（Token校验 + 权限检查）
US-003: [文档] 编写认证模块 API 文档
US-004: [前端] 实现登录/注册页面（依据 API 文档）
US-005: [集成] 端到端认证流程验证
错误：
US-001: 实现用户认证功能（包括前后端）← 太大，跨层
US-002: 优化认证体验 ← 太模糊，不可验证
适用边界
适用：前后端分离项目、全栈项目（SSR+API）、微服务/微前端架构、多人/多AI协作项目
不强制适用：纯脚本/CLI、纯数据处理/ETL、嵌入式/系统级、原型验证阶段（可简化但保留 API 文档习惯）
不适用时不强行套用，但可借鉴"模块封装 + 接口文档"的核心思想。