# API First Modular

> API-First 模块化开发框架 — 后端功能封装为独立 API 包，前端只调 API，全栈只做编排，跨层任务自动分解。适用于所有涉及前后端的开发与调试任务，包括：(1) 后端功能开发（需走 5 步闭环），(2) 前端页面开发（需依据 API 文档），(3) 跨层需求拆分（需按 API 边界分解），(4) Bug 修复（需先判定归属层再定位）。 Use when this capability is needed.

- Skill: `tomevault-io/api-first-modular` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/api-first-modular`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/api-first-modular/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/api-first-modular

---


# API-First 模块化开发框架

> **后端每个功能 = 一个独立 API 包。前端只调 API + 渲染页面。全栈只做多个 API 包之间的编排。**

这是**强制约束**，所有涉及前后端的开发和调试任务都必须遵循。

---

## 三层架构模型

```
┌─────────────────────────────────────────────────────────────────┐
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐       │
│  │  前端层       │   │  中间层/BFF  │   │  后端API包    │       │
│  │  Frontend    │◄─►│  Glue / BFF  │◄─►│  Backend     │       │
│  │              │   │              │   │              │       │
│  │ 职责:        │   │ 职责:        │   │ 职责:        │       │
│  │ • 页面渲染   │   │ • 跨API编排  │   │ • 业务逻辑   │       │
│  │ • 用户交互   │   │ • 数据聚合   │   │ • 数据处理   │       │
│  │ • API调用    │   │ • 适配转换   │   │ • API暴露    │       │
│  │ • 状态管理   │   │ • 鉴权中继   │   │ • API文档    │       │
│  │              │   │              │   │              │       │
│  │ 禁止:        │   │ 禁止:        │   │ 禁止:        │       │
│  │ • 业务逻辑   │   │ • 重复后端   │   │ • 关心前端   │       │
│  │ • 直连数据库 │   │   已有逻辑   │   │   如何渲染   │       │
│  └──────────────┘   └──────────────┘   └──────────────┘       │
└─────────────────────────────────────────────────────────────────┘
```

### 层级判断规则

| 如果任务涉及… | 归属层 | 处理方式 |
|---------------|--------|----------|
| 页面布局、组件、样式、用户交互 | 前端 | 前端开发 |
| 数据库操作、算法、业务规则 | 后端API包 | 后端开发 |
| 多个API的组合调用、数据聚合 | 中间层 | 全栈开发 |
| 前后端数据格式不匹配 | 集成问题 | 先查API文档契约 |

---

## 后端 API 包标准开发流程（5 步闭环）

每个后端功能**必须走完以下 5 步**：

```
开发 ──► Checkfix ──► 封装 ──► API端点 ──► API文档
```

1. **开发 (Implement)** — 实现核心业务逻辑，编写单元测试，遵循单一职责
2. **Checkfix 闭环** — 执行技术栈对应的 lint/build 检查，失败则修复并复跑直至通过
3. **封装 (Encapsulate)** — 封装为独立模块/类/包，明确输入输出接口，隐藏内部实现
4. **API 暴露 (Expose)** — 创建 API 端点（REST/GraphQL/RPC/WebSocket/SSE），统一响应格式，添加输入验证、错误处理、鉴权
5. **API 文档 (Document)** — 按标准模板生成文档，文档是前端开发的唯一依据，必须与代码同步

---

## API 文档标准模板

每个 API 包完成后，在 `docs/api/` 或模块目录下生成：

```markdown
# [模块名] 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 调用层：

```typescript
// 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 流式输出功能"**：
1. [后端] 创建 SSE 端点 API 包 → Checkfix 通过
2. [文档] 编写 SSE 接口文档 → `docs/api/sse-stream.md`
3. [前端] EventSource 调用 + 流式 UI 渲染 + 断线重连
4. [集成] 端到端测试

**"增加用户认证功能"**：
1. [后端] 用户认证 API 包（注册/登录/Token刷新/登出）
2. [后端] 认证中间件包（Token校验/权限检查）
3. [文档] 认证接口文档
4. [前端] 登录/注册页面 + Token管理 + 路由守卫
5. [中间层] 认证中间件集成到网关
6. [集成] 完整认证流程测试

---

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

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

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hhx465453939) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->