rxthinkcmf-wiki/RXThinkCMF_ThinkPhp6_NaiveVue/zh/api-spec/overview.md

# 8.7 API 接口总览

:::tip 概述
本节按模块分组列出所有 API 接口的概述，详细路由清单见[附录 E](/zh/appendix/api-cheatsheet.html)。
:::

## API 设计规范

### 命名规范

| 规范 | 说明 | 示例 |
|------|------|------|
| URL 风格 | RESTful，小写下划线 | `/api/user/page` |
| 模块名 | 与 Controller 对应 | `user`、`article`、`dict` |
| 操作名 | 标准 CRUD 动词 | `page`、`list`、`detail`、`add`、`update`、`delete`、`batchDelete` |
| 扩展操作 | 业务动词 | `import`、`export`、`resetPwd`、`refreshCache` |

### HTTP 方法规范

| 操作 | HTTP 方法 | URL 示例 | 说明 |
|------|----------|---------|------|
| 分页查询 | GET | `/api/user/page` | 参数在 URL query string |
| 全量列表 | GET | `/api/user/list` | 参数在 URL query string |
| 详情 | GET | `/api/user/detail/{id}` | ID 在 URL 路径 |
| 新增 | POST | `/api/user/add` | 参数在 JSON 请求体 |
| 修改 | PUT | `/api/user/update` | 参数在 JSON 请求体（含 id） |
| 删除 | DELETE | `/api/user/delete/{id}` | ID 在 URL 路径 |
| 批量删除 | DELETE | `/api/user/batchDelete` | ids 在 JSON 请求体 |

### 统一响应格式

```json
{
    "code": 0,       // 0=成功，其他=失败
    "ok": true,      // 是否成功
    "msg": "操作成功", // 提示信息
    "data": {}       // 响应数据
}
```

### 认证方式

```text
Authorization: Bearer <access_token>
```

## 公开接口（无需认证）

| 模块 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 登录 | `/api/login` | POST | 用户登录，返回双令牌 |
| 登出 | `/api/logout` | GET | 用户登出（记录日志） |
| 验证码 | `/api/captcha` | GET | 获取图片验证码 |
| Token | `/api/oauth2/token` | POST | 获取/刷新 Token |
| Token | `/api/oauth2/check/token` | GET | 检查 Token 有效性 |
| Token | `/api/oauth2/remove/{token}` | DELETE | 吊销 Token |

## 系统管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 首页 | `/api/index/getUserInfo` | GET | 获取当前用户信息 |
| 首页 | `/api/index/getMenus` | GET | 获取菜单树（动态路由） |
| 首页 | `/api/index/updatePwd` | PUT | 修改密码 |
| 用户 | `/api/user/page` | GET | 用户分页列表 |
| 用户 | `/api/user/detail/{id}` | GET | 用户详情 |
| 用户 | `/api/user/add` | POST | 新增用户 |
| 用户 | `/api/user/update` | PUT | 修改用户 |
| 用户 | `/api/user/delete/{id}` | DELETE | 删除用户 |
| 用户 | `/api/user/batchDelete` | DELETE | 批量删除用户 |
| 用户 | `/api/user/resetPwd` | POST | 重置密码 |
| 用户 | `/api/user/import` | POST | Excel 导入用户 |
| 用户 | `/api/user/export` | GET | Excel 导出用户 |
| 角色 | `/api/role/page` | GET | 角色分页列表 |
| 角色 | `/api/role/add` | POST | 新增角色（含菜单权限） |
| 角色 | `/api/role/update` | PUT | 修改角色（含菜单权限） |
| 角色 | `/api/role/delete/{id}` | DELETE | 删除角色 |
| 角色 | `/api/role/menus/{id}` | GET | 获取角色的菜单 ID 列表 |
| 菜单 | `/api/menu/treeList` | GET | 菜单树形列表 |
| 菜单 | `/api/menu/add` | POST | 新增菜单 |
| 菜单 | `/api/menu/update` | PUT | 修改菜单 |
| 菜单 | `/api/menu/delete/{id}` | DELETE | 删除菜单 |
| 部门 | `/api/dept/treeList` | GET | 部门树形列表 |
| 部门 | `/api/dept/add` | POST | 新增部门 |
| 部门 | `/api/dept/update` | PUT | 修改部门 |
| 部门 | `/api/dept/delete/{id}` | DELETE | 删除部门 |
| 岗位 | `/api/position/page` | GET | 岗位分页列表 |
| 岗位 | `/api/position/add` | POST | 新增岗位 |
| 岗位 | `/api/position/update` | PUT | 修改岗位 |
| 岗位 | `/api/position/delete/{id}` | DELETE | 删除岗位 |
| 职级 | `/api/level/page` | GET | 职级分页列表 |
| 职级 | `/api/level/add` | POST | 新增职级 |
| 职级 | `/api/level/update` | PUT | 修改职级 |
| 职级 | `/api/level/delete/{id}` | DELETE | 删除职级 |
| 职级 | `/api/level/import` | POST | Excel 导入职级 |
| 职级 | `/api/level/export` | GET | Excel 导出职级 |
| 租户 | `/api/tenant/page` | GET | 租户分页列表 |
| 租户 | `/api/tenant/detail/{id}` | GET | 租户详情 |
| 租户 | `/api/tenant/add` | POST | 新增租户 |
| 租户 | `/api/tenant/update` | PUT | 修改租户 |
| 租户 | `/api/tenant/delete/{id}` | DELETE | 删除租户 |
| 租户 | `/api/tenant/account` | POST | 创建租户管理员账号 |
| 租户 | `/api/tenant/users/{tenantId}` | GET | 获取租户用户列表 |

## 数据管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 字典 | `/api/dict/page` | GET | 字典分页列表 |
| 字典 | `/api/dict/add` | POST | 新增字典 |
| 字典 | `/api/dict/update` | PUT | 修改字典 |
| 字典 | `/api/dict/delete/{id}` | DELETE | 删除字典 |
| 字典 | `/api/dict/refreshCache` | GET | 刷新字典缓存 |
| 字典项 | `/api/dict/item/page` | GET | 字典项分页列表 |
| 字典项 | `/api/dict/item/add` | POST | 新增字典项 |
| 字典项 | `/api/dict/item/update` | PUT | 修改字典项 |
| 字典项 | `/api/dict/item/delete/{id}` | DELETE | 删除字典项 |
| 字典项 | `/api/dict/item/getDictItemList/{code}` | GET | 按编码获取字典项列表 |
| 配置 | `/api/config/page` | GET | 配置分页列表 |
| 配置 | `/api/config/add` | POST | 新增配置组 |
| 配置 | `/api/config/update` | PUT | 修改配置组 |
| 配置 | `/api/config/delete/{id}` | DELETE | 删除配置组 |
| 配置项 | `/api/config/item/page` | GET | 配置项分页列表 |
| 配置项 | `/api/config/item/add` | POST | 新增配置项 |
| 配置项 | `/api/config/item/update` | PUT | 修改配置项 |
| 配置项 | `/api/config/item/delete/{id}` | DELETE | 删除配置项 |
| 参数 | `/api/param/page` | GET | 参数分页列表 |
| 参数 | `/api/param/add` | POST | 新增参数 |
| 参数 | `/api/param/update` | PUT | 修改参数 |
| 参数 | `/api/param/delete/{id}` | DELETE | 删除参数 |
| 公告 | `/api/notice/page` | GET | 公告分页列表 |
| 公告 | `/api/notice/add` | POST | 新增公告 |
| 公告 | `/api/notice/update` | PUT | 修改公告 |
| 公告 | `/api/notice/delete/{id}` | DELETE | 删除公告 |
| 城市 | `/api/city/list` | GET | 城市列表 |
| 城市 | `/api/city/add` | POST | 新增城市 |
| 城市 | `/api/city/update` | PUT | 修改城市 |
| 城市 | `/api/city/delete/{id}` | DELETE | 删除城市 |
| 城市 | `/api/city/getCityList/{parentCode}` | GET | 按父编码查询下级城市 |
| 城市 | `/api/city/getParent` | GET | 获取省份列表 |

## 内容管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 文章 | `/api/article/page` | GET | 文章分页列表 |
| 文章 | `/api/article/detail/{id}` | GET | 文章详情 |
| 文章 | `/api/article/add` | POST | 新增文章 |
| 文章 | `/api/article/update` | PUT | 修改文章 |
| 文章 | `/api/article/delete/{id}` | DELETE | 删除文章 |
| 文章 | `/api/article/batchDelete` | DELETE | 批量删除文章 |
| 分类 | `/api/category/treeList` | GET | 分类树形列表 |
| 分类 | `/api/category/add` | POST | 新增分类 |
| 分类 | `/api/category/update` | PUT | 修改分类 |
| 分类 | `/api/category/delete/{id}` | DELETE | 删除分类 |
| 链接 | `/api/link/page` | GET | 链接分页列表 |
| 链接 | `/api/link/add` | POST | 新增链接 |
| 链接 | `/api/link/update` | PUT | 修改链接 |
| 链接 | `/api/link/delete/{id}` | DELETE | 删除链接 |

## 监控管理

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 定时任务 | `/api/job/page` | GET | 任务分页列表 |
| 定时任务 | `/api/job/add` | POST | 新增任务 |
| 定时任务 | `/api/job/update` | PUT | 修改任务 |
| 定时任务 | `/api/job/delete/{id}` | DELETE | 删除任务 |
| 定时任务 | `/api/job/run/{id}` | POST | 手动执行任务 |
| 定时任务 | `/api/job/pause/{id}` | POST | 暂停任务 |
| 定时任务 | `/api/job/resume/{id}` | POST | 恢复任务 |
| 任务日志 | `/api/job/log/page` | GET | 任务日志分页列表 |
| 任务日志 | `/api/job/log/delete/{id}` | DELETE | 删除日志 |
| 任务日志 | `/api/job/log/batchDelete` | DELETE | 批量删除日志 |

## 日志审计

| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 操作日志 | `/api/oper/log/page` | GET | 操作日志分页列表 |
| 操作日志 | `/api/oper/log/detail/{id}` | GET | 日志详情 |
| 操作日志 | `/api/oper/log/delete/{id}` | DELETE | 删除日志 |
| 操作日志 | `/api/oper/log/batchDelete` | DELETE | 批量删除日志 |
| 登录日志 | `/api/login/log/page` | GET | 登录日志分页列表 |
| 登录日志 | `/api/login/log/detail/{id}` | GET | 日志详情 |
| 登录日志 | `/api/login/log/delete/{id}` | DELETE | 删除日志 |
| 登录日志 | `/api/login/log/batchDelete` | DELETE | 批量删除日志 |

## 公共接口

| 模块 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 文件上传 | `/api/upload/uploadFile` | POST | 上传文件（type=file/image） |
| 代码生成 | `/api/generator/page` | GET | 可生成的表列表 |
| 代码生成 | `/api/generator/preview` | POST | 预览生成代码 |
| 代码生成 | `/api/generator/generate` | POST | 执行代码生成 |

## 接口统计

| 模块 | 接口数量 | 说明 |
|------|---------|------|
| 公开接口 | 6 | 登录/登出/验证码/Token |
| 系统管理 | ~35 | 用户/角色/菜单/部门/岗位/职级/租户 |
| 数据管理 | ~25 | 字典/字典项/配置/配置项/参数/公告/城市 |
| 内容管理 | ~12 | 文章/分类/链接 |
| 监控管理 | ~10 | 定时任务/任务日志 |
| 日志审计 | ~8 | 操作日志/登录日志 |
| 公共接口 | ~4 | 文件上传/代码生成 |
| **合计** | **~100** | |

详细路由清单（HTTP 方法 + 路径 + 权限码）见[附录 E](/zh/appendix/api-cheatsheet.html)。