System项目AI文档

Appearance

角色权限模块接口规范 ​

文档编号: SYS-INT-API-ROLE-001
模块: 角色权限 (ROLE)
基础路径: /api/v1/roles
版本: v1
日期: 2026-03-09
作者: 系统架构师
状态: ✅ 已评审

一、模块概述 ​

1.1 功能说明 ​

角色权限模块提供系统角色管理、权限管理、角色权限分配等功能，支持基于RBAC（Role-Based Access Control）的权限控制模型。

1.2 接口列表 ​

序号接口名称方法路径权限要求
1查询角色列表GET/rolesrole:read
2创建角色POST/rolesrole:create
3查询角色详情GET/roles/{id}role:read
4更新角色PUT/roles/{id}role:update
5删除角色DELETE/roles/{id}role:delete
6查询角色权限GET/roles/{id}/permissionsrole:read, permission:read
7分配角色权限POST/roles/{id}/permissionsrole:update, permission:update
8查询角色用户GET/roles/{id}/usersrole:read, user:read
9查询权限树GET/permissions/treepermission:read
10创建权限POST/permissionspermission:create
11更新权限PUT/permissions/{id}permission:update
12删除权限DELETE/permissions/{id}permission:delete

二、接口详细定义 ​

1. 查询角色列表 ​

基本信息 ​

项目内容
接口名称查询角色列表
请求方法GET
接口路径/api/v1/roles
权限要求role:read

请求参数 ​

Query参数:

参数名类型必填说明示例
pageinteger否当前页码，默认11
sizeinteger否每页大小，默认1010
keywordstring否搜索关键词（角色名称/编码）admin
statusinteger否状态：0-禁用，1-启用1

响应数据 ​

成功响应:

json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "code": "admin",
        "name": "系统管理员",
        "description": "拥有系统所有权限",
        "status": 1,
        "statusName": "启用",
        "permissionCount": 50,
        "userCount": 3,
        "createTime": "2024-01-01T10:00:00Z",
        "updateTime": "2024-01-01T10:00:00Z"
      }
    ],
    "total": 10
  },
  "error": null,
  "message": "ok"
}

2. 创建角色 ​

基本信息 ​

项目内容
接口名称创建角色
请求方法POST
接口路径/api/v1/roles
权限要求role:create

请求参数 ​

Body参数 (application/json):

参数名类型必填说明示例
codestring是角色编码，唯一，2-50字符manager
namestring是角色名称，2-50字符部门经理
descriptionstring否角色描述部门管理权限
statusinteger否状态：0-禁用，1-启用，默认11
permissionIdsarray否权限ID列表[1, 2, 3]

请求示例 ​

http
POST /api/v1/roles
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "code": "manager",
  "name": "部门经理",
  "description": "部门管理权限",
  "status": 1,
  "permissionIds": [1, 2, 3, 4, 5]
}

响应数据 ​

成功响应:

json
{
  "code": 0,
  "data": {
    "id": 2,
    "code": "manager",
    "name": "部门经理",
    "status": 1,
    "createTime": "2024-03-09T10:00:00Z"
  },
  "error": null,
  "message": "ok"
}

3. 查询角色详情 ​

基本信息 ​

项目内容
接口名称查询角色详情
请求方法GET
接口路径/api/v1/roles/{id}
权限要求role:read

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是角色ID1

响应数据 ​

json
{
  "code": 0,
  "data": {
    "id": 1,
    "code": "admin",
    "name": "系统管理员",
    "description": "拥有系统所有权限",
    "status": 1,
    "statusName": "启用",
    "permissions": [
      {
        "id": 1,
        "code": "user:create",
        "name": "用户创建"
      }
    ],
    "permissionCount": 50,
    "userCount": 3,
    "createTime": "2024-01-01T10:00:00Z",
    "updateTime": "2024-03-09T10:00:00Z"
  },
  "error": null,
  "message": "ok"
}

4. 更新角色 ​

基本信息 ​

项目内容
接口名称更新角色
请求方法PUT
接口路径/api/v1/roles/{id}
权限要求role:update

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是角色ID1

Body参数:

参数名类型必填说明
namestring否角色名称
descriptionstring否角色描述
statusinteger否状态

5. 删除角色 ​

基本信息 ​

项目内容
接口名称删除角色
请求方法DELETE
接口路径/api/v1/roles/{id}
权限要求role:delete

响应数据 ​

错误响应:

json
{
  "code": -1,
  "data": {
    "userCount": 5
  },
  "error": "该角色已分配给用户，无法删除",
  "message": "该角色已分配给用户，无法删除"
}

6. 查询角色权限 ​

基本信息 ​

项目内容
接口名称查询角色权限
请求方法GET
接口路径/api/v1/roles/{id}/permissions
权限要求role:read, permission:read

响应数据 ​

json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "code": "user:create",
      "name": "用户创建",
      "type": 1,
      "typeName": "菜单权限"
    },
    {
      "id": 2,
      "code": "user:update",
      "name": "用户更新",
      "type": 2,
      "typeName": "按钮权限"
    }
  ],
  "error": null,
  "message": "ok"
}

7. 分配角色权限 ​

基本信息 ​

项目内容
接口名称分配角色权限
请求方法POST
接口路径/api/v1/roles/{id}/permissions
权限要求role:update, permission:update

请求参数 ​

Body参数:

参数名类型必填说明示例
permissionIdsarray是权限ID列表[1, 2, 3, 4, 5]

请求示例 ​

http
POST /api/v1/roles/1/permissions
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "permissionIds": [1, 2, 3, 4, 5]
}

8. 查询角色用户 ​

基本信息 ​

项目内容
接口名称查询角色用户
请求方法GET
接口路径/api/v1/roles/{id}/users
权限要求role:read, user:read

响应数据 ​

json
{
  "code": 0,
  "data": {
    "items": [
      {
        "id": 1,
        "username": "zhangsan",
        "nickname": "张三",
        "email": "zhangsan@example.com"
      }
    ],
    "total": 3
  },
  "error": null,
  "message": "ok"
}

9. 查询权限树 ​

基本信息 ​

项目内容
接口名称查询权限树
请求方法GET
接口路径/api/v1/permissions/tree
权限要求permission:read

请求参数 ​

Query参数:

参数名类型必填说明示例
typeinteger否权限类型：1-菜单，2-按钮，3-接口1
statusinteger否状态：0-禁用，1-启用1

响应数据 ​

json
{
  "code": 0,
  "data": [
    {
      "id": 1,
      "code": "system",
      "name": "系统管理",
      "type": 1,
      "typeName": "菜单权限",
      "icon": "Setting",
      "path": "/system",
      "sort": 1,
      "status": 1,
      "children": [
        {
          "id": 2,
          "code": "user:list",
          "name": "用户管理",
          "type": 1,
          "typeName": "菜单权限",
          "icon": "User",
          "path": "/system/user",
          "sort": 1,
          "status": 1,
          "children": [
            {
              "id": 3,
              "code": "user:create",
              "name": "用户创建",
              "type": 2,
              "typeName": "按钮权限",
              "sort": 1,
              "status": 1
            }
          ]
        }
      ]
    }
  ],
  "error": null,
  "message": "ok"
}

10. 创建权限 ​

基本信息 ​

项目内容
接口名称创建权限
请求方法POST
接口路径/api/v1/permissions
权限要求permission:create

请求参数 ​

Body参数:

参数名类型必填说明示例
codestring是权限编码，唯一user:create
namestring是权限名称用户创建
typeinteger是类型：1-菜单，2-按钮，3-接口2
parentIdinteger否父权限ID2
iconstring否图标（菜单类型）User
pathstring否路径（菜单类型）/system/user
sortinteger否排序，默认01
statusinteger否状态：0-禁用，1-启用1

请求示例 ​

http
POST /api/v1/permissions
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

{
  "code": "user:export",
  "name": "用户导出",
  "type": 2,
  "parentId": 2,
  "sort": 5,
  "status": 1
}

11. 更新权限 ​

基本信息 ​

项目内容
接口名称更新权限
请求方法PUT
接口路径/api/v1/permissions/{id}
权限要求permission:update

请求参数 ​

Path参数:

参数名类型必填说明示例
idinteger是权限ID1

Body参数:

参数名类型必填说明
namestring否权限名称
iconstring否图标
pathstring否路径
sortinteger否排序
statusinteger否状态

12. 删除权限 ​

基本信息 ​

项目内容
接口名称删除权限
请求方法DELETE
接口路径/api/v1/permissions/{id}
权限要求permission:delete

响应数据 ​

错误响应 (409 Conflict):

json
{
  "code": 409,
  "message": "该权限有子权限，无法删除",
  "data": {
    "childrenCount": 3
  },
  "timestamp": 1709827200000
}

三、数据模型 ​

3.1 角色对象 (Role) ​

字段类型必填说明
idinteger是角色ID
codestring是角色编码，唯一，2-50字符
namestring是角色名称，2-50字符
descriptionstring否角色描述
statusinteger是状态：0-禁用，1-启用
permissionCountinteger否权限数量
userCountinteger否用户数量
createTimedatetime是创建时间
updateTimedatetime是更新时间

3.2 权限对象 (Permission) ​

字段类型必填说明
idinteger是权限ID
codestring是权限编码，唯一
namestring是权限名称
typeinteger是类型：1-菜单，2-按钮，3-接口
parentIdinteger否父权限ID
iconstring否图标（菜单类型）
pathstring否路径（菜单类型）
sortinteger否排序
statusinteger是状态：0-禁用，1-启用
createTimedatetime是创建时间
updateTimedatetime是更新时间

3.3 权限类型枚举 ​

值名称说明
1菜单权限左侧菜单导航
2按钮权限页面按钮操作
3接口权限API接口访问

四、权限编码规范 ​

4.1 编码格式 ​

{模块}:{操作}

示例:

  • user:create - 用户创建
  • user:update - 用户更新
  • user:delete - 用户删除
  • user:read - 用户查询
  • role:* - 角色所有权限

4.2 操作类型 ​

操作说明
create创建
update更新
delete删除
read查询
*所有操作

五、错误码 ​

错误码错误信息说明
400请求参数错误参数校验失败
401未认证Token无效或过期
403无权限用户无此操作权限
404角色/权限不存在指定的ID不存在
409数据冲突编码已存在或有依赖关系
500服务器内部错误系统异常

六、相关文档 ​

七、评审记录 ​

7.1 评审意见 ​

序号评审项评审结果评审意见
1接口完整性✓ 通过覆盖RBAC权限管理所有功能
2接口规范性✓ 通过符合RESTful API设计规范
3权限设计✓ 通过RBAC模型设计合理，权限编码规范
4权限树设计✓ 通过树形结构清晰，支持多级权限
5数据模型✓ 通过模型设计完整，字段定义清晰

7.2 评审结论 ​

评审结论: 通过

评审意见: 角色权限模块接口规范完整，RBAC设计合理，权限控制粒度适中，可作为开发依据。

7.3 签字确认 ​

角色姓名签字日期意见
技术总监张总_______________2026-03-09同意
系统架构师李工_______________2026-03-09同意
后端架构师王工_______________2026-03-09同意
前端负责人陈工_______________2026-03-09同意

八、修订记录 ​

版本日期作者变更内容
1.02026-03-09系统架构师初始版本，定义角色权限模块12个接口
1.12026-03-11系统架构师统一响应格式，与Mock服务保持一致

Released under the MIT License.

Copyright © 2026 linsir | 鄂ICP备99999999号