一、概述
权限管理是企业知识库系统的核心安全模块,采用 RBAC(基于角色的访问控制)模型,通过"用户 → 角色 → 权限"的三层架构实现精细化的权限控制。
本文将详细介绍如何在 kb-user-auth 服务中实现完整的权限管理功能。
1.1 功能定位
权限管理作为系统安全的基础设施,提供以下核心功能:
| 功能模块 | 说明 | 使用场景 |
|---|---|---|
| 权限CRUD | 创建、更新、删除、查询权限 | 权限基础管理 |
| 树形结构 | 构建父子关系的权限菜单树 | 层级展示 |
| 类型管理 | 支持菜单、按钮、接口三种权限类型 | 精细化权限控制 |
| 分页查询 | 按关键词搜索并分页展示权限列表 | 权限检索 |
| 角色分配 | 将权限分配给角色,角色分配给用户 | 权限授予 |
| 前端校验 | 基于权限码控制页面和按钮的可见性 | UI权限控制 |
1.2 权限模型
系统采用经典的 RBAC 权限模型:

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

二、数据库设计
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 数据关系图

2.5 字段说明
| 字段 | 类型 | 说明 | 必填 | 默认值 |
|---|---|---|---|---|
| id | BIGINT | 权限ID | 是 | 雪花ID |
| parent\_id | BIGINT | 父权限ID(0表示顶级) | 是 | 0 |
| permission\_name | VARCHAR(50) | 权限名称 | 是 | - |
| permission\_code | VARCHAR(100) | 权限编码(唯一标识) | 是 | - |
| permission\_type | TINYINT | 权限类型 | 是 | - |
| menu\_url | VARCHAR(200) | 菜单URL(菜单类型使用) | 否 | NULL |
| api\_url | VARCHAR(500) | 接口URL(接口类型使用) | 否 | NULL |
| method | VARCHAR(10) | 请求方法(GET/POST/PUT/DELETE/*) | 否 | NULL |
| icon | VARCHAR(50) | 图标(Ant Design图标名) | 否 | NULL |
| sort | INT | 排序号 | 是 | 0 |
| status | TINYINT | 状态(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 设计要点
- 继承 BaseEntity:复用基础字段(id、createdAt、updatedAt、createBy、updateBy、deleted)
- permissionType 字段:用整数存储类型,1=菜单、2=按钮、3=接口,方便数据库索引
- menu\_url / api\_url:使用
@TableField显式指定数据库列名,解决驼峰命名与下划线命名的映射 - 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;
}算法特点:

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

七、控制器层
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 调用流程

八、前端页面实现
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 操作按钮
创建权限时根据上下文提供三种入口:

表单字段
创建/编辑权限的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 权限保护流程

9.3 URL 路径直连保护表
以下路径即使直接输入URL也无法访问,除非用户拥有对应权限:
| 路径 | 所需权限 | 说明 |
|---|---|---|
/admin | system:* 任一 | 管理中心首页 |
/admin/users | system:user | 用户管理 |
/admin/roles | system:role | 角色管理 |
/admin/permissions | system:permission | 权限管理 |
/admin/teams | system:team | 团队管理 |
/admin/statistics | system:statistics | 数据统计 |
/admin/review | document:review | 审核管理 |
/admin/settings | system:settings | 系统设置 |
/admin/system-config | system:config | 系统配置 |
/admin/dictionary | system:dictionary | 字典管理 |
/admin/operation-logs | system:operation-log | 操作日志 |
/admin/notification-templates | system:notification-template | 通知模板 |
测试
按顺序启动下面这些微服务:
kb-auth-user
kb-document
kb-gateway
启动前端
cd knowledge-base-frontend
npm run dev
浏览器访问权限管理页面:
http://localhost:3002/admin/permissions

点击文档中心菜单:

可以看到下面的子菜单和权限点。
还可以修改相关内容:

总结
本文详细介绍了权限管理功能的完整实现,涵盖了从数据库设计到前端页面的全栈开发:
已完成功能
| 功能 | 实现方式 | 说明 |
|---|---|---|
| 权限CRUD | Service + Controller | 完整的增删改查 |
| 树形结构 | 递归算法 | 构建父子关系菜单树 |
| 类型管理 | String↔Integer转换 | 支持menu/button/api三种类型 |
| 分页查询 | MyBatis Plus Page | 关键词搜索加分页 |
| 前端页面 | React + Ant Design | 双栏布局的权限管理界面 |
| 权限保护 | hasPermission工具函数 | 菜单和按钮的可见性控制 |
| 路由守卫 | ProtectedRoute | URL直连也会校验权限 |
技术要点
- RBAC 模型:用户 → 角色 → 权限的三层架构,灵活可扩展
- 树形结构构建:递归算法将平铺数据转换为树形结构
- 类型转换:DTO/VO 使用字符串(menu/button/api),Entity 使用整数(1/2/3)
- 逻辑删除:使用
deleted字段实现软删除,数据可追溯 - 雪花ID:使用雪花算法生成分布式唯一ID
- 权限门控:前端通过
hasPermission控制按钮和菜单的渲染
通过本文的学习,你应该能够掌握:
- RBAC 权限模型的设计和实现
- MyBatis Plus 在权限管理中的高级用法
- 前后端权限码的统一管理方案
- RESTful API 的设计规范
- React + Ant Design 的权限管理页面开发
- 前端权限门控(菜单、按钮、路由)的完整实现
祝你开发顺利!