角色管理API文档

概述

角色管理API模块负责处理系统角色的增删改查、权限分配、角色用户关联等功能。

文件位置: src/api/role.js

API接口

1. 获取角色列表 - getRoleList

功能: 获取角色列表数据，支持分页和搜索

请求方式: GET

接口地址: /role/list

参数:

{
  page: number,        // 页码，默认1
  pageSize: number,    // 每页数量，默认20
  keyword: string,     // 搜索关键词（可选）
  status: number,      // 状态筛选（可选）1-启用 0-禁用
  type: string        // 角色类型筛选（可选）
}

返回数据:

{
  status: boolean,
  msg: string,
  data: {
    list: [
      {
        id: number,           // 角色ID
        name: string,         // 角色名称
        code: string,         // 角色编码
        type: string,         // 角色类型
        level: number,        // 角色级别
        status: number,       // 状态 1-启用 0-禁用
        description: string,  // 角色描述
        permissions: Array,   // 权限列表
        menuIds: Array,       // 菜单ID列表
        userCount: number,    // 用户数量
        isDefault: number,    // 是否默认角色 1-是 0-否
        isSystem: number,     // 是否系统角色 1-是 0-否
        createTime: string,   // 创建时间
        updateTime: string,   // 更新时间
        createBy: string,     // 创建人
        updateBy: string      // 更新人
      }
    ],
    total: number,
    page: number,
    pageSize: number
  }
}

使用示例:

import { getRoleList } from '@/api/role'

const loadRoles = async () => {
  try {
    const params = {
      page: 1,
      pageSize: 20,
      status: 1
    }
    const result = await getRoleList(params)
    if (result.status) {
      console.log('角色列表:', result.data.list)
    }
  } catch (error) {
    console.error('获取角色列表失败:', error)
  }
}

2. 获取角色详情 - getRoleDetail

功能: 根据角色ID获取角色详细信息

请求方式: GET

接口地址: /role/detail/{id}

参数:

{
  id: number  // 角色ID
}

返回数据:

{
  status: boolean,
  data: {
    id: number,
    name: string,
    code: string,
    type: string,
    level: number,
    status: number,
    description: string,
    permissions: [        // 详细权限信息
      {
        id: number,
        name: string,
        code: string,
        type: string,
        resource: string
      }
    ],
    menuIds: Array,
    menus: [             // 详细菜单信息
      {
        id: number,
        name: string,
        title: string,
        path: string
      }
    ],
    users: [             // 关联用户信息
      {
        id: number,
        username: string,
        realname: string
      }
    ],
    createTime: string,
    updateTime: string
  }
}

3. 创建角色 - createRole

功能: 创建新角色

请求方式: POST

接口地址: /role/create

参数:

{
  name: string,         // 角色名称（必填）
  code: string,         // 角色编码（必填）
  type: string,         // 角色类型（可选）
  level: number,        // 角色级别（可选）
  status: number,       // 状态（可选，默认1）
  description: string,  // 角色描述（可选）
  permissions: Array,   // 权限ID列表（可选）
  menuIds: Array,       // 菜单ID列表（可选）
  isDefault: number     // 是否默认角色（可选，默认0）
}

返回数据:

{
  status: boolean,
  msg: string,
  data: {
    id: number  // 新创建的角色ID
  }
}

4. 更新角色 - updateRole

功能: 更新角色信息

请求方式: PUT

接口地址: /role/update/{id}

参数:

{
  id: number,           // 角色ID（必填）
  name: string,         // 角色名称
  code: string,         // 角色编码
  type: string,         // 角色类型
  level: number,        // 角色级别
  status: number,       // 状态
  description: string,  // 角色描述
  permissions: Array,   // 权限ID列表
  menuIds: Array,       // 菜单ID列表
  isDefault: number     // 是否默认角色
}

5. 删除角色 - deleteRole

功能: 删除角色（软删除）

请求方式: DELETE

接口地址: /role/delete/{id}

参数:

{
  id: number  // 角色ID
}

返回数据:

{
  status: boolean,
  msg: string
}

6. 分配权限 - assignPermissions

功能: 为角色分配权限

请求方式: PUT

接口地址: /role/assign-permissions

参数:

{
  roleId: number,       // 角色ID
  permissionIds: Array, // 权限ID列表
  menuIds: Array        // 菜单ID列表
}

返回数据:

{
  status: boolean,
  msg: string
}

7. 分配用户 - assignUsers

功能: 为角色分配用户

请求方式: PUT

接口地址: /role/assign-users

参数:

{
  roleId: number,    // 角色ID
  userIds: Array,    // 用户ID列表
  action: string     // 操作类型 'add'-添加 'remove'-移除 'replace'-替换
}

8. 获取角色权限 - getRolePermissions

功能: 获取角色的权限列表

请求方式: GET

接口地址: /role/{id}/permissions

参数:

{
  id: number  // 角色ID
}

返回数据:

{
  status: boolean,
  data: {
    permissions: [
      {
        id: number,
        name: string,
        code: string,
        type: string,
        resource: string,
        action: string
      }
    ],
    menus: [
      {
        id: number,
        name: string,
        title: string,
        path: string,
        permission: string
      }
    ]
  }
}

9. 获取角色用户 - getRoleUsers

功能: 获取角色关联的用户列表

请求方式: GET

接口地址: /role/{id}/users

参数:

{
  id: number,          // 角色ID
  page: number,        // 页码
  pageSize: number,    // 每页数量
  keyword: string      // 搜索关键词
}

返回数据:

{
  status: boolean,
  data: {
    list: [
      {
        id: number,
        username: string,
        realname: string,
        email: string,
        mobile: string,
        department: string,
        status: number,
        assignTime: string
      }
    ],
    total: number
  }
}

10. 复制角色 - copyRole

功能: 复制现有角色创建新角色

请求方式: POST

接口地址: /role/copy

参数:

{
  sourceRoleId: number,  // 源角色ID
  name: string,          // 新角色名称
  code: string,          // 新角色编码
  description: string    // 新角色描述
}

11. 批量操作角色 - batchOperateRoles

功能: 批量启用、禁用或删除角色

请求方式: PUT

接口地址: /role/batch-operate

参数:

{
  ids: Array,        // 角色ID列表
  operation: string, // 操作类型 'enable'-启用 'disable'-禁用 'delete'-删除
  reason: string     // 操作原因（可选）
}

数据结构

Role - 角色信息

{
  id: number,           // 角色ID
  name: string,         // 角色名称
  code: string,         // 角色编码（唯一）
  type: string,         // 角色类型 'system'-系统角色 'custom'-自定义角色
  level: number,        // 角色级别（数字越小级别越高）
  status: number,       // 状态 1-启用 0-禁用
  description: string,  // 角色描述
  permissions: Array,   // 权限列表
  menuIds: Array,       // 菜单ID列表
  userCount: number,    // 关联用户数量
  isDefault: number,    // 是否默认角色 1-是 0-否
  isSystem: number,     // 是否系统角色 1-是 0-否（系统角色不可删除）
  createTime: string,   // 创建时间
  updateTime: string,   // 更新时间
  createBy: string,     // 创建人
  updateBy: string      // 更新人
}

Permission - 权限信息

{
  id: number,           // 权限ID
  name: string,         // 权限名称
  code: string,         // 权限编码
  type: string,         // 权限类型 'menu'-菜单 'button'-按钮 'api'-接口
  resource: string,     // 资源标识
  action: string,       // 操作类型 'view'-查看 'add'-新增 'edit'-编辑 'delete'-删除
  description: string,  // 权限描述
  parentId: number,     // 父权限ID
  level: number,        // 权限层级
  sort: number          // 排序
}

业务规则

角色层级

支持角色层级管理
高级别角色可以管理低级别角色
系统角色不可删除和修改核心权限

权限继承

子权限依赖父权限
分配父权限时自动包含子权限
移除父权限时自动移除子权限

默认角色

新用户自动分配默认角色
系统必须至少有一个默认角色
默认角色不可删除

权限验证

用户权限 = 所有角色权限的并集
权限验证支持通配符匹配
支持动态权限验证

使用示例

创建角色并分配权限

import { createRole, assignPermissions } from '@/api/role'

const createRoleWithPermissions = async () => {
  // 1. 创建角色
  const roleData = {
    name: '部门经理',
    code: 'DEPT_MANAGER',
    type: 'custom',
    level: 3,
    description: '部门经理角色，可以管理本部门用户'
  }
  
  try {
    const createResult = await createRole(roleData)
    if (createResult.status) {
      const roleId = createResult.data.id
      
      // 2. 分配权限
      const permissionData = {
        roleId: roleId,
        permissionIds: [1, 2, 3, 4], // 权限ID列表
        menuIds: [1, 2, 3]           // 菜单ID列表
      }
      
      const assignResult = await assignPermissions(permissionData)
      if (assignResult.status) {
        ElMessage.success('角色创建并分配权限成功')
      }
    }
  } catch (error) {
    ElMessage.error('操作失败')
  }
}

权限树形选择组件

<template>
  <div class="permission-tree">
    <el-tree
      ref="permissionTree"
      :data="permissionTreeData"
      :props="treeProps"
      show-checkbox
      node-key="id"
      :default-checked-keys="checkedPermissions"
      @check="handlePermissionCheck"
    >
      <template #default="{ node, data }">
        <div class="permission-node">
          <el-icon v-if="data.type === 'menu'">
            <Menu />
          </el-icon>
          <el-icon v-else-if="data.type === 'button'">
            <Operation />
          </el-icon>
          <el-icon v-else>
            <Key />
          </el-icon>
          <span>{{ data.name }}</span>
          <el-tag size="small" :type="getPermissionTypeColor(data.type)">
            {{ getPermissionTypeName(data.type) }}
          </el-tag>
        </div>
      </template>
    </el-tree>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue'
import { getPermissionTree, getRolePermissions } from '@/api/role'

const props = defineProps({
  roleId: {
    type: Number,
    default: null
  }
})

const permissionTree = ref()
const permissionTreeData = ref([])
const checkedPermissions = ref([])

const treeProps = {
  children: 'children',
  label: 'name'
}

const loadPermissionTree = async () => {
  try {
    const result = await getPermissionTree()
    if (result.status) {
      permissionTreeData.value = result.data
    }
  } catch (error) {
    console.error('加载权限树失败:', error)
  }
}

const loadRolePermissions = async () => {
  if (!props.roleId) return
  
  try {
    const result = await getRolePermissions(props.roleId)
    if (result.status) {
      checkedPermissions.value = result.data.permissions.map(p => p.id)
    }
  } catch (error) {
    console.error('加载角色权限失败:', error)
  }
}

const handlePermissionCheck = (data, checked) => {
  // 处理权限选择逻辑
  const checkedKeys = permissionTree.value.getCheckedKeys()
  const halfCheckedKeys = permissionTree.value.getHalfCheckedKeys()
  
  // 发送权限变更事件
  emit('permission-change', {
    checkedKeys,
    halfCheckedKeys
  })
}

const getPermissionTypeColor = (type) => {
  const colors = {
    menu: 'primary',
    button: 'success',
    api: 'warning'
  }
  return colors[type] || 'info'
}

const getPermissionTypeName = (type) => {
  const names = {
    menu: '菜单',
    button: '按钮',
    api: '接口'
  }
  return names[type] || '未知'
}

onMounted(() => {
  loadPermissionTree()
  loadRolePermissions()
})
</script>

角色用户管理

import { getRoleUsers, assignUsers } from '@/api/role'

const manageRoleUsers = {
  // 获取角色用户列表
  async loadUsers(roleId, page = 1) {
    try {
      const result = await getRoleUsers(roleId, { page, pageSize: 20 })
      if (result.status) {
        return result.data
      }
    } catch (error) {
      console.error('获取角色用户失败:', error)
    }
  },
  
  // 添加用户到角色
  async addUsers(roleId, userIds) {
    try {
      const result = await assignUsers({
        roleId,
        userIds,
        action: 'add'
      })
      if (result.status) {
        ElMessage.success('用户添加成功')
        return true
      }
    } catch (error) {
      ElMessage.error('用户添加失败')
    }
    return false
  },
  
  // 从角色移除用户
  async removeUsers(roleId, userIds) {
    try {
      const result = await assignUsers({
        roleId,
        userIds,
        action: 'remove'
      })
      if (result.status) {
        ElMessage.success('用户移除成功')
        return true
      }
    } catch (error) {
      ElMessage.error('用户移除失败')
    }
    return false
  }
}

错误处理

常见错误码

20001: 角色名称已存在
20002: 角色编码已存在
20003: 角色不存在
20004: 系统角色不可删除
20005: 角色下还有用户，不能删除
20006: 权限不足，无法操作此角色

错误处理示例

try {
  const result = await createRole(roleData)
  if (!result.status) {
    switch (result.code) {
      case 20001:
        ElMessage.error('角色名称已存在')
        break
      case 20002:
        ElMessage.error('角色编码已存在')
        break
      default:
        ElMessage.error(result.msg || '操作失败')
    }
    return
  }
  // 处理成功逻辑
} catch (error) {
  console.error('角色操作失败:', error)
  ElMessage.error('网络请求失败')
}

Mock数据

// src/mock/api.js
export const mockRoleList = {
  url: '/role/list',
  method: 'get',
  response: {
    status: true,
    data: {
      list: [
        {
          id: 1,
          name: '超级管理员',
          code: 'SUPER_ADMIN',
          type: 'system',
          level: 1,
          status: 1,
          description: '系统超级管理员，拥有所有权限',
          userCount: 1,
          isDefault: 0,
          isSystem: 1,
          createTime: '2024-01-01 00:00:00'
        },
        {
          id: 2,
          name: '普通用户',
          code: 'USER',
          type: 'system',
          level: 5,
          status: 1,
          description: '普通用户角色',
          userCount: 50,
          isDefault: 1,
          isSystem: 1,
          createTime: '2024-01-01 00:00:00'
        }
      ],
      total: 2
    }
  }
}

注意事项

权限设计: 合理设计权限粒度，避免过于复杂
角色层级: 明确角色层级关系，避免权限混乱
系统角色: 保护系统角色不被误删或误改
权限缓存: 用户权限变更后及时清理缓存
审计日志: 重要权限操作需要记录审计日志

最后更新时间：2025-09-19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

角色管理API文档

概述

API接口

1. 获取角色列表 - getRoleList

2. 获取角色详情 - getRoleDetail

3. 创建角色 - createRole

4. 更新角色 - updateRole

5. 删除角色 - deleteRole

6. 分配权限 - assignPermissions

7. 分配用户 - assignUsers

8. 获取角色权限 - getRolePermissions

9. 获取角色用户 - getRoleUsers

10. 复制角色 - copyRole

11. 批量操作角色 - batchOperateRoles

数据结构

Role - 角色信息

Permission - 权限信息

业务规则

角色层级

权限继承

默认角色

权限验证

使用示例

创建角色并分配权限

权限树形选择组件

角色用户管理

错误处理

常见错误码

错误处理示例

Mock数据

注意事项

FilesExpand file tree

role.md

Latest commit

History

role.md

File metadata and controls

角色管理API文档

概述

API接口

1. 获取角色列表 - getRoleList

2. 获取角色详情 - getRoleDetail

3. 创建角色 - createRole

4. 更新角色 - updateRole

5. 删除角色 - deleteRole

6. 分配权限 - assignPermissions

7. 分配用户 - assignUsers

8. 获取角色权限 - getRolePermissions

9. 获取角色用户 - getRoleUsers

10. 复制角色 - copyRole

11. 批量操作角色 - batchOperateRoles

数据结构

Role - 角色信息

Permission - 权限信息

业务规则

角色层级

权限继承

默认角色

权限验证

使用示例

创建角色并分配权限

权限树形选择组件

角色用户管理

错误处理

常见错误码

错误处理示例

Mock数据

注意事项