# API集成

## 规则（Rules）

# API接口联调规范

## 适用对象和范围

本规范适用于所有前后端API联调对接的场景，包括阅读接口文档、测试入参传参、编写数据转换协议。

---

## 1. 以接口文档为准

**规则**：联调过程中必须以API接口设计文档为准，禁止直接对照代码联调。

- ✅ 正确：先读取API文档，再对照后端实现
- ❌ 错误：直接看后端代码猜测接口格式

**违反后果**：脱离文档联调导致接口规范不一致，后续维护困难。

---

## 2. 数据转换规范

**规则**：禁止在前端直接修改后端返回的原始数据结构，必须通过转换函数处理。

- ✅ 正确：定义 `transformResponse()` 函数进行数据转换
- ❌ 错误：`response.data.user_id = response.data.id; delete response.data.id;`

**违反后果**：直接修改原始数据导致后续代码逻辑混乱，难以追踪数据来源。

---

## 3. 异常场景测试规范

**规则**：必须测试异常场景，包括空数据、错误参数、网络超时等。

- ✅ 正确：测试空列表返回、参数缺失、超时等情况
- ❌ 错误：只测试正常路径

**违反后果**：未测试异常场景导致线上出现问题时无法处理。

---

## 4. 联调记录规范

**规则**：联调结果必须记录到联调报告中，每个接口的状态必须明确标注。

| 状态 | 含义 |
|------|------|
| ✅ 通过 | 请求和响应均正常 |
| ⚠️ 有差异 | 存在字段名或格式差异，已记录 |
| ❌ 失败 | 接口不可用或返回错误 |

**违反后果**：不记录联调结果导致问题追踪困难，不知道哪些接口已完成联调。

## 方法（Methods）

# API接口联调方法

## 前置条件

- [ ] 已有API接口设计文档（路由、参数、响应格式）
- [ ] 后端已完成API接口实现
- [ ] 前端已编写完页面和交互逻辑

## 流程概览

分析接口文档 → 检查后端实现 → 检查前端调用 → 编写数据转换协议 → 逐接口验证 → 修复问题

## 详细步骤

### 步骤1：分析接口文档
分析API接口设计文档，从文档中提取每个接口的以下信息：
- 请求方法、请求路径
- 请求参数（路径参数、查询参数、请求体）
- 响应格式（成功响应结构、错误响应结构）
- 状态码说明

## 技巧（Tips）

# API接口联调技巧

## 1. 使用转换函数隔离前后端格式差异

**适用场景**：后端返回的数据格式与前端的期望格式不一致时。

**具体做法**：编写独立的转换函数，集中管理所有数据格式转换。

**对比说明**：

| 维度 | 散落在各处的转换 | 集中管理的转换函数 |
|------|----------------|------------------|
| 可维护性 | 修改格式需搜索所有代码 | 只改转换函数 |
| 可测试性 | 难以单独测试 | 可单独测试转换函数 |
| 可读性 | 业务逻辑中混入转换代码 | 业务逻辑清晰 |

**示例**：
```javascript
// 集中转换处理
const apiTransforms = {
  // 用户列表转换
  userList: (data) => ({
    userId: data.user_id,
    userName: data.user_name,
    createdAt: data.created_at?.split('T')[0],
    statusText: { 1: '启用', 2: '禁用' }[data.status] || '未知'
  }),
  
  // 创建用户请求转换
  createUser: (data) => ({
    user_name: data.userName,
    email: data.email
  })
};
```

**注意事项**：转换函数应该放在独立的 `api/transforms.js` 文件中，不要混在组件代码中。

---

## 2. 使用浏览器开发者工具调试接口

**适用场景**：需要排查接口请求/响应的具体数据时。

**具体做法**：使用浏览器开发者工具的Network面板查看请求详情。

**检查清单**：
- [ ] 请求URL是否正确
- [ ] 请求方法是否正确（GET/POST/PUT/DELETE）
- [ ] 请求头是否正确（Content-Type、Authorization）
- [ ] 请求体格式是否正确（JSON/FormData）
- [ ] 响应状态码是否符合预期
- [ ] 响应体结构是否与接口文档一致

**注意事项**：Network面板可以过滤请求类型（XHR/Fetch），方便只查看API请求。

---

## 3. 使用mock数据先行联调

**适用场景**：后端接口尚未完成，但前端需要先开发时。

**具体做法**：在前端代码中使用mock数据模拟后端响应。

**对比说明**：

| 维度 | 等待后端完成 | 使用mock数据 |
|------|------------|-------------|
| 开发效率 | 前端等待后端 | 前后端并行开发 |
| 联调风险 | 联调时才发现问题 | 提前发现问题 |
| 代码切换 | 无 | 添加环境判断 |

**示例**：
```javascript
// api/index.js
const USE_MOCK = process.env.NODE_ENV === 'development';

export async function getUsers(params) {
  if (USE_MOCK) {
    return mockData.users;  // 返回mock数据
  }
  const response = await fetch('/api/users?' + new URLSearchParams(params));
  return response.json();
}
```

**注意事项**：mock数据应该尽量接近真实数据结构，包括边界情况（空数据、错误等）。

---

## 4. 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 接口返回404 | 路由路径错误 | 检查请求URL与后端路由是否一致 |
| 接口返回500 | 服务器异常 | 查看后端日志，检查参数和业务逻辑 |
| 跨域请求被拦截 | 未配置CORS | 后端配置 `cors` 中间件 |
| 请求体为空 | Content-Type不匹配 | 检查请求头的 `Content-Type` |
| 响应字段为undefined | 字段名不匹配 | 检查snake_case和camelCase的转换 |
| 中文乱码 | 编码问题 | 确保请求和响应都使用UTF-8 |