# API设计

## 规则（Rules）

# API接口设计规范

## 适用对象和范围

本规范适用于所有设计RESTful API接口的场景，包括路由规划、参数定义、返回格式和错误处理。

---

## 1. 路由命名规范

**规则**：路由路径必须使用名词复数形式，禁止使用动词。

- ✅ 正确：`GET /api/users`、`POST /api/users`、`GET /api/users/{id}`
- ❌ 错误：`GET /api/getUser`、`POST /api/createUser`、`GET /api/user`（单数）

**违反后果**：动词式路由不符合RESTful规范，接口风格不统一，增加前端对接复杂度。

---

## 2. HTTP方法规范

**规则**：必须按照标准RESTful语义使用HTTP方法。

| 方法 | 用途 | 示例 |
|------|------|------|
| GET | 查询列表/详情 | `GET /api/users`、`GET /api/users/{id}` |
| POST | 创建资源 | `POST /api/users` |
| PUT | 全量更新 | `PUT /api/users/{id}` |
| PATCH | 部分更新 | `PATCH /api/users/{id}` |
| DELETE | 删除资源 | `DELETE /api/users/{id}` |

- ✅ 正确：创建用户用 `POST /api/users`
- ❌ 错误：创建用户用 `GET /api/users?action=create`

**违反后果**：HTTP方法使用不当导致接口语义不清晰，缓存和代理无法正确工作。

---

## 3. 状态码规范

**规则**：必须使用标准HTTP状态码表示接口执行结果。

| 场景 | 状态码 | 说明 |
|------|--------|------|
| 查询成功 | 200 OK | 正常返回数据 |
| 创建成功 | 201 Created | 资源已创建 |
| 参数错误 | 400 Bad Request | 请求参数不合法 |
| 未授权 | 401 Unauthorized | 需要登录 |
| 无权限 | 403 Forbidden | 权限不足 |
| 资源不存在 | 404 Not Found | 请求的资源不存在 |
| 服务器错误 | 500 Internal Server Error | 服务器内部异常 |

- ✅ 正确：创建资源返回 `201 Created`
- ❌ 错误：创建资源返回 `200 OK` 但body中包含创建结果

**违反后果**：状态码使用不规范导致前端无法通过状态码判断请求结果，增加处理复杂度。

---

## 4. 响应格式规范

**规则**：所有接口必须返回统一的JSON响应格式。

**成功响应**：
```json
{
  "code": 0,
  "message": "success",
  "data": { ... }
}
```

**错误响应**：
```json
{
  "code": 40001,
  "message": "参数错误：用户名为必填项",
  "data": null
}
```

- ✅ 正确：统一 `code` + `message` + `data` 格式
- ❌ 错误：每个接口返回不同格式

**违反后果**：响应格式不统一导致前端需要为每个接口单独处理响应解析。

---

## 5. 接口安全规范

**规则**：禁止在接口中暴露敏感信息（密码、token、内部IP、数据库结构等）。

- ✅ 正确：`{"id": 1, "name": "张三", "email": "zhang@example.com"}`
- ❌ 错误：`{"id": 1, "name": "张三", "password": "123456", "token": "xxx", "internal_ip": "10.0.0.1"}`

**违反后果**：暴露敏感信息存在严重安全风险。

---

## 6. 向后兼容规范

**规则**：已有接口的路径和参数不能随意修改，如需修改必须走版本号升级。

- ✅ 正确：`/api/v1/users` → `/api/v2/users`（大版本升级）
- ❌ 错误：直接修改 `/api/users` 的参数结构

**违反后果**：随意修改已有接口导致前端调用崩溃，影响线上服务。

## 方法（Methods）

# API接口设计方法

## 前置条件

- [ ] 已获取需求文档，了解需要暴露的API接口列表
- [ ] 已识别实体资源和操作类型（增删改查）

## 流程概览

分析功能需求 → 设计RESTful路由 → 定义请求和响应格式 → 编写API文档 → 评审优化

## 详细步骤

### 步骤1：分析功能需求
分析需求文档，提取需要暴露的API接口列表，识别实体资源和操作类型（增删改查）。

### 步骤2：设计RESTful路由
对每个资源，设计标准RESTful路由。

## 技巧（Tips）

# API接口设计技巧

## 1. 合理使用查询参数过滤

**适用场景**：列表接口需要支持筛选条件时。

**具体做法**：使用查询参数（query parameters）而非路径参数做筛选。

**对比说明**：

| 维度 | 路径参数 | 查询参数 |
|------|---------|---------|
| 语义 | 标识资源 | 过滤条件 |
| 必填性 | 通常是必填 | 通常是可选 |
| 组合 | 不可组合 | 可自由组合 |

**示例**：
```javascript
// ✅ 推荐：查询参数过滤
GET /api/users?status=active&role=admin&page=1&size=20

// ❌ 不推荐：路径参数过滤
GET /api/users/status/active/role/admin
```

**注意事项**：查询参数应该使用snake_case命名，保持与后端字段一致。

---

## 2. 使用嵌套路由表示资源关联

**适用场景**：资源之间存在从属关系时。

**具体做法**：使用嵌套路由 `/parent/{parentId}/child` 表示资源层级。

**示例**：
```javascript
// 用户下的订单
GET /api/users/{userId}/orders
POST /api/users/{userId}/orders

// 订单下的商品
GET /api/orders/{orderId}/items
```

**注意事项**：嵌套层级不建议超过2层，超过时应考虑扁平化设计。

---

## 3. 批量操作使用自定义端点

**适用场景**：需要批量创建、更新或删除时。

**具体做法**：使用 `POST /api/{resources}/batch` 作为批量操作的端点。

**示例**：
```javascript
// 批量创建
POST /api/users/batch
Body: { "users": [{...}, {...}] }

// 批量删除
POST /api/users/batch-delete
Body: { "ids": [1, 2, 3] }
```

**注意事项**：批量操作应该返回每个资源的操作结果，而非整体成功/失败。

---

## 4. 常见问题速查

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| 接口返回格式不统一 | 未定义统一响应结构 | 定义 `{code, message, data}` 统一格式 |
| 路由路径冲突 | 路径设计不合理 | 使用 `/api/v{version}/` 前缀隔离版本 |
| 参数校验错误信息不清晰 | 校验逻辑过于简单 | 详细说明每个参数的取值范围和格式 |
| 接口响应时间过长 | 未做分页或数据量过大 | 列表接口必须分页，设置默认pageSize |