rxthinkcmf/rxthinkcmf-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
08eae7b646bb687784563223d162b8b72a445dac
rxthinkcmf-wiki/RXThinkCMF_Laravel13_NaiveVue/zh/api-spec/overview.md
T
gitadmin e213a9b31d 签入版本
2026-10-08 17:50:29 +08:00

237 lines
12 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 8.7 API 接口总览
:::tip 概述
本节按模块分组列出所有 API 接口的概述（全部来自 `routes/api.php` 实际路由），详细路由清单见 [附录 E API 接口速查表](/zh/appendix/api-cheatsheet.html)。
:::
## API 设计规范
### 命名规范
| 规范 | 说明 | 示例 |
|------|------|------|
| URL 风格 | 小驼峰/小写下划线混合，前缀 `/api`（`bootstrap/app.php` 统一添加） | `/api/user/page` |
| 模块名 | 与 Controller 对应 | `user`、`article`、`dict` |
| 操作名 | 标准 CRUD 动词 | `page`、`list`、`detail`、`add`、`update`、`delete`、`batchDelete` |
| 扩展操作 | 业务动词 | `import`、`export`、`resetPwd`、`refreshCache`、`runOnce` |
### HTTP 方法规范
| 操作 | HTTP 方法 | URL 示例 | 说明 |
|------|----------|---------|------|
| 分页查询 | GET | `/api/user/page` | 参数在 URL query string |
| 全量列表 | GET | `/api/role/list` | 参数在 URL query string（`list` 路由按模块提供，如 role/dept/menu；user 模块仅分页） |
| 详情 | 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 请求体（**本项目统一 DELETE + body**） |
### 统一响应格式
```json
{
"code": 0, // 0=成功，其他=失败
"ok": true, // 是否成功
"msg": "操作成功", // 提示信息
"data": {} // 响应数据
}
```
### 认证方式
```text
Authorization: Bearer <access_token>
```
公开接口放在 `routes/api.php` 中间件组**外**，认证接口统一在 `['auth.jwt', 'tenant', 'demo', 'log.operation']` 组内。
## 公开接口（无需认证）
| 模块 | 接口 | 方法 | 说明 |
|------|------|------|------|
| 登录 | `/api/login` | POST | 用户登录，返回双令牌 |
| 刷新 | `/api/refresh` | POST | refresh_token 换取新令牌对 |
| 验证码 | `/api/captcha` | GET | 获取图片验证码 |
| Token | `/api/oauth2/token` | POST | OAuth2 兼容获取/刷新 Token |
| Token | `/api/oauth2/check/token` | GET | 检查 Token 有效性 |
## 认证接口（组内，其余全部）
以下模块接口均位于认证中间件组内，需要 `Authorization` 头。
### 个人中心与公共
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 登出 | `/api/logout` | POST | 登出（吊销 refresh_token + 记录日志） |
| Token | `/api/oauth2/remove/{token}` | DELETE | 吊销指定令牌 |
| 首页 | `/api/index/getUser` | GET | 获取当前用户信息（含角色与权限） |
| 首页 | `/api/index/getMenus` | GET | 获取菜单树（动态路由数据源） |
| 首页 | `/api/index/updatePassword` | PUT | 修改密码（改密后全端下线） |
| 首页 | `/api/index/updateProfile` | PUT | 更新个人信息 |
| 上传 | `/api/upload/uploadFile` | POST | 上传文件（需 `sys:upload:file` 权限） |
### 系统管理
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 用户 | `/api/user/page` `detail/{id}` | GET | 分页 / 详情 |
| 用户 | `/api/user/add` `import` | POST | 新增 / Excel 导入 |
| 用户 | `/api/user/batchDelete` | DELETE | 批量删除 |
| 用户 | `/api/user/update` | PUT | 修改 |
| 用户 | `/api/user/resetPwd` | PUT | 重置密码 |
| 用户 | `/api/user/delete/{id}` `export` | DELETE / GET | 删除 / Excel 导出 |
| 角色 | `/api/role/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 角色 | `/api/role/add` `menu/save` | POST | 新增 / 保存菜单权限 |
| 角色 | `/api/role/batchDelete` | DELETE | 批量删除 |
| 角色 | `/api/role/update` | PUT | 修改 |
| 角色 | `/api/role/delete/{id}` | DELETE | 删除 |
| 角色 | `/api/role/menu/list/{id}` | GET | 获取角色菜单（含选中状态） |
| 菜单 | `/api/menu/list` `detail/{id}` | GET | 树形列表 / 详情 |
| 菜单 | `/api/menu/add` | POST | 新增 |
| 菜单 | `/api/menu/update` | PUT | 修改 |
| 菜单 | `/api/menu/delete/{id}` | DELETE | 删除 |
| 部门 | `/api/dept/list` `detail/{id}` | GET | 树形列表 / 详情 |
| 部门 | `/api/dept/add` | POST | 新增 |
| 部门 | `/api/dept/update` | PUT | 修改 |
| 部门 | `/api/dept/delete/{id}` | DELETE | 删除 |
| 职级 | `/api/level/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 职级 | `/api/level/add` `import` | POST | 新增 / Excel 导入 |
| 职级 | `/api/level/batchDelete` | DELETE | 批量删除 |
| 职级 | `/api/level/update` | PUT | 修改 |
| 职级 | `/api/level/delete/{id}` `export` | DELETE / GET | 删除 / Excel 导出 |
| 岗位 | `/api/position/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 岗位 | `/api/position/add` | POST | 新增 |
| 岗位 | `/api/position/batchDelete` | DELETE | 批量删除 |
| 岗位 | `/api/position/update` | PUT | 修改 |
| 岗位 | `/api/position/delete/{id}` | DELETE | 删除 |
| 租户 | `/api/tenant/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 租户 | `/api/tenant/add` `account` | POST | 新增 / 创建租户账号 |
| 租户 | `/api/tenant/batchDelete` | DELETE | 批量删除 |
| 租户 | `/api/tenant/update` | PUT | 修改 |
| 租户 | `/api/tenant/delete/{id}` | DELETE | 删除 |
| 租户 | `/api/tenant/users/{tenantId}` | GET | 租户用户列表 |
### 数据管理
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 字典 | `/api/dict/page` `detail/{id}` | GET | 分页 / 详情 |
| 字典 | `/api/dict/add` | POST | 新增 |
| 字典 | `/api/dict/batchDelete` | DELETE | 批量删除 |
| 字典 | `/api/dict/update` | PUT | 修改 |
| 字典 | `/api/dict/delete/{id}` | DELETE | 删除 |
| 字典 | `/api/dict/refreshCache` | GET | 刷新字典缓存（`#[DemoAllow]`） |
| 字典项 | `/api/dict/item/page` `detail/{id}` `getDictItemList/{code}` | GET | 分页 / 详情 / 按编码获取 |
| 字典项 | `/api/dict/item/add` | POST | 新增 |
| 字典项 | `/api/dict/item/batchDelete` | DELETE | 批量删除 |
| 字典项 | `/api/dict/item/update` | PUT | 修改 |
| 字典项 | `/api/dict/item/delete/{id}` | DELETE | 删除 |
| 配置 | `/api/config/page` `list` `detail/{id}` `web/index` | GET | 分页 / 全量 / 详情 / 网站配置 |
| 配置 | `/api/config/add` `web/save` | POST | 新增 / 保存网站配置 |
| 配置 | `/api/config/batchDelete` | DELETE | 批量删除 |
| 配置 | `/api/config/update` | PUT | 修改 |
| 配置 | `/api/config/delete/{id}` | DELETE | 删除 |
| 配置项 | `/api/config/item/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 配置项 | `/api/config/item/add` | POST | 新增 |
| 配置项 | `/api/config/item/batchDelete` | DELETE | 批量删除 |
| 配置项 | `/api/config/item/update` | PUT | 修改 |
| 配置项 | `/api/config/item/delete/{id}` | DELETE | 删除 |
| 参数 | `/api/param/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 参数 | `/api/param/add` | POST | 新增 |
| 参数 | `/api/param/batchDelete` | DELETE | 批量删除 |
| 参数 | `/api/param/update` | PUT | 修改 |
| 参数 | `/api/param/delete/{id}` | DELETE | 删除 |
| 城市 | `/api/city/list` `detail/{id}` `getCityList/{code}` `getParent/{id}` `findByParentCode` | GET | 列表 / 详情 / 级联查询 |
| 城市 | `/api/city/add` | POST | 新增 |
| 城市 | `/api/city/batchDelete` | DELETE | 批量删除 |
| 城市 | `/api/city/update` | PUT | 修改 |
| 城市 | `/api/city/delete/{id}` | DELETE | 删除 |
### 内容管理
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 文章 | `/api/article/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 文章 | `/api/article/add` | POST | 新增 |
| 文章 | `/api/article/batchDelete` | DELETE | 批量删除 |
| 文章 | `/api/article/update` | PUT | 修改 |
| 文章 | `/api/article/delete/{id}` | DELETE | 删除 |
| 分类 | `/api/category/list` `page` `detail/{id}` | GET | 树形 / 分页 / 详情 |
| 分类 | `/api/category/add` | POST | 新增 |
| 分类 | `/api/category/batchDelete` | DELETE | 批量删除 |
| 分类 | `/api/category/update` | PUT | 修改 |
| 分类 | `/api/category/delete/{id}` | DELETE | 删除 |
| 公告 | `/api/notice/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 公告 | `/api/notice/add` | POST | 新增 |
| 公告 | `/api/notice/batchDelete` | DELETE | 批量删除 |
| 公告 | `/api/notice/update` | PUT | 修改 |
| 公告 | `/api/notice/delete/{id}` | DELETE | 删除 |
| 友链 | `/api/link/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 友链 | `/api/link/add` | POST | 新增 |
| 友链 | `/api/link/batchDelete` | DELETE | 批量删除 |
| 友链 | `/api/link/update` | PUT | 修改 |
| 友链 | `/api/link/delete/{id}` | DELETE | 删除 |
### 监控管理
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 定时任务 | `/api/job/page` `list` `detail/{id}` | GET | 分页 / 全量 / 详情 |
| 定时任务 | `/api/job/runOnce/{id}` | GET | 手动执行一次 |
| 定时任务 | `/api/job/pause/{id}` `resume/{id}` `daemonStatus` | GET | 暂停 / 恢复 / 守护进程状态 |
| 定时任务 | `/api/job/add` `status` | POST | 新增 / 设置状态 |
| 定时任务 | `/api/job/batchDelete` | DELETE | 批量删除 |
| 定时任务 | `/api/job/update` | PUT | 修改 |
| 定时任务 | `/api/job/delete/{id}` | DELETE | 删除 |
| 任务日志 | `/api/job/log/page` `detail/{id}` | GET | 日志分页 / 详情 |
| 任务日志 | `/api/job/log/batchDelete` | DELETE | 批量删除日志 |
| 任务日志 | `/api/job/log/delete/{id}` | DELETE | 删除日志 |
### 日志审计
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 操作日志 | `/api/oper/log/page` `detail/{id}` | GET | 分页 / 详情 |
| 操作日志 | `/api/oper/log/batchDelete` | DELETE | 批量删除 |
| 操作日志 | `/api/oper/log/delete/{id}` | DELETE | 删除 |
| 登录日志 | `/api/login/log/page` `detail/{id}` | GET | 分页 / 详情 |
| 登录日志 | `/api/login/log/batchDelete` | DELETE | 批量删除 |
| 登录日志 | `/api/login/log/delete/{id}` | DELETE | 删除 |
### 示例与开发工具
| 模块 | 主要接口 | 方法 | 说明 |
|------|---------|------|------|
| 示例 | `/api/example/page` `list` `detail/{id}` `export` | GET | 分页 / 全量 / 详情 / 导出 |
| 示例 | `/api/example/add` `import` | POST | 新增 / 导入 |
| 示例 | `/api/example/batchDelete` | DELETE | 批量删除 |
| 示例 | `/api/example/update` | PUT | 修改 |
| 示例 | `/api/example/delete/{id}` | DELETE | 删除 |
| 文件模板 | `/api/file/template/page` `detail/{id}` `getTemplateByCode/{code}` | GET | 分页 / 详情 / 按编码获取 |
| 文件模板 | `/api/file/template/add` | POST | 新增 |
| 文件模板 | `/api/file/template/batchDelete` | DELETE | 批量删除 |
| 文件模板 | `/api/file/template/update` | PUT | 修改 |
| 文件模板 | `/api/file/template/delete/{id}` | DELETE | 删除 |
| 代码生成 | `/api/generator/page` `preview` | GET | 可生成表列表 / 预览代码 |
| 代码生成 | `/api/generator/generate` `batchGenerate` | POST | 生成 / 批量生成 |
## 接口统计
| 分组 | 接口数量 | 说明 |
|------|---------|------|
| 公开接口 | 5 | 登录 / 刷新 / 验证码 / OAuth2 |
| 个人中心与公共 | 7 | 登出 / 用户信息 / 菜单 / 改密 / 改资料 / 上传 / 吊销 |
| 系统管理 | ~52 | 用户 / 角色 / 菜单 / 部门 / 岗位 / 职级 / 租户 |
| 数据管理 | ~50 | 字典 / 字典项 / 配置 / 配置项 / 参数 / 城市 |
| 内容管理 | ~28 | 文章 / 分类 / 公告 / 友链 |
| 监控管理 | 16 | 定时任务 / 任务日志 |
| 日志审计 | 8 | 操作日志 / 登录日志 |
| 示例与开发工具 | ~20 | 示例 / 文件模板 / 代码生成 |
| **合计** | **≈180** | 以 `php artisan route:list` 为准 |
:::tip 动态获取
执行 `php artisan route:list` 可输出全部路由（方法、URI、中间件、控制器动作），是核对接口清单的最权威来源。详细清单见 [附录 E](/zh/appendix/api-cheatsheet.html)。
:::
Reference in New Issue View Git Blame Copy Permalink