接口文档

版本: v1.0.0
更新日期: 2025-12-07
适用范围: 所有后端（Java/Node/Go/Python/PHP/ASP.NET Core）

本章节包含 vue3-element-admin 对接的后端接口文档，所有后端实现遵循统一的接口协议。

一、RESTful API 设计规范

1.1 核心原则

1. 资源路径使用复数名词：/api/v1/users 而非 /api/v1/user
2. HTTP 方法语义化：
   • GET - 查询资源
   • POST - 创建资源
   • PUT - 完整更新资源
   • PATCH - 部分更新资源
   • DELETE - 删除资源
3. URL 层级清晰：/api/v1/{resource}/{id}/{sub-resource}
4. 统一响应格式：所有接口返回统一的 JSON 结构

1.2 URL 规范

基础路径: /api/v1
资源路径: /api/v1/{resources}     (必须使用复数)
单个资源: /api/v1/{resources}/{id}
子资源:   /api/v1/{resources}/{id}/{sub-resources}

示例：

• ✅ /api/v1/users/1 - 正确
• ✅ /api/v1/users/1/roles - 正确（用户的角色列表）
• ❌ /api/v1/user/1 - 错误（应使用复数）

1.3 命名规范

• URL 路径：小写字母 + 连字符，如 /dict-items
• 查询参数：驼峰命名，如 ?pageNum=1&pageSize=10
• JSON 字段：驼峰命名，如 {"userId": 1, "userName": "admin"}

1.4 统一响应格式

{
  "code": "00000", // 响应码
  "msg": "Success", // 响应消息
  "data": {}, // 响应数据
  "timestamp": 1701936000000 // 时间戳（可选）
}

响应码规范：

错误码	说明	HTTP 状态码
00000	成功	200
A0001	用户端错误	400
A0200	用户未登录	401
A0300	用户无权限	403
A0400	资源不存在	404
B0001	系统执行出错	500
B0100	系统资源异常	503
C0001	第三方服务错误	500

1.5 排序参数规范

参数	说明
sortBy	排序字段
order	ASC / DESC

示例：GET /api/v1/users?sortBy=createTime&order=DESC

---

二、认证与授权

2.1 认证接口

接口标题	HTTP 方法	接口路径	说明
获取验证码	GET	/api/v1/auth/captcha	获取图形验证码
账号密码登录	POST	/api/v1/auth/login	用户名密码登录
短信验证码登录	POST	/api/v1/auth/login/sms	手机号+验证码登录
发送短信验证码	POST	/api/v1/auth/sms/code	发送登录验证码
微信授权登录	POST	/api/v1/auth/login/wechat	微信 Web 扫码登录
微信小程序登录(Code)	POST	/api/v1/auth/wx/miniapp/code-login	微信小程序授权码登录
微信小程序登录(手机号)	POST	/api/v1/auth/wx/miniapp/phone-login	微信小程序手机号登录
退出登录	DELETE	/api/v1/auth/logout	注销登录
刷新令牌	POST	/api/v1/auth/refresh-token	刷新访问令牌

2.2 认证方式

所有需要认证的接口必须在请求头中携带 Token：

Authorization: Bearer {accessToken}

---

三、系统管理

3.1 用户管理

接口标题	HTTP 方法	接口路径	权限标识
用户分页列表	GET	/api/v1/users	sys:user:list
获取当前用户信息	GET	/api/v1/users/me	-
新增用户	POST	/api/v1/users	sys:user:create
获取用户表单数据	GET	/api/v1/users/{userId}/form	sys:user:update
修改用户	PUT	/api/v1/users/{userId}	sys:user:update
删除用户	DELETE	/api/v1/users/{ids}	sys:user:delete
修改用户状态	PATCH	/api/v1/users/{userId}/status	sys:user:update
修改用户密码	PATCH	/api/v1/users/{userId}/password	sys:user:reset-password
获取用户下拉选项	GET	/api/v1/users/options	-

3.2 角色管理

接口标题	HTTP 方法	接口路径	权限标识
角色分页列表	GET	/api/v1/roles	sys:role:list
角色下拉选项	GET	/api/v1/roles/options	-
新增角色	POST	/api/v1/roles	sys:role:create
获取角色表单数据	GET	/api/v1/roles/{id}/form	sys:role:update
修改角色	PUT	/api/v1/roles/{id}	sys:role:update
删除角色	DELETE	/api/v1/roles/{id}	sys:role:delete
获取角色菜单 ID 集合	GET	/api/v1/roles/{id}/menu-ids	sys:role:update
分配角色菜单权限	PUT	/api/v1/roles/{id}/menus	sys:role:update

3.3 菜单管理

接口标题	HTTP 方法	接口路径	权限标识
菜单列表	GET	/api/v1/menus	sys:menu:list
菜单下拉选项	GET	/api/v1/menus/options	-
获取当前用户路由	GET	/api/v1/menus/routes	-
新增菜单	POST	/api/v1/menus	sys:menu:create
获取菜单表单数据	GET	/api/v1/menus/{id}/form	sys:menu:update
修改菜单	PUT	/api/v1/menus/{id}	sys:menu:update
删除菜单	DELETE	/api/v1/menus/{id}	sys:menu:delete

3.4 部门管理

接口标题	HTTP 方法	接口路径	权限标识
部门列表	GET	/api/v1/depts	sys:dept:list
部门下拉选项	GET	/api/v1/depts/options	-
新增部门	POST	/api/v1/depts	sys:dept:create
获取部门表单数据	GET	/api/v1/depts/{id}/form	sys:dept:update
修改部门	PUT	/api/v1/depts/{id}	sys:dept:update
删除部门	DELETE	/api/v1/depts/{ids}	sys:dept:delete

3.5 字典管理

接口标题	HTTP 方法	接口路径	权限标识
字典分页列表	GET	/api/v1/dicts	sys:dict:list
字典下拉选项	GET	/api/v1/dicts/options	-
新增字典	POST	/api/v1/dicts	sys:dict:create
获取字典表单数据	GET	/api/v1/dicts/{id}/form	sys:dict:update
修改字典	PUT	/api/v1/dicts/{id}	sys:dict:update
删除字典	DELETE	/api/v1/dicts/{id}	sys:dict:delete
字典项分页列表	GET	/api/v1/dicts/{dictCode}/items	-
字典项下拉选项	GET	/api/v1/dicts/{dictCode}/items/options	-
新增字典项	POST	/api/v1/dicts/{dictCode}/items	sys:dict:update
获取字典项表单	GET	/api/v1/dicts/{dictCode}/items/{itemId}/form	sys:dict:update
修改字典项	PUT	/api/v1/dicts/{dictCode}/items/{itemId}	sys:dict:update
删除字典项	DELETE	/api/v1/dicts/{dictCode}/items/{itemIds}	sys:dict:delete

3.6 系统配置

接口标题	HTTP 方法	接口路径	权限标识
配置分页列表	GET	/api/v1/configs	sys:config:list
新增系统配置	POST	/api/v1/configs	sys:config:create
获取配置表单数据	GET	/api/v1/configs/{id}/form	-
修改系统配置	PUT	/api/v1/configs/{id}	sys:config:update
删除系统配置	DELETE	/api/v1/configs/{id}	sys:config:delete
刷新配置缓存	PUT	/api/v1/configs/refresh	sys:config:refresh

3.7 通知公告

接口标题	HTTP 方法	接口路径	权限标识
通知公告分页列表	GET	/api/v1/notices	sys:notice:list
获取我的通知	GET	/api/v1/notices/my	-
新增通知公告	POST	/api/v1/notices	sys:notice:create
获取通知表单数据	GET	/api/v1/notices/{id}/form	sys:notice:update
获取通知详情	GET	/api/v1/notices/{id}/detail	-
修改通知公告	PUT	/api/v1/notices/{id}	sys:notice:update
发布通知公告	PUT	/api/v1/notices/{id}/publish	sys:notice:publish
撤回通知公告	PUT	/api/v1/notices/{id}/revoke	sys:notice:revoke
删除通知公告	DELETE	/api/v1/notices/{ids}	sys:notice:delete
全部标记已读	PATCH	/api/v1/notices/read/all	-
批量标记已读	PATCH	/api/v1/notices/read	-

3.8 系统日志

接口标题	HTTP 方法	接口路径	权限标识
日志分页列表	GET	/api/v1/logs	sys:log:list
清空日志	DELETE	/api/v1/logs	sys:log:delete
导出日志	GET	/api/v1/logs/export	sys:log:export

---

四、平台服务

4.1 文件服务

接口标题	HTTP 方法	接口路径	说明
文件上传	POST	/api/v1/files	支持图片、文档、视频等
文件删除	DELETE	/api/v1/files	根据文件路径删除

4.2 WebSocket

接口标题	协议	接口路径	说明
WebSocket 连接	WS	/ws	实时消息推送

---

五、分页查询规范

5.1 分页参数

请求参数：

• pageNum: 页码（从 1 开始）
• pageSize: 每页条数

示例：

GET /api/v1/users?pageNum=1&pageSize=10

5.2 分页响应格式

{
  "code": "00000",
  "msg": "一切ok",
  "data": [],
  "page": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 100
  }
}

---

六、在线文档

各后端提供 Swagger 在线接口文档：

后端	文档地址
Java	/doc.html
Node	/api
Go	/swagger/index.html
Python	/swagger
PHP	/swagger
.NET	/swagger

---

七、模块导航

认证模块

• 登录认证 - 登录、登出、刷新令牌

系统管理

• 用户管理 - 用户 CRUD
• 角色管理 - 角色 CRUD、权限分配
• 菜单管理 - 菜单 CRUD、路由数据
• 部门管理 - 部门 CRUD、树形结构

文件服务

• 文件上传 - 单文件、多文件上传