一、概述

权限管理是企业知识库系统的核心安全模块,采用 RBAC(基于角色的访问控制)模型,通过"用户 → 角色 → 权限"的三层架构实现精细化的权限控制。

本文将详细介绍如何在 kb-user-auth 服务中实现完整的权限管理功能。

1.1 功能定位

权限管理作为系统安全的基础设施,提供以下核心功能:

功能模块说明使用场景
权限CRUD创建、更新、删除、查询权限权限基础管理
树形结构构建父子关系的权限菜单树层级展示
类型管理支持菜单、按钮、接口三种权限类型精细化权限控制
分页查询按关键词搜索并分页展示权限列表权限检索
角色分配将权限分配给角色,角色分配给用户权限授予
前端校验基于权限码控制页面和按钮的可见性UI权限控制

1.2 权限模型

系统采用经典的 RBAC 权限模型:

图片.png

1.3 权限分类

类型编码值说明示例
菜单权限1 (menu)控制菜单和页面的可见性system:user、document:list
按钮权限2 (button)控制页面内按钮的可见性和可用性system:permission:create
接口权限3 (api)控制后端API接口的访问api:permission:list

1.4 技术架构

图片.png

二、数据库设计

2.1 权限表结构

创建 kb_permission 表,用于存储系统和用户定义的权限数据:

CREATE TABLE `kb_permission` (
  `id`              BIGINT       NOT NULL COMMENT '权限ID',
  `parent_id`       BIGINT       NOT NULL DEFAULT 0 COMMENT '父权限ID',
  `permission_name` VARCHAR(50)  NOT NULL COMMENT '权限名称',
  `permission_code` VARCHAR(100) NOT NULL COMMENT '权限编码',
  `permission_type` TINYINT      NOT NULL COMMENT '权限类型:1-菜单,2-按钮,3-接口',
  `menu_url`        VARCHAR(200) DEFAULT NULL COMMENT '菜单URL',
  `api_url`         VARCHAR(500) DEFAULT NULL COMMENT '接口URL',
  `method`          VARCHAR(10)  DEFAULT NULL COMMENT '请求方法',
  `icon`            VARCHAR(50)  DEFAULT NULL COMMENT '图标',
  `sort`            INT          NOT NULL DEFAULT 0 COMMENT '排序号',
  `status`          TINYINT      NOT NULL DEFAULT 1 COMMENT '状态:0-禁用,1-启用',
  `created_at`      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `updated_at`      DATETIME     NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `deleted`         TINYINT      NOT NULL DEFAULT 0 COMMENT '删除标识',
  PRIMARY KEY (`id`),
  KEY `idx_parent_id` (`parent_id`),
  KEY `idx_permission_type` (`permission_type`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='权限表';

2.2 角色-权限关联表

CREATE TABLE `kb_role_permission` (
  `id`            BIGINT   NOT NULL COMMENT '主键ID',
  `role_id`       BIGINT   NOT NULL COMMENT '角色ID',
  `permission_id` BIGINT   NOT NULL COMMENT '权限ID',
  `created_at`    DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_role_permission` (`role_id`, `permission_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='角色权限关联表';

2.3 用户-角色关联表

CREATE TABLE `kb_user_role` (
  `id`         BIGINT   NOT NULL COMMENT '主键ID',
  `user_id`    BIGINT   NOT NULL COMMENT '用户ID',
  `role_id`    BIGINT   NOT NULL COMMENT '角色ID',
  `created_at` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `create_by`  BIGINT   DEFAULT NULL COMMENT '创建人',
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_user_role` (`user_id`, `role_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='用户角色关联表';

2.4 数据关系图

图片.png

2.5 字段说明

字段类型说明必填默认值
idBIGINT权限ID是雪花ID
parent\_idBIGINT父权限ID(0表示顶级)是0
permission\_nameVARCHAR(50)权限名称是-
permission\_codeVARCHAR(100)权限编码(唯一标识)是-
permission\_typeTINYINT权限类型是-
menu\_urlVARCHAR(200)菜单URL(菜单类型使用)否NULL
api\_urlVARCHAR(500)接口URL(接口类型使用)否NULL
methodVARCHAR(10)请求方法(GET/POST/PUT/DELETE/*)否NULL
iconVARCHAR(50)图标(Ant Design图标名)否NULL
sortINT排序号是0
statusTINYINT状态(0-禁用,1-启用)是1

2.6 索引设计

  • 主键索引:id - 主键唯一标识
  • 父级索引:idx_parent_id - 加速查询子权限
  • 类型索引:idx_permission_type - 加速按类型筛选

三、实体类设计

3.1 创建 Permission 实体类

在 kb-user-auth 模块中创建 Permission.java:

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/entity/Permission.java

package com.knowledge.base.userauth.entity;

import com.baomidou.mybatisplus.annotation.TableField;
import com.baomidou.mybatisplus.annotation.TableName;
import com.knowledge.base.common.config.BaseEntity;
import lombok.Data;
import lombok.EqualsAndHashCode;

/**
 * 权限实体类
 *
 * <p>按照阿里巴巴Java开发规范设计,存储权限信息</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@EqualsAndHashCode(callSuper = true)
@TableName("kb_permission")
public class Permission extends BaseEntity {

    /**
     * 父权限ID(0表示顶级权限)
     */
    private Long parentId;

    /**
     * 权限名称
     */
    private String permissionName;

    /**
     * 权限编码(唯一标识)
     */
    private String permissionCode;

    /**
     * 权限类型:1-菜单,2-按钮,3-接口
     */
    private Integer permissionType;

    /**
     * 菜单URL(仅菜单类型使用)
     */
    @TableField("menu_url")
    private String menuUrl;

    /**
     * 接口URL(接口类型使用)
     */
    @TableField("api_url")
    private String apiUrl;

    /**
     * 请求方法(GET/POST/PUT/DELETE/*)
     */
    @TableField("method")
    private String method;

    /**
     * 图标
     */
    private String icon;

    /**
     * 排序号
     */
    private Integer sort;

    /**
     * 状态(0-禁用,1-启用)
     */
    private Integer status;
}

3.2 设计要点

  1. 继承 BaseEntity:复用基础字段(id、createdAt、updatedAt、createBy、updateBy、deleted)
  2. permissionType 字段:用整数存储类型,1=菜单、2=按钮、3=接口,方便数据库索引
  3. menu\_url / api\_url:使用 @TableField 显式指定数据库列名,解决驼峰命名与下划线命名的映射
  4. parentId 字段:实现树形结构,0表示顶级权限

四、DTO 和 VO 设计

4.1 创建 PermissionDTO

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/dto/PermissionDTO.java

package com.knowledge.base.userauth.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;

/**
 * 权限DTO
 *
 * <p>用于接收客户端请求,包含参数校验注解</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Schema(description = "权限信息")
public class PermissionDTO {

    @Schema(description = "权限ID(更新时必填)")
    private Long id;

    @NotBlank(message = "权限名称不能为空")
    @Schema(description = "权限名称")
    private String name;

    @NotBlank(message = "权限编码不能为空")
    @Schema(description = "权限编码")
    private String code;

    @Schema(description = "权限类型:menu、button、api")
    private String type;

    @Schema(description = "父权限ID")
    private Long parentId;

    @Schema(description = "菜单URL")
    private String menuUrl;

    @Schema(description = "接口URL")
    private String apiUrl;

    @Schema(description = "请求方法")
    private String method;

    @Schema(description = "权限描述")
    private String description;

    @Schema(description = "排序号")
    private Integer sortOrder;

    @Schema(description = "状态:0-禁用,1-启用")
    private Integer status;
}

4.2 创建 PermissionVO

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/vo/PermissionVO.java

package com.knowledge.base.userauth.vo;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.AllArgsConstructor;
import lombok.Builder;
import lombok.Data;
import lombok.NoArgsConstructor;

import java.io.Serializable;
import java.time.LocalDateTime;
import java.util.List;

/**
 * 权限VO
 *
 * <p>用于返回客户端响应,包含树形结构和扩展字段</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Schema(description = "权限信息")
public class PermissionVO implements Serializable {

    @Schema(description = "权限ID")
    private Long id;

    @Schema(description = "权限名称")
    private String name;

    @Schema(description = "权限编码")
    private String code;

    @Schema(description = "权限类型:menu、button、api")
    private String type;

    @Schema(description = "父权限ID")
    private Long parentId;

    @Schema(description = "菜单URL")
    private String menuUrl;

    @Schema(description = "接口URL")
    private String apiUrl;

    @Schema(description = "请求方法")
    private String method;

    @Schema(description = "权限描述")
    private String description;

    @Schema(description = "排序号")
    private Integer sortOrder;

    @Schema(description = "状态:0-禁用,1-启用")
    private Integer status;

    @Schema(description = "子权限列表(构建树形结构)")
    private List<PermissionVO> children;

    @Schema(description = "创建时间")
    private LocalDateTime createdAt;

    @Schema(description = "更新时间")
    private LocalDateTime updatedAt;
}

4.3 设计说明

DTO vs VO 的区别:

类型用途特点
DTO接收客户端请求字段精简,包含 @NotBlank 参数校验注解,type为String
VO返回客户端响应包含 children 递归字段,支持树形结构,type为String

类型映射逻辑:

  • DTO/VO 的 type 字段使用字符串("menu"、"button"、"api"),方便前端使用
  • Entity 的 permissionType 使用整数(1/2/3),方便数据库索引
  • Service 层负责两者之间的转换

五、数据访问层

5.1 创建 Mapper 接口

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/mapper/PermissionMapper.java

package com.knowledge.base.userauth.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.knowledge.base.userauth.entity.Permission;
import org.apache.ibatis.annotations.Mapper;

/**
 * 权限Mapper接口
 *
 * <p>继承BaseMapper获得通用CRUD方法,无需编写XML</p>
 *
 * @author 苏三
 * @since 1.0.0
 */
@Mapper
public interface PermissionMapper extends BaseMapper<Permission> {

}

5.2 MyBatis Plus 集成

该项目使用 MyBatis Plus,简单的 CRUD 操作无需编写 SQL:

// 自动生成SQL,无需编写XML
permissionMapper.selectById(id);           // 按ID查询
permissionMapper.selectList(wrapper);      // 条件查询列表
permissionMapper.selectPage(page, wrapper); // 分页查询
permissionMapper.insert(permission);       // 插入
permissionMapper.updateById(permission);   // 按ID更新
permissionMapper.deleteById(id);           // 按ID删除

5.3 LambdaQueryWrapper 示例

使用 Lambda 表达式构建类型安全的查询条件:

// 按权限编码精确查询
LambdaQueryWrapper<Permission> wrapper = new LambdaQueryWrapper<>();
wrapper.eq(Permission::getPermissionCode, "system:user");

// 按名称模糊搜索 + 按排序字段升序
LambdaQueryWrapper<Permission> wrapper = new LambdaQueryWrapper<>();
wrapper.like(Permission::getPermissionName, "用户")
       .orderByAsc(Permission::getSort);

六、业务逻辑层

6.1 创建 Service 接口

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/service/PermissionService.java

package com.knowledge.base.userauth.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.knowledge.base.userauth.dto.PermissionDTO;
import com.knowledge.base.userauth.vo.PermissionVO;

import java.util.List;

/**
 * 权限Service接口
 *
 * @author 苏三
 * @since 1.0.0
 */
public interface PermissionService {

    /**
     * 创建权限
     */
    Long createPermission(PermissionDTO permissionDTO);

    /**
     * 更新权限
     */
    Boolean updatePermission(PermissionDTO permissionDTO);

    /**
     * 删除权限
     */
    Boolean deletePermission(Long permissionId);

    /**
     * 根据ID查询权限
     */
    PermissionVO getPermissionById(Long permissionId);

    /**
     * 根据父权限ID查询子权限
     */
    List<PermissionVO> getPermissionsByParentId(Long parentId);

    /**
     * 分页查询权限
     */
    IPage<PermissionVO> pagePermissions(Long current, Long size, String keyword);

    /**
     * 获取权限树
     */
    List<PermissionVO> getPermissionTree();

    /**
     * 获取所有启用的权限
     */
    List<PermissionVO> getAllPermissions();
}

6.2 创建 Service 实现类

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/service/impl/PermissionServiceImpl.java

package com.knowledge.base.userauth.service.impl;

import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
import com.knowledge.base.common.exception.BusinessException;
import com.knowledge.base.common.utils.SnowflakeIdGenerator;
import com.knowledge.base.userauth.dto.PermissionDTO;
import com.knowledge.base.userauth.entity.Permission;
import com.knowledge.base.userauth.mapper.PermissionMapper;
import com.knowledge.base.userauth.service.PermissionService;
import com.knowledge.base.userauth.vo.PermissionVO;
import jakarta.annotation.Resource;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
import org.springframework.util.StringUtils;

import java.util.ArrayList;
import java.util.List;
import java.util.stream.Collectors;

/**
 * 权限Service实现类
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@Service
public class PermissionServiceImpl
        extends ServiceImpl<PermissionMapper, Permission>
        implements PermissionService {

    @Resource
    private PermissionMapper permissionMapper;

    // ==================== 创建权限 ====================

    @Override
    @Transactional(rollbackFor = Exception.class)
    public Long createPermission(PermissionDTO permissionDTO) {
        log.info("创建权限:permissionName={}", permissionDTO.getName());

        // 1. 检查权限编码是否已存在
        if (StringUtils.hasText(permissionDTO.getCode())) {
            Permission existPermission = permissionMapper.selectOne(
                new LambdaQueryWrapper<Permission>()
                    .eq(Permission::getPermissionCode, permissionDTO.getCode())
            );
            if (existPermission != null) {
                throw new BusinessException("权限编码已存在");
            }
        }

        // 2. 检查父权限是否存在
        if (permissionDTO.getParentId() != null
                && permissionDTO.getParentId() > 0) {
            Permission parentPermission = permissionMapper
                .selectById(permissionDTO.getParentId());
            if (parentPermission == null) {
                throw new BusinessException("父权限不存在");
            }
        }

        // 3. 构建权限实体
        Permission permission = new Permission();
        permission.setId(SnowflakeIdGenerator.getInstance().nextId());
        permission.setParentId(
            permissionDTO.getParentId() != null
                ? permissionDTO.getParentId() : 0L);
        permission.setPermissionName(permissionDTO.getName());
        permission.setPermissionCode(permissionDTO.getCode());
        // 类型转换:String → Integer
        permission.setPermissionType(
            getPermissionTypeValue(permissionDTO.getType()));
        permission.setMenuUrl(permissionDTO.getMenuUrl());
        permission.setApiUrl(permissionDTO.getApiUrl());
        permission.setMethod(permissionDTO.getMethod());
        permission.setSort(
            permissionDTO.getSortOrder() != null
                ? permissionDTO.getSortOrder() : 0);
        permission.setStatus(
            permissionDTO.getStatus() != null
                ? permissionDTO.getStatus() : 1);

        // 4. 保存权限
        int count = permissionMapper.insert(permission);
        if (count <= 0) {
            throw new BusinessException("创建权限失败");
        }

        return permission.getId();
    }

    // ==================== 更新权限 ====================

    @Override
    @Transactional(rollbackFor = Exception.class)
    public Boolean updatePermission(PermissionDTO permissionDTO) {
        log.info("更新权限:permissionId={}", permissionDTO.getId());

        // 1. 参数校验
        if (permissionDTO.getId() == null) {
            throw new BusinessException("权限ID不能为空");
        }

        // 2. 检查权限是否存在
        Permission existPermission = permissionMapper
            .selectById(permissionDTO.getId());
        if (existPermission == null) {
            throw new BusinessException("权限不存在");
        }

        // 3. 检查编码唯一性(排除自身)
        if (StringUtils.hasText(permissionDTO.getCode())
                && !permissionDTO.getCode()
                    .equals(existPermission.getPermissionCode())) {
            Permission dup = permissionMapper.selectOne(
                new LambdaQueryWrapper<Permission>()
                    .eq(Permission::getPermissionCode,
                        permissionDTO.getCode())
            );
            if (dup != null
                    && !dup.getId().equals(permissionDTO.getId())) {
                throw new BusinessException("权限编码已被使用");
            }
        }

        // 4. 检查父权限(防止自引用)
        if (permissionDTO.getParentId() != null
                && permissionDTO.getParentId() > 0) {
            if (permissionDTO.getParentId()
                    .equals(permissionDTO.getId())) {
                throw new BusinessException("父权限不能是自己");
            }
            Permission parent = permissionMapper
                .selectById(permissionDTO.getParentId());
            if (parent == null) {
                throw new BusinessException("父权限不存在");
            }
        }

        // 5. 构建更新实体并保存
        Permission permission = new Permission();
        permission.setId(permissionDTO.getId());
        permission.setParentId(
            permissionDTO.getParentId() != null
                ? permissionDTO.getParentId() : 0L);
        permission.setPermissionName(permissionDTO.getName());
        permission.setPermissionCode(permissionDTO.getCode());
        if (StringUtils.hasText(permissionDTO.getType())) {
            permission.setPermissionType(
                getPermissionTypeValue(permissionDTO.getType()));
        }
        permission.setMenuUrl(permissionDTO.getMenuUrl());
        permission.setApiUrl(permissionDTO.getApiUrl());
        permission.setMethod(permissionDTO.getMethod());
        permission.setSort(permissionDTO.getSortOrder());
        permission.setStatus(permissionDTO.getStatus());

        int count = permissionMapper.updateById(permission);
        return count > 0;
    }

    // ==================== 删除权限 ====================

    @Override
    @Transactional(rollbackFor = Exception.class)
    public Boolean deletePermission(Long permissionId) {
        log.info("删除权限:permissionId={}", permissionId);

        if (permissionId == null) {
            throw new BusinessException("权限ID不能为空");
        }

        // 1. 检查权限是否存在
        Permission permission = permissionMapper
            .selectById(permissionId);
        if (permission == null) {
            throw new BusinessException("权限不存在");
        }

        // 2. 防止删除有子权限的父权限
        Long childCount = permissionMapper.selectCount(
            new LambdaQueryWrapper<Permission>()
                .eq(Permission::getParentId, permissionId)
        );
        if (childCount > 0) {
            throw new BusinessException(
                "该权限下有子权限,不能删除");
        }

        // 3. 逻辑删除
        int count = permissionMapper.deleteById(permissionId);
        return count > 0;
    }

    // ==================== 查询权限 ====================

    @Override
    public PermissionVO getPermissionById(Long permissionId) {
        if (permissionId == null) {
            throw new BusinessException("权限ID不能为空");
        }

        Permission permission = permissionMapper
            .selectById(permissionId);
        if (permission == null) {
            throw new BusinessException("权限不存在");
        }

        return convertToVO(permission);
    }

    @Override
    public List<PermissionVO> getPermissionsByParentId(Long parentId) {
        Long targetParentId = parentId != null ? parentId : 0L;
        List<Permission> permissions = permissionMapper.selectList(
            new LambdaQueryWrapper<Permission>()
                .eq(Permission::getParentId, targetParentId)
                .orderByAsc(Permission::getSort)
        );

        return permissions.stream()
                .map(this::convertToVO)
                .collect(Collectors.toList());
    }

    @Override
    public IPage<PermissionVO> pagePermissions(
            Long current, Long size, String keyword) {
        LambdaQueryWrapper<Permission> wrapper =
            new LambdaQueryWrapper<>();
        if (StringUtils.hasText(keyword)) {
            wrapper.and(w -> w
                .like(Permission::getPermissionName, keyword)
                .or()
                .like(Permission::getPermissionCode, keyword)
            );
        }
        wrapper.orderByAsc(Permission::getSort);

        Page<Permission> page = new Page<>(current, size);
        IPage<Permission> result = permissionMapper
            .selectPage(page, wrapper);

        return result.convert(this::convertToVO);
    }

    @Override
    public List<PermissionVO> getPermissionTree() {
        // 查询所有权限
        List<Permission> allPermissions = permissionMapper.selectList(
            new LambdaQueryWrapper<Permission>()
                .orderByAsc(Permission::getSort)
        );

        // 转换并构建树形结构
        List<PermissionVO> vos = allPermissions.stream()
                .map(this::convertToVO)
                .collect(Collectors.toList());

        return buildPermissionTree(vos, 0L);
    }

    @Override
    public List<PermissionVO> getAllPermissions() {
        List<Permission> permissions = permissionMapper.selectList(
            new LambdaQueryWrapper<Permission>()
                .eq(Permission::getStatus, 1)
                .orderByAsc(Permission::getSort)
        );

        return permissions.stream()
                .map(this::convertToVO)
                .collect(Collectors.toList());
    }

    // ==================== 工具方法 ====================

    /**
     * Entity → VO 转换
     */
    private PermissionVO convertToVO(Permission permission) {
        return PermissionVO.builder()
                .id(permission.getId())
                .name(permission.getPermissionName())
                .code(permission.getPermissionCode())
                .type(getPermissionTypeString(
                    permission.getPermissionType()))
                .parentId(permission.getParentId())
                .menuUrl(permission.getMenuUrl())
                .apiUrl(permission.getApiUrl())
                .method(permission.getMethod())
                .sortOrder(permission.getSort())
                .status(permission.getStatus())
                .createdAt(permission.getCreatedAt())
                .updatedAt(permission.getUpdatedAt())
                .build();
    }

    /**
     * 递归构建权限树
     */
    private List<PermissionVO> buildPermissionTree(
            List<PermissionVO> permissions, Long parentId) {
        List<PermissionVO> tree = new ArrayList<>();

        for (PermissionVO permission : permissions) {
            if (parentId.equals(permission.getParentId())) {
                permission.setChildren(
                    buildPermissionTree(permissions,
                        permission.getId()));
                tree.add(permission);
            }
        }

        return tree;
    }

    /**
     * 类型字符串 → 整数(用于存储到数据库)
     */
    private Integer getPermissionTypeValue(String type) {
        if (type == null) {
            return 1;
        }
        return switch (type.trim().toLowerCase()) {
            case "2", "button" -> 2;
            case "3", "api" -> 3;
            default -> 1; // "1", "menu"
        };
    }

    /**
     * 类型整数 → 字符串(用于返回给前端)
     */
    private String getPermissionTypeString(Integer type) {
        if (type == null) {
            return "menu";
        }
        return switch (type) {
            case 2 -> "button";
            case 3 -> "api";
            default -> "menu";
        };
    }
}

6.3 核心算法说明

6.3.1 树形结构构建

private List<PermissionVO> buildPermissionTree(
        List<PermissionVO> permissions, Long parentId) {
    List<PermissionVO> tree = new ArrayList<>();

    for (PermissionVO permission : permissions) {
        if (parentId.equals(permission.getParentId())) {
            // 递归查找子权限
            permission.setChildren(
                buildPermissionTree(permissions, permission.getId()));
            tree.add(permission);
        }
    }
    return tree;
}

算法特点:

图片.png

  • 时间复杂度:O(n²),n为节点数量
  • 空间复杂度:O(n),递归栈深度
  • 适用场景:中小型权限树(< 500个节点)

6.3.2 类型转换逻辑

图片.png

七、控制器层

7.1 创建 PermissionController

文件路径: kb-user-auth/src/main/java/com/knowledge/base/userauth/controller/PermissionController.java

package com.knowledge.base.userauth.controller;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.knowledge.base.common.result.Result;
import com.knowledge.base.userauth.dto.PermissionDTO;
import com.knowledge.base.userauth.service.PermissionService;
import com.knowledge.base.userauth.vo.PermissionVO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import jakarta.annotation.Resource;
import jakarta.validation.Valid;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.annotation.*;

import java.util.List;

/**
 * 权限管理Controller
 *
 * @author 苏三
 * @since 1.0.0
 */
@Slf4j
@RestController
@RequestMapping("/permissions")
@Tag(name = "权限管理", description = "权限信息管理接口")
public class PermissionController {

    @Resource
    private PermissionService permissionService;

    /**
     * 创建权限
     */
    @PostMapping
    @Operation(summary = "创建权限")
    public Result<Long> createPermission(
            @Valid @RequestBody PermissionDTO permissionDTO) {
        Long permissionId = permissionService
            .createPermission(permissionDTO);
        return Result.success("创建权限成功", permissionId);
    }

    /**
     * 更新权限
     */
    @PutMapping
    @Operation(summary = "更新权限")
    public Result<Boolean> updatePermission(
            @Valid @RequestBody PermissionDTO permissionDTO) {
        Boolean success = permissionService
            .updatePermission(permissionDTO);
        return Result.success("更新权限成功", success);
    }

    /**
     * 删除权限
     */
    @DeleteMapping("/{permissionId}")
    @Operation(summary = "删除权限")
    public Result<Boolean> deletePermission(
            @PathVariable Long permissionId) {
        Boolean success = permissionService
            .deletePermission(permissionId);
        return Result.success("删除权限成功", success);
    }

    /**
     * 根据ID查询权限
     */
    @GetMapping("/{permissionId}")
    @Operation(summary = "查询权限详情")
    public Result<PermissionVO> getPermissionById(
            @PathVariable Long permissionId) {
        PermissionVO vo = permissionService
            .getPermissionById(permissionId);
        return Result.success(vo);
    }

    /**
     * 查询直属子权限
     */
    @GetMapping("/{permissionId}/children")
    @Operation(summary = "查询下级资源")
    public Result<List<PermissionVO>> getPermissionsByParentId(
            @PathVariable Long permissionId) {
        List<PermissionVO> permissions = permissionService
            .getPermissionsByParentId(permissionId);
        return Result.success(permissions);
    }

    /**
     * 分页查询权限
     */
    @GetMapping("/page")
    @Operation(summary = "分页查询权限")
    public Result<IPage<PermissionVO>> pagePermissions(
            @RequestParam(defaultValue = "1") Long current,
            @RequestParam(defaultValue = "10") Long size,
            @RequestParam(required = false) String keyword) {
        IPage<PermissionVO> page = permissionService
            .pagePermissions(current, size, keyword);
        return Result.success(page);
    }

    /**
     * 获取权限树
     */
    @GetMapping("/tree")
    @Operation(summary = "获取权限树")
    public Result<List<PermissionVO>> getPermissionTree() {
        List<PermissionVO> tree = permissionService
            .getPermissionTree();
        return Result.success(tree);
    }

    /**
     * 获取所有启用的权限(扁平列表)
     */
    @GetMapping("/list")
    @Operation(summary = "获取所有权限")
    public Result<List<PermissionVO>> getAllPermissions() {
        List<PermissionVO> permissions = permissionService
            .getAllPermissions();
        return Result.success(permissions);
    }
}

7.2 RESTful API 设计

方法路径说明请求体/参数
POST/permissions创建权限PermissionDTO
PUT/permissions更新权限PermissionDTO
DELETE/permissions/{id}删除权限permissionId
GET/permissions/{id}查询权限详情permissionId
GET/permissions/{id}/children查询子权限permissionId
GET/permissions/page分页查询current, size, keyword
GET/permissions/tree获取权限树-
GET/permissions/list获取所有权限-

7.3 API 调用流程

图片.png


八、前端页面实现

8.1 创建权限管理页面

文件路径: knowledge-base-frontend/src/pages/admin/PermissionsPage.tsx

权限管理页面采用左右两栏布局:

  • 左栏(25%):可搜索的权限菜单树,显示完整的菜单层级结构
  • 右栏(75%):选中菜单的详情 + 其下的权限资源列表(支持类型过滤和CRUD)

核心State设计

// 权限树数据
const [permissionTree, setPermissionTree] = useState<PermissionTreeNode[]>([]);
// 当前选中的菜单ID
const [selectedMenuId, setSelectedMenuId] = useState<string | number | null>(null);
// 选中菜单的详情
const [currentMenu, setCurrentMenu] = useState<PermissionTreeNode | null>(null);
// 选中菜单下的子资源
const [currentResources, setCurrentResources] = useState<PermissionTreeNode[]>([]);
// 正在编辑的权限
const [editingPermission, setEditingPermission] = useState<PermissionTreeNode | null>(null);
// 资源类型筛选
const [resourceFilterType, setResourceFilterType] = useState<'all' | 'menu' | 'button' | 'api'>('all');

CRUD 操作按钮

创建权限时根据上下文提供三种入口:

图片.png

表单字段

创建/编辑权限的Modal表单字段:

字段组件必填说明
资源名称Input是权限的中文名称
权限编码Input是唯一标识,格式 [a-z:_]+,编辑时禁用
资源类型Select是菜单 / 按钮权限 / 接口权限
所属父菜单TreeSelect否选择父级菜单,"顶级菜单"表示一级菜单
菜单路径Input条件类型为"菜单"时显示,对应前端路由
接口地址Input条件类型为"接口"时显示
请求方法Select条件类型为"接口"时显示,GET/POST/PUT/DELETE/PATCH/*
排序号InputNumber否控制同级菜单的排序
状态Select否启用/禁用
描述TextArea否权限的备注说明

权限门控

按钮的可见性由权限码控制:

const canCreatePermission = hasPermission(user, PERMISSIONS.systemPermission)
  || hasPermission(user, PERMISSIONS.systemPermissionCreate);
const canEditPermission = hasPermission(user, PERMISSIONS.systemPermission)
  || hasPermission(user, PERMISSIONS.systemPermissionEdit);
const canDeletePermission = hasPermission(user, PERMISSIONS.systemPermission)
  || hasPermission(user, PERMISSIONS.systemPermissionDelete);

创建按钮、编辑按钮和删除按钮根据这些标志条件渲染。

8.2 前端权限工具函数

文件路径: knowledge-base-frontend/src/utils/permission.ts

// 权限码常量
export const PERMISSIONS = {
  documentList:           'document:list',
  documentCreate:         'document:create',
  documentEdit:           'document:edit',
  documentDelete:         'document:delete',
  documentReview:         'document:review',
  documentCategory:       'document:category',
  documentCategoryQuery:  'document:category:query',
  documentTag:            'document:tag',
  documentVersion:        'document:version',
  systemUser:             'system:user',
  systemRole:             'system:role',
  systemPermission:       'system:permission',
  systemPermissionCreate: 'system:permission:create',
  systemPermissionEdit:   'system:permission:edit',
  systemPermissionDelete: 'system:permission:delete',
  systemTeam:             'system:team',
  systemStatistics:       'system:statistics',
  systemSettings:         'system:settings',
} as const;

// 超级管理员角色集合
const SUPER_ADMIN_ROLES = new Set(['ROLE_SUPER_ADMIN', 'SUPER_ADMIN']);

// 检查用户是否为超级管理员
export function isSuperAdmin(user: User | null): boolean {
  if (!user) return false;
  const roles = getUserRoles(user);
  return roles.some(role => SUPER_ADMIN_ROLES.has(role.toUpperCase()));
}

// 检查单个权限(超级管理员始终返回true)
export function hasPermission(
  user: User | null,
  permission: string
): boolean {
  if (!user) return false;
  if (isSuperAdmin(user)) return true;
  const perms = getUserPermissions(user);
  return perms.includes(permission);
}

// 检查是否拥有任意一个权限
export function hasAnyPermission(
  user: User | null,
  permissions: string[]
): boolean {
  if (!user) return false;
  if (isSuperAdmin(user)) return true;
  const perms = new Set(getUserPermissions(user));
  return permissions.some(p => perms.has(p));
}

// 获取用户的所有权限码
export function getUserPermissions(user: User): string[] {
  return user.permissions || [];
}

8.3 前端 API 服务

文件路径: knowledge-base-frontend/src/services/permission.service.ts

import request from '@/utils/request';

const BASE_URL = '/auth/permissions';

export const permissionService = {
  // 获取权限树
  getPermissionTree: () =>
    request.get(`${BASE_URL}/tree`),

  // 获取所有权限(扁平列表)
  getAllPermissions: () =>
    request.get(`${BASE_URL}/list`),

  // 根据ID查询权限
  getPermissionById: (id: string | number) =>
    request.get(`${BASE_URL}/${id}`),

  // 查询子权限
  getPermissionsByParentId: (id: string | number) =>
    request.get(`${BASE_URL}/${id}/children`),

  // 分页查询
  pagePermissions: (params: {
    current?: number;
    size?: number;
    keyword?: string;
  }) => request.get(`${BASE_URL}/page`, { params }),

  // 创建权限
  createPermission: (data: Record<string, unknown>) =>
    request.post(BASE_URL, data),

  // 更新权限
  updatePermission: (data: Record<string, unknown>) =>
    request.put(BASE_URL, data),

  // 删除权限
  deletePermission: (id: string | number) =>
    request.delete(`${BASE_URL}/${id}`),
};

九、路由和权限保护

9.1 注册路由

在路由配置中添加权限管理页面的路由,并使用 ProtectedRoute 包裹:

{
  path: 'admin/permissions',
  element: (
    <ProtectedRoute
      requireAdmin
      requiredPermissions={[PERMISSIONS.systemPermission]}
    >
      <Suspense fallback={<LoadingFallback />}>
        <PermissionsPage />
      </Suspense>
    </ProtectedRoute>
  ),
}

9.2 权限保护流程

图片.png

9.3 URL 路径直连保护表

以下路径即使直接输入URL也无法访问,除非用户拥有对应权限:

路径所需权限说明
/adminsystem:* 任一管理中心首页
/admin/userssystem:user用户管理
/admin/rolessystem:role角色管理
/admin/permissionssystem:permission权限管理
/admin/teamssystem:team团队管理
/admin/statisticssystem:statistics数据统计
/admin/reviewdocument:review审核管理
/admin/settingssystem:settings系统设置
/admin/system-configsystem:config系统配置
/admin/dictionarysystem:dictionary字典管理
/admin/operation-logssystem:operation-log操作日志
/admin/notification-templatessystem:notification-template通知模板

测试

按顺序启动下面这些微服务:

kb-auth-user

kb-document

kb-gateway

启动前端

cd knowledge-base-frontend

npm run dev

浏览器访问权限管理页面:

http://localhost:3002/admin/permissions

图片.png

点击文档中心菜单:

图片.png

可以看到下面的子菜单和权限点。

还可以修改相关内容:

图片.png

总结

本文详细介绍了权限管理功能的完整实现,涵盖了从数据库设计到前端页面的全栈开发:

已完成功能

功能实现方式说明
权限CRUDService + Controller完整的增删改查
树形结构递归算法构建父子关系菜单树
类型管理String↔Integer转换支持menu/button/api三种类型
分页查询MyBatis Plus Page关键词搜索加分页
前端页面React + Ant Design双栏布局的权限管理界面
权限保护hasPermission工具函数菜单和按钮的可见性控制
路由守卫ProtectedRouteURL直连也会校验权限

技术要点

  1. RBAC 模型:用户 → 角色 → 权限的三层架构,灵活可扩展
  2. 树形结构构建:递归算法将平铺数据转换为树形结构
  3. 类型转换:DTO/VO 使用字符串(menu/button/api),Entity 使用整数(1/2/3)
  4. 逻辑删除:使用 deleted 字段实现软删除,数据可追溯
  5. 雪花ID:使用雪花算法生成分布式唯一ID
  6. 权限门控:前端通过 hasPermission 控制按钮和菜单的渲染

通过本文的学习,你应该能够掌握:

  • RBAC 权限模型的设计和实现
  • MyBatis Plus 在权限管理中的高级用法
  • 前后端权限码的统一管理方案
  • RESTful API 的设计规范
  • React + Ant Design 的权限管理页面开发
  • 前端权限门控(菜单、按钮、路由)的完整实现

祝你开发顺利!

最后修改:2026 年 10 月 24 日
如果觉得我的文章对你有用,请随意赞赏