# 🔌 REST API 生成

> 根据需求生成 RESTful API 接口定义和文档的 Prompt 工程实践

---

## 📌 应用场景

根据业务需求生成完整的 REST API 接口定义，用于：
- API 接口设计和规范
- OpenAPI/Swagger 文档生成
- 前后端接口约定
- API 文档自动生成
- 接口测试用例生成

---

## 🎯 核心要素

| 要素 | 说明 | 例子 |
|------|------|------|
| **角色** | API 架构设计师 | 后端工程师、API 设计专家 |
| **背景** | 业务需求和数据模型 | 用户管理、订单系统等 |
| **目标** | 生成标准的 API 接口 | RESTful 规范的端点定义 |
| **约束** | 命名规范、版本管理 | RESTful 最佳实践 |
| **示例** | 请求/响应示例 | JSON 格式示例 |

---

## ✅ 完整 Prompt 模板

### 基础版（简单 API）

```
你是一位资深的 API 架构设计师，擅长设计规范的 RESTful API。

请根据以下需求，设计一个 REST API 接口。

【业务需求】
{需求描述}

【数据模型】
{主要数据结构}

【设计要求】
1. 遵循 RESTful 设计规范
2. 使用标准的 HTTP 方法和状态码
3. 请求和响应使用 JSON 格式
4. 包含错误处理和验证

【输出格式 - API 接口定义】

### {接口名称}

**请求**
- 方法：{GET/POST/PUT/DELETE}
- 路径：{/api/v1/...}
- 认证：{有/无}

**请求参数**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| {参数} | {类型} | {是/否} | {说明} |

**请求示例**
{curl 或 JSON 示例}

**响应**
- 状态码：{200/201/400/404等}
- 响应格式：JSON

**响应示例**
{JSON 响应示例}

**错误处理**
- {错误场景1}：{状态码} - {错误消息}
- {错误场景2}：{状态码} - {错误消息}
```

### 进阶版（完整 API 设计文档）

```
你是一位资深的 API 架构设计师，拥有丰富的大规模系统 API 设计经验。

请根据以下需求，设计一套完整的 REST API，包括接口、数据模型、错误处理等。

【项目背景】
- 项目名称：{项目名}
- API 版本：{版本号}
- 基础 URL：{https://api.example.com/v1}

【业务需求**】
{详细的业务需求描述}

【核心业务流程】
{主要的用户操作和系统交互流程}

【数据模型】
请列出主要的数据结构及字段定义

【设计原则】
1. RESTful API 设计规范
2. 版本管理：URL 路径版本（/v1, /v2）
3. 错误响应格式统一
4. 分页、排序、过滤标准化
5. 认证与授权

【API 接口设计】

为以下操作设计接口：
- {操作1}（如：创建用户）
- {操作2}（如：获取用户列表）
- {操作3}（如：更新用户信息）
- {操作4}（如：删除用户）
- {其他操作}

对于每个操作，提供：

**1. 接口基本信息**
- 端点：{HTTP 方法} {路径}
- 描述：{接口功能描述}
- 认证：{认证方式}
- 权限：{需要的权限}

**2. 请求定义**
- 参数位置：Path / Query / Body
- 参数列表（表格格式）：参数名 | 类型 | 必填 | 说明 | 范围/规则
- 请求示例（cURL 或 JSON）

**3. 响应定义**
- 成功状态码：{状态码}
- 响应字段（表格格式）：字段名 | 类型 | 说明
- 响应示例（JSON）

**4. 错误处理**
- 可能的错误状态码和错误消息
- 错误响应格式：
  {
    "error": {
      "code": "{错误代码}",
      "message": "{错误消息}",
      "details": "{详细信息}"
    }
  }

**5. 其他考虑**
- 分页（如果列表接口）：支持 limit, offset 或 page, size
- 排序（如果列表接口）：支持 sort_by, order 参数
- 过滤（如果列表接口）：支持的过滤字段
- 限流：请求频率限制（如：100 requests/minute）

【通用标准】

**请求头**
- Content-Type: application/json
- Authorization: Bearer {token}（如果需要认证）

**成功响应格式**
{
  "code": 0,
  "message": "success",
  "data": {...}
}

**分页响应格式**
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [...],
    "total": 100,
    "page": 1,
    "size": 20
  }
}

**错误响应格式**
{
  "code": {错误代码},
  "message": "{错误消息}",
  "details": "{详细信息}"
}

【状态码规范】
- 200 OK：请求成功
- 201 Created：资源创建成功
- 204 No Content：请求成功但无返回内容
- 400 Bad Request：请求参数错误
- 401 Unauthorized：未授权
- 403 Forbidden：禁止访问
- 404 Not Found：资源不存在
- 409 Conflict：冲突（如：重复创建）
- 429 Too Many Requests：限流
- 500 Internal Server Error：服务器错误
- 503 Service Unavailable：服务不可用

【输出格式**】

## API 设计总览

| 接口 | 方法 | 路径 | 描述 |
|------|------|------|------|
| {名称} | {GET/POST/PUT/DELETE} | {路径} | {描述} |
...

---

## 接口详情

### 1. {接口名称}
{完整的接口定义...}

### 2. {接口名称}
{完整的接口定义...}

...

---

## 数据模型

{数据结构定义}

---

## 错误处理

{错误代码和消息定义}

---

## 示例流程

{完整的业务流程示例，包括多个接口调用}
```

---

## 💡 真实示例

### 示例1：用户管理 API

**输入需求：**
```
设计一个简单的用户管理 API，支持：
- 创建用户
- 获取用户列表（分页）
- 获取单个用户
- 更新用户信息
- 删除用户
```

**部分期望输出：**
```
### 创建用户

**请求**
- 方法：POST
- 路径：/api/v1/users

**请求参数（Body）**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名，3-20个字符 |
| email | string | 是 | 邮箱，需要验证格式 |
| password | string | 是 | 密码，至少8个字符 |
| full_name | string | 否 | 全名 |

**请求示例**
```json
{
  "username": "john_doe",
  "email": "john@example.com",
  "password": "securepassword123",
  "full_name": "John Doe"
}
```

**响应**
- 状态码：201 Created

**响应示例**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "user_12345",
    "username": "john_doe",
    "email": "john@example.com",
    "full_name": "John Doe",
    "created_at": "2024-03-02T10:30:00Z"
  }
}
```

**错误处理**
- 400 Bad Request：参数验证失败
- 409 Conflict：用户名或邮箱已存在

---

### 获取用户列表

**请求**
- 方法：GET
- 路径：/api/v1/users?page=1&size=20&sort_by=created_at&order=desc

**请求参数（Query）**
| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | integer | 否 | 页码，默认1 |
| size | integer | 否 | 每页数量，默认20 |
| sort_by | string | 否 | 排序字段（created_at/username） |
| order | string | 否 | 排序顺序（asc/desc） |
| search | string | 否 | 搜索关键词（用户名或邮箱） |

**响应示例**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "items": [
      {
        "id": "user_12345",
        "username": "john_doe",
        "email": "john@example.com",
        "created_at": "2024-03-02T10:30:00Z"
      },
      ...
    ],
    "total": 100,
    "page": 1,
    "size": 20
  }
}
```
```

---

## 🔧 优化建议

### ✅ 做的事情

1. **遵循 RESTful 原则**
   ```
   ✅ 很好：
   - GET /users（获取列表）
   - POST /users（创建）
   - GET /users/{id}（获取详情）
   - PUT /users/{id}（更新）
   - DELETE /users/{id}（删除）

   ❌ 不好：
   - GET /getUsers
   - POST /createUser
   - GET /updateUser?id=1
   ```

2. **清晰的错误处理**
   ```
   ✅ 很好：明确的状态码 + 错误消息 + 错误代码
   ❌ 不好：所有错误都返回 200，只在 message 中说错误
   ```

3. **完整的参数文档**
   ```
   ✅ 很好：参数类型、必填性、范围、格式要求
   ❌ 不好：模糊的参数说明
   ```

4. **包含实际示例**
   ```
   ✅ 很好：实际的 cURL 命令和 JSON 示例
   ❌ 不好：只有理论描述
   ```

### ❌ 避免的事情

1. **不一致的命名** - 字段名、路径名应该遵循统一的规范
2. **缺少错误定义** - 不清楚哪些错误是可能的
3. **过度 API 化** - 不必要的接口会增加维护成本
4. **忽视性能** - 没有考虑分页、限流等问题

---

## 📊 API 版本管理对比

| 方案 | 优点 | 缺点 | 适用场景 |
|-----|------|------|---------|
| **URL 路径** | 明确、易于理解 | 需要维护多版本 | 大多数情况 |
| **Query 参数** | 灵活 | 容易混淆 | 小型迭代 |
| **Header** | 向后兼容 | 客户端容易忽略 | 内部 API |
| **Accept Header** | 标准方式 | 实现复杂 | 学术场景 |

---

## 🚀 快速上手

1. **明确业务需求** - 需要哪些操作？
2. **定义数据模型** - 主要数据结构是什么？
3. **设计接口** - 为每个操作设计一个 REST 端点
4. **编写文档** - 使用上面的模板完整描述
5. **生成代码** - 基于 API 文档生成服务端和客户端代码

---

## 💡 进阶应用

### 应用1：OpenAPI/Swagger 生成
```
Prompt 修改：
- 直接生成 OpenAPI 3.0 或 Swagger 2.0 格式
- 可用于自动生成交互式文档（Swagger UI）
```

### 应用2：SDK 生成
```
Prompt 修改：
- 基于 API 设计生成 Python/JavaScript/Java SDK
- 包含类型定义和错误处理
```

### 应用3：测试用例生成
```
Prompt 修改：
- 为每个接口生成完整的测试用例
- 包括成功、错误、边界条件测试
```

---

**💡 提示**: 好的 API 设计是系统成功的基础。花时间设计清晰、一致的 API，会大大降低开发和维护的成本。