# 设计API

## 规则（Rules）

# 设计API接口 - 规范

## 1. RESTful路由命名规范

| 操作 | 方法 | 路径格式 |
|------|------|---------|
| 列表查询 | GET | `/api/{resources}` |
| 获取单个 | GET | `/api/{resources}/{id}` |
| 创建 | POST | `/api/{resources}` |
| 更新 | PUT | `/api/{resources}/{id}` |
| 删除 | DELETE | `/api/{resources}/{id}` |

### 命名原则
- 使用名词复数形式：`/users`、`/orders`，禁止使用动词式路由如 `/getUser`
- 嵌套资源：`/users/{userId}/orders`
- 路径全部小写，单词用下划线分隔：`/order_items`

## 2. HTTP状态码规范

| 状态码 | 含义 | 使用场景 |
|--------|------|---------|
| 200 | 成功 | GET、PUT、DELETE成功 |
| 201 | 创建成功 | POST创建资源成功 |
| 400 | 参数错误 | 请求参数校验失败 |
| 401 | 未认证 | 缺少或无效的认证信息 |
| 403 | 无权限 | 认证通过但无操作权限 |
| 404 | 未找到 | 资源不存在 |
| 409 | 冲突 | 资源已存在（如重复创建） |
| 500 | 服务器错误 | 服务器内部异常 |

## 3. 响应格式规范

统一响应格式：

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

// 错误响应
{
  "code": 40001,
  "message": "参数错误：用户名不能为空",
  "data": null
}
```

## 4. 参数规范
- 路径参数：用于定位资源，如 `/{id}`
- 查询参数：用于过滤和分页，如 `?page=1&size=20`
- 请求体参数：用于创建/更新资源，使用JSON格式
- 所有参数必须有明确的类型说明和取值范围

## 5. 向后兼容规范
- 已有接口的路径和参数不能随意修改
- 新增参数必须设为可选（非必填）
- 如需破坏性变更，必须升级API版本（如 `/api/v2/`）

## 方法（Methods）

# 设计API接口 - 方法

## 流程概览

```
分析需求 → 设计路由 → 定义格式 → 编写文档 → 评审优化
```

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

## 步骤2：设计RESTful路由
对每个资源设计标准RESTful路由，以表格列出所有路由。

## 步骤3：定义请求和响应格式
对每个API接口定义：请求参数（路径参数、查询参数、请求体）、响应格式（成功/错误）、HTTP状态码。

## 步骤4：编写API文档
包含接口概述、路由表、详细接口说明（含请求/响应示例）、错误码说明。

## 步骤5：评审优化
检查路由命名是否符合RESTful规范、参数定义是否完整、错误处理是否覆盖异常场景。

## 技巧（Tips）

# 设计API接口 - 技巧

## 1. 分页设计
统一使用 `page`（页码）和 `size`（每页条数）参数，响应中返回 `total`（总数）。

## 2. 字段选择
支持 `fields` 参数让客户端选择返回字段，减少数据传输。

## 3. 排序规范
支持 `sort` 参数，格式为 `field:asc|desc`，如 `sort=created_at:desc`。

## 4. 错误码设计
业务错误码使用5位数字：前2位代表模块，后3位代表具体错误。