接口协议

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

本文为权威口径，包含两部分：

接口规范：风格、命名、响应结构、分页、错误码等通用约定
接口清单：各业务模块的接口清单与路径

前端 TypeScript 的接口/类型约定请查看：

接口与类型约定（前端）

一、RESTful API 设计规范

1.1 核心原则

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

json

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

响应码规范：

00000 - 成功
A0001 - 用户端错误（参数错误、认证失败等）
B0001 - 系统错误（服务器内部错误）
C0001 - 第三方服务错误

1.5 排序参数规范（推荐）

不推荐：

orderBy

原因：容易导致 SQL 语义泄露（字段拼接、注入风险、跨语言实现难统一）。

参数	说明
`sortBy`	排序字段
`order`	`ASC` / `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`	刷新访问令牌

请求示例（账号密码登录）：

bash

POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded

username=admin&password=123456

响应示例：

json

{
  "code": "00000",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600
  }
}

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

请求示例（用户分页）：

bash

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

响应示例：

json

{
  "code": "00000",
  "msg": "一切ok",
  "data": [
    {
      "userId": 1,
      "username": "admin",
      "nickname": "系统管理员",
      "mobile": "18888888888",
      "gender": 1,
      "avatar": "https://...",
      "email": "admin@example.com",
      "status": 1,
      "deptName": "研发部门",
      "roleNames": "系统管理员",
      "createTime": "2023-01-01 00:00:00"
    }
  ],
  "page": {
    "pageNum": 1,
    "pageSize": 10,
    "total": 100
  }
}

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`	根据文件路径删除

请求示例（文件上传）：

bash

POST /api/v1/files
Content-Type: multipart/form-data

file: <binary>

响应示例：

json

{
  "code": "00000",
  "data": {
    "name": "avatar.jpg",
    "url": "https://cdn.example.com/2024/12/avatar.jpg",
    "size": 102400,
    "type": "image/jpeg"
  }
}

4.2 短信服务

接口标题	HTTP 方法	接口路径	说明
发送短信	POST	`/api/v1/sms/send`	发送短信验证码或通知

4.3 邮件服务

接口标题	HTTP 方法	接口路径	说明
发送邮件	POST	`/api/v1/mails/send`	发送邮件

4.4 WebSocket

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

五、分页查询规范

5.1 分页参数

请求参数：

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

示例：

bash

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

5.2 分页响应格式

json

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

六、错误处理

6.1 错误响应格式

json

{
  "code": "A0001",
  "msg": "用户名或密码错误",
  "data": null
}

6.2 常见错误码

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

文档维护：本页为接口协议权威文档，接口变更需同步更新并保持向后兼容。

接口协议 ​

一、RESTful API 设计规范 ​

1.1 核心原则 ​

1.2 URL 规范 ​

1.3 命名规范 ​

1.4 统一响应格式 ​

1.5 排序参数规范（推荐） ​

二、认证与授权 ​

2.1 认证接口 ​

2.2 认证方式 ​

三、系统管理 ​

3.1 用户管理 ​

3.2 角色管理 ​

3.3 菜单管理 ​

3.4 部门管理 ​

3.5 字典管理 ​

3.6 系统配置 ​

3.7 通知公告 ​

3.8 系统日志 ​

四、平台服务 ​

4.1 文件服务 ​

4.2 短信服务 ​

4.3 邮件服务 ​

4.4 WebSocket ​

五、分页查询规范 ​

5.1 分页参数 ​

5.2 分页响应格式 ​

六、错误处理 ​

6.1 错误响应格式 ​

6.2 常见错误码 ​

接口协议

一、RESTful API 设计规范

1.1 核心原则

1.2 URL 规范

1.3 命名规范

1.4 统一响应格式

1.5 排序参数规范（推荐）

二、认证与授权

2.1 认证接口

2.2 认证方式

三、系统管理

3.1 用户管理

3.2 角色管理

3.3 菜单管理

3.4 部门管理

3.5 字典管理

3.6 系统配置

3.7 通知公告

3.8 系统日志

四、平台服务

4.1 文件服务

4.2 短信服务

4.3 邮件服务

4.4 WebSocket

五、分页查询规范

5.1 分页参数

5.2 分页响应格式

六、错误处理

6.1 错误响应格式

6.2 常见错误码