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 不能为空" }

错误码

调用示例

[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 文档习惯）

不适用时不强行套用，但可借鉴"模块封装 + 接口文档"的核心思想。