# API 文档模板

> 🎯 **模板用途**：本模板用于创建标准化的 API 接口文档，为 Cursor AI 提供 API 文档编写和维护的参考格式

## 📋 文档说明

### 适用场景

-   新增 API 接口时创建文档
-   现有 API 接口修改时更新文档
-   为 Cursor AI 提供接口开发上下文

### 使用方法

1. 复制本模板内容
2. 替换所有 `[占位符]` 为实际内容
3. 根据实际接口情况调整结构
4. 确保示例代码可以正常运行

---

## 🔌 [模块名称] API 接口文档

### 模块概述

**模块名称**：[模块英文名] / [模块中文名]  
**基础路径**：`/api/[module]`  
**版本**：v1.0  
**负责人**：[开发负责人]  
**更新时间**：[最后更新时间]

### 模块功能

[模块的主要功能描述，包括业务价值和技术特点]

### 权限说明

-   **权限前缀**：`[module]:`
-   **权限列表**：
    -   `[module]:list` - 查询权限
    -   `[module]:add` - 新增权限
    -   `[module]:edit` - 编辑权限
    -   `[module]:remove` - 删除权限

---

## 📊 接口概览

### 接口分类

#### 基础 CRUD 接口

| 接口名称       | HTTP 方法 | 路径                  | 权限要求          | 功能描述               |
| -------------- | --------- | --------------------- | ----------------- | ---------------------- |
| 查询[实体]列表 | GET       | `/api/[module]/list`  | `[module]:list`   | 分页查询[实体]列表     |
| 查询[实体]详情 | GET       | `/api/[module]/{id}`  | `[module]:list`   | 根据 ID 查询[实体]详情 |
| 新增[实体]     | POST      | `/api/[module]`       | `[module]:add`    | 创建新的[实体]         |
| 修改[实体]     | PUT       | `/api/[module]`       | `[module]:edit`   | 更新[实体]信息         |
| 删除[实体]     | DELETE    | `/api/[module]/{ids}` | `[module]:remove` | 批量删除[实体]         |

#### 业务逻辑接口

| 接口名称     | HTTP 方法 | 路径                      | 权限要求 | 功能描述   |
| ------------ | --------- | ------------------------- | -------- | ---------- |
| [业务接口 1] | [方法]    | `/api/[module]/[action1]` | `[权限]` | [功能描述] |
| [业务接口 2] | [方法]    | `/api/[module]/[action2]` | `[权限]` | [功能描述] |
| [业务接口 3] | [方法]    | `/api/[module]/[action3]` | `[权限]` | [功能描述] |

### 通用响应格式

#### 成功响应

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        // 响应数据
    }
}
```

#### 分页响应

```json
{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        // 数据列表
    ],
    "total": 100
}
```

#### 错误响应

```json
{
    "code": 400001,
    "msg": "参数错误",
    "data": null
}
```

---

## 🔍 接口详细说明

### 1. 查询[实体]列表

#### 接口信息

**接口地址**: `GET /api/[module]/list`

**接口描述**: 分页查询[实体]列表，支持多条件筛选

**权限要求**: `[module]:list`

#### 请求参数

| 参数名    | 类型    | 必填 | 说明                 | 示例值       |
| --------- | ------- | ---- | -------------------- | ------------ |
| pageNum   | Integer | N    | 页码，默认 1         | 1            |
| pageSize  | Integer | N    | 每页大小，默认 10    | 10           |
| [field1]  | String  | N    | [字段 1 说明]        | "示例值"     |
| [field2]  | Integer | N    | [字段 2 说明]        | 1            |
| status    | Integer | N    | 状态：1 启用，0 禁用 | 1            |
| beginTime | String  | N    | 开始时间             | "2024-01-01" |
| endTime   | String  | N    | 结束时间             | "2024-01-31" |

#### 请求示例

```bash
curl -X GET "http://localhost:8080/api/[module]/list?pageNum=1&pageSize=10&status=1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
```

#### 响应示例

```json
{
    "code": 200,
    "msg": "查询成功",
    "rows": [
        {
            "id": 1,
            "[field1]": "示例值1",
            "[field2]": 1,
            "status": 1,
            "createBy": 1,
            "createTime": "2024-01-01 10:00:00",
            "updateBy": 1,
            "updateTime": "2024-01-01 10:00:00"
        },
        {
            "id": 2,
            "[field1]": "示例值2",
            "[field2]": 2,
            "status": 1,
            "createBy": 1,
            "createTime": "2024-01-01 11:00:00",
            "updateBy": 1,
            "updateTime": "2024-01-01 11:00:00"
        }
    ],
    "total": 100
}
```

#### 错误码

| 错误码 | 说明     | 解决方案             |
| ------ | -------- | -------------------- |
| 401001 | 未登录   | 请先登录获取 token   |
| 403001 | 无权限   | 请联系管理员分配权限 |
| 400001 | 参数错误 | 检查请求参数格式     |

---

### 2. 查询[实体]详情

#### 接口信息

**接口地址**: `GET /api/[module]/{id}`

**接口描述**: 根据 ID 查询[实体]的详细信息

**权限要求**: `[module]:list`

#### 路径参数

| 参数名 | 类型 | 必填 | 说明     | 示例值 |
| ------ | ---- | ---- | -------- | ------ |
| id     | Long | Y    | [实体]ID | 1      |

#### 请求示例

```bash
curl -X GET "http://localhost:8080/api/[module]/1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
```

#### 响应示例

```json
{
    "code": 200,
    "msg": "查询成功",
    "data": {
        "id": 1,
        "[field1]": "示例值",
        "[field2]": 1,
        "status": 1,
        "remark": "备注信息",
        "createBy": 1,
        "createTime": "2024-01-01 10:00:00",
        "updateBy": 1,
        "updateTime": "2024-01-01 10:00:00"
    }
}
```

#### 错误码

| 错误码 | 说明       | 解决方案             |
| ------ | ---------- | -------------------- |
| 404001 | 数据不存在 | 检查 ID 是否正确     |
| 401001 | 未登录     | 请先登录获取 token   |
| 403001 | 无权限     | 请联系管理员分配权限 |

---

### 3. 新增[实体]

#### 接口信息

**接口地址**: `POST /api/[module]`

**接口描述**: 创建新的[实体]记录

**权限要求**: `[module]:add`

#### 请求参数

| 参数名   | 类型    | 必填 | 说明                         | 示例值     |
| -------- | ------- | ---- | ---------------------------- | ---------- |
| [field1] | String  | Y    | [字段 1 说明]                | "示例值"   |
| [field2] | Integer | Y    | [字段 2 说明]                | 1          |
| status   | Integer | N    | 状态：1 启用，0 禁用，默认 1 | 1          |
| remark   | String  | N    | 备注信息                     | "备注内容" |

#### 请求体

```json
{
    "[field1]": "示例值",
    "[field2]": 1,
    "status": 1,
    "remark": "备注信息"
}
```

#### 请求示例

```bash
curl -X POST "http://localhost:8080/api/[module]" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "[field1]": "示例值",
    "[field2]": 1,
    "status": 1,
    "remark": "备注信息"
  }'
```

#### 响应示例

```json
{
    "code": 200,
    "msg": "新增成功",
    "data": {
        "id": 3
    }
}
```

#### 错误码

| 错误码 | 说明       | 解决方案             |
| ------ | ---------- | -------------------- |
| 400001 | 参数错误   | 检查必填参数是否缺失 |
| 400002 | 数据已存在 | 检查唯一字段是否重复 |
| 401001 | 未登录     | 请先登录获取 token   |
| 403001 | 无权限     | 请联系管理员分配权限 |

#### 参数验证规则

-   `[field1]`: 长度 2-50 字符，不能为空
-   `[field2]`: 必须为正整数
-   `status`: 只能为 0 或 1
-   `remark`: 最大长度 500 字符

---

### 4. 修改[实体]

#### 接口信息

**接口地址**: `PUT /api/[module]`

**接口描述**: 更新[实体]信息

**权限要求**: `[module]:edit`

#### 请求参数

| 参数名   | 类型    | 必填 | 说明                 | 示例值     |
| -------- | ------- | ---- | -------------------- | ---------- |
| id       | Long    | Y    | [实体]ID             | 1          |
| [field1] | String  | Y    | [字段 1 说明]        | "示例值"   |
| [field2] | Integer | Y    | [字段 2 说明]        | 1          |
| status   | Integer | N    | 状态：1 启用，0 禁用 | 1          |
| remark   | String  | N    | 备注信息             | "备注内容" |

#### 请求体

```json
{
    "id": 1,
    "[field1]": "修改后的值",
    "[field2]": 2,
    "status": 1,
    "remark": "修改后的备注"
}
```

#### 请求示例

```bash
curl -X PUT "http://localhost:8080/api/[module]" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "[field1]": "修改后的值",
    "[field2]": 2,
    "status": 1,
    "remark": "修改后的备注"
  }'
```

#### 响应示例

```json
{
    "code": 200,
    "msg": "修改成功",
    "data": null
}
```

#### 错误码

| 错误码 | 说明       | 解决方案             |
| ------ | ---------- | -------------------- |
| 404001 | 数据不存在 | 检查 ID 是否正确     |
| 400001 | 参数错误   | 检查参数格式是否正确 |
| 401001 | 未登录     | 请先登录获取 token   |
| 403001 | 无权限     | 请联系管理员分配权限 |

---

### 5. 删除[实体]

#### 接口信息

**接口地址**: `DELETE /api/[module]/{ids}`

**接口描述**: 批量删除[实体]，支持逻辑删除

**权限要求**: `[module]:remove`

#### 路径参数

| 参数名 | 类型   | 必填 | 说明                          | 示例值  |
| ------ | ------ | ---- | ----------------------------- | ------- |
| ids    | String | Y    | [实体]ID 列表，多个用逗号分隔 | "1,2,3" |

#### 请求示例

```bash
curl -X DELETE "http://localhost:8080/api/[module]/1,2,3" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json"
```

#### 响应示例

```json
{
    "code": 200,
    "msg": "删除成功",
    "data": {
        "successCount": 2,
        "failCount": 1,
        "failIds": [3]
    }
}
```

#### 错误码

| 错误码 | 说明       | 解决方案             |
| ------ | ---------- | -------------------- |
| 400001 | 参数错误   | 检查 ID 格式是否正确 |
| 400003 | 数据被引用 | 请先删除关联数据     |
| 401001 | 未登录     | 请先登录获取 token   |
| 403001 | 无权限     | 请联系管理员分配权限 |

---

## 🎯 业务逻辑接口

### 1. [业务接口 1 名称]

#### 接口信息

**接口地址**: `[HTTP方法] /api/[module]/[action]`

**接口描述**: [详细的业务功能描述]

**权限要求**: `[权限代码]`

#### 业务流程

1. [业务步骤 1]
2. [业务步骤 2]
3. [业务步骤 3]

#### 请求参数

| 参数名   | 类型   | 必填  | 说明       | 示例值   |
| -------- | ------ | ----- | ---------- | -------- |
| [param1] | [类型] | [Y/N] | [参数说明] | [示例值] |
| [param2] | [类型] | [Y/N] | [参数说明] | [示例值] |

#### 请求示例

```bash
curl -X [方法] "http://localhost:8080/api/[module]/[action]" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "[param1]": "[值1]",
    "[param2]": "[值2]"
  }'
```

#### 响应示例

```json
{
    "code": 200,
    "msg": "操作成功",
    "data": {
        "[result1]": "[结果值1]",
        "[result2]": "[结果值2]"
    }
}
```

#### 业务规则

-   [业务规则 1]
-   [业务规则 2]
-   [业务规则 3]

#### 注意事项

-   [注意事项 1]
-   [注意事项 2]

---

## 📋 数据字典

### [实体名称] 状态枚举

| 值  | 名称 | 说明     |
| --- | ---- | -------- |
| 0   | 禁用 | 不可使用 |
| 1   | 启用 | 正常使用 |

### [其他枚举名称]

| 值     | 名称     | 说明     |
| ------ | -------- | -------- |
| [值 1] | [名称 1] | [说明 1] |
| [值 2] | [名称 2] | [说明 2] |

---

## 🔧 SDK 使用示例

### Java SDK

```java
// 查询列表
[Module]QueryBo queryBo = new [Module]QueryBo();
queryBo.setStatus(1);
PageQuery pageQuery = new PageQuery(1, 10);
Result<PageResult<[Module]Vo>> result = [module]Api.list(queryBo, pageQuery);

// 新增记录
[Module]Bo [module]Bo = new [Module]Bo();
[module]Bo.set[Field1]("示例值");
[module]Bo.set[Field2](1);
Result<Long> addResult = [module]Api.add([module]Bo);

// 修改记录
[module]Bo.setId(1L);
[module]Bo.set[Field1]("修改后的值");
Result<Void> updateResult = [module]Api.update([module]Bo);
```

### JavaScript SDK

```javascript
// 查询列表
const queryParams = {
  pageNum: 1,
  pageSize: 10,
  status: 1
};
const listResult = await [module]Api.list(queryParams);

// 新增记录
const [module]Data = {
  [field1]: "示例值",
  [field2]: 1,
  status: 1
};
const addResult = await [module]Api.add([module]Data);

// 修改记录
[module]Data.id = 1;
[module]Data.[field1] = "修改后的值";
const updateResult = await [module]Api.update([module]Data);
```

---

## 🧪 测试用例

### 接口测试

```javascript
// Jest 测试示例
describe('[Module] API Tests', () => {
  test('查询列表接口', async () => {
    const response = await request(app)
      .get('/api/[module]/list')
      .set('Authorization', `Bearer ${token}`)
      .expect(200);

    expect(response.body.code).toBe(200);
    expect(response.body.rows).toBeDefined();
    expect(response.body.total).toBeGreaterThanOrEqual(0);
  });

  test('新增接口', async () => {
    const [module]Data = {
      [field1]: "测试值",
      [field2]: 1
    };

    const response = await request(app)
      .post('/api/[module]')
      .set('Authorization', `Bearer ${token}`)
      .send([module]Data)
      .expect(200);

    expect(response.body.code).toBe(200);
    expect(response.body.data.id).toBeDefined();
  });
});
```

---

## 🔄 版本历史

### v1.0.0 - 2024-01-01

-   ✅ 初始版本发布
-   ✅ 完成基础 CRUD 接口
-   ✅ 完成核心业务接口

### v1.0.1 - 2024-01-15

-   🔧 优化查询接口性能
-   🐛 修复删除接口的权限检查问题
-   📚 补充接口文档和示例

### v1.1.0 - 2024-02-01

-   ✨ 新增[新功能 1]接口
-   ✨ 新增[新功能 2]接口
-   🔧 优化错误处理机制

---

## 📖 相关文档

-   **数据库设计**：[数据库设计文档](../设计文档/database/)
-   **业务需求**：[业务需求文档](../需求文档/)
-   **技术架构**：[技术架构文档](./技术架构/)
-   **开发规范**：[开发规范文档](./开发规范/)

---

## 📞 联系方式

**开发团队**：[团队名称]  
**负责人**：[负责人姓名]  
**邮箱**：[联系邮箱]  
**文档维护**：实时更新，如有问题请及时反馈

---

**📌 重要提醒**：

1. 所有接口都需要先登录获取 token
2. 请求头必须包含 `Authorization: Bearer {token}`
3. 参数验证失败会返回详细的错误信息
4. 生产环境请使用 HTTPS 协议