109 lines
3.0 KiB
Markdown
109 lines
3.0 KiB
Markdown
# 01 — 接口契约
|
||
|
||
> **这是前后端共享的唯一真相来源。** 修改本文件 = 修改协议，必须同步更新所有端。
|
||
|
||
---
|
||
|
||
## 契约生命周期（任务拆分时决定）
|
||
|
||
契约由**任务拆分时先开工的那一端**负责起草。这是任务产出物之一，不是额外工作。
|
||
|
||
```
|
||
任务拆分阶段：
|
||
┌─ 任务A：后端-用户管理CRUD ──→ 产出：接口契约（后端起草）
|
||
│ + 后端代码
|
||
│
|
||
└─ 任务B：前端-用户管理页面 ──→ 拿到契约后对接
|
||
|
||
反过来：
|
||
┌─ 任务A：前端-首页改版 ──→ 产出：接口契约（前端起草）
|
||
│ + 前端页面
|
||
│
|
||
└─ 任务B：后端-首页数据接口 ──→ 按契约实现
|
||
```
|
||
|
||
**铁律**：
|
||
- 拆分任务时明确标注：**本任务包含接口契约起草**
|
||
- 契约随任务一起交付，不单独走审批
|
||
- 后开工的一方拿到契约后，发现问题直接跟起草方沟通修改
|
||
- 联调时对照本文件，不一致的以本文件为准
|
||
|
||
### 分仓库时契约放哪
|
||
|
||
```
|
||
Monorepo（推荐）： 分仓库：
|
||
项目根/ 后端仓库/ 前端仓库/
|
||
└── rules/ ├── rules/ ├── rules/
|
||
└── 01-接口契约.md │ └── 01-接口契约.md │ └── 01-接口契约.md
|
||
← git submodule 引用同一份 →
|
||
```
|
||
|
||
---
|
||
|
||
## 返回格式（不变式）
|
||
|
||
```json
|
||
// ✅ 唯一正确格式
|
||
{ "code": 200, "message": "success", "data": { ... } }
|
||
{ "code": 500, "message": "错误原因", "data": null }
|
||
|
||
// ❌ 永远不许出现
|
||
return data; // 裸对象
|
||
return "ok"; // 裸字符串
|
||
{ "success": true, "result": {...} } // 自造格式
|
||
```
|
||
|
||
---
|
||
|
||
## 分页格式（不变式）
|
||
|
||
```json
|
||
{ "list": [...], "total": 100, "pages": 10, "current": 1, "size": 10 }
|
||
```
|
||
|
||
---
|
||
|
||
## 接口命名约定
|
||
|
||
| 前缀 | 用途 | 示例 |
|
||
|------|------|------|
|
||
| `/admin/**` | 管理后台 | `/admin/user/list` |
|
||
| `/app/**` | 移动端/H5/小程序 | `/app/task/list` |
|
||
| `/auth/**` | 登录注册（共享） | `/auth/login` |
|
||
| `/open/**` | 对外开放接口 | `/open/callback` |
|
||
|
||
---
|
||
|
||
## 状态值映射表
|
||
|
||
**← 改这里 = 改协议，必须同步后端 + 所有前端。**
|
||
|
||
| 含义 | 后端值 | 前端显示 | 前端 CSS 类 |
|
||
|------|--------|----------|------------|
|
||
| [状态1] | [值] | [文字] | [class] |
|
||
| [状态2] | [值] | [文字] | [class] |
|
||
|
||
---
|
||
|
||
## 字段名桥接表
|
||
|
||
同一个概念在不同端字段名不同时，在此登记：
|
||
|
||
| 概念 | 后端字段 | 前端A字段 | 前端B字段 |
|
||
|------|----------|-----------|-----------|
|
||
| | | | |
|
||
|
||
---
|
||
|
||
## 契约同步铁律
|
||
|
||
```
|
||
改后端接口 → grep 所有前端 → 逐个同步 → 两端都通过才算完成
|
||
|
||
步骤：
|
||
1. 改之前：grep -r "接口路径" 所有前端目录/
|
||
2. 改后端 → 编译通过
|
||
3. 逐个改前端 → 构建通过
|
||
4. 更新本文件的映射表（如有新增状态值/字段差异）
|
||
```
|