import{_ as d,o as e,c as a,a2 as o}from"./chunks/framework.BbmSSMjL.js";const E=JSON.parse('{"title":"8.7 API 接口总览","description":"","frontmatter":{},"headers":[],"relativePath":"zh/api-spec/overview.md","filePath":"zh/api-spec/overview.md"}'),i={name:"zh/api-spec/overview.md"};function c(r,t,p,s,l,h){return e(),a("div",null,[...t[0]||(t[0]=[o(`

8.7 API 接口总览

概述

本节按模块分组列出所有 API 接口的概述（全部来自 routes/api.php 实际路由），详细路由清单见附录 E API 接口速查表。

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` 为准

动态获取

执行 php artisan route:list 可输出全部路由（方法、URI、中间件、控制器动作），是核对接口清单的最权威来源。详细清单见附录 E。

`,33)])])}const T=d(i,[["render",c]]);export{E as __pageData,T as default};

8.7 API 接口总览 ​

API 设计规范 ​

命名规范 ​

HTTP 方法规范 ​

统一响应格式 ​

认证方式 ​

公开接口（无需认证） ​

认证接口（组内，其余全部） ​

个人中心与公共 ​

系统管理 ​

数据管理 ​

内容管理 ​

监控管理 ​

日志审计 ​

示例与开发工具 ​

接口统计 ​