简介这是一套基于SpringBoot与Vue.js开发的前后端分离式用户权限管理系统面向计算机专业本科生毕业设计、课程设计及期末大作业需求解决典型Web应用中用户认证、角色管理与细粒度权限控制等核心问题。资源包共64个文件含55个Java后端业务与配置类、2个properties配置文件、1个SQL建表脚本、1个XML依赖配置、1个README.md项目说明文档以及mvnw构建脚本和.gitignore等工程基础设施文件整体仅90KB轻量易部署。已有25人学习下载适合初学者快速理解SpringBootVue全栈开发流程。读者可直接运行调试完整权限模块掌握JWT鉴权实现、RBAC模型落地、前后端跨域联调、Maven标准化构建及Git工程管理等关键实践环节目录结构规范包含标准src/main/java与src/main/resources分层便于教学复现与二次开发。1. 为什么一个“基于SpringBoot的用户权限管理系统”不是模板套用题而是后端工程能力的试金石很多刚跑通spring-boot-starter-web的开发者看到“基于SpringBoot的用户权限管理系统”这个标题第一反应是不就是加个登录页、查数据库、跳角色页面但真实企业级权限系统里RBAC模型落地时菜单动态加载卡在前端路由同步、按钮级权限校验被绕过、多租户场景下数据隔离失效、JWT刷新令牌并发冲突——这些都不是PreAuthorize(hasRole(ADMIN))一行注解能兜住的。它考验的是你对 Spring Security 认证流程的穿透理解、对 MyBatis-Plus 多表关联查询的 SQL 控制力、对 Spring Boot 自动装配机制的调试能力以及对前后端分离架构中权限边界划分的工程判断。适合正在从单体 CRUD 迈向中型业务系统开发的 Java 工程师尤其适用于需要快速交付可审计、可扩展、可二次集成的权限底座的团队。这不是练手 Demo而是你接手真实 SaaS 管理后台前必须亲手拆解、重装、压测过的最小可行权限内核。2. 从零构建权限模型RBAC 四要素在 Spring Boot 中的实体映射与关系约束2.1 为什么不用 ACL 或 ABACRBAC 是当前最平衡的选型依据在中小规模业务系统中ACL访问控制列表会导致权限数据爆炸式增长每新增一个资源就要维护一条规则ABAC属性基访问控制虽灵活但策略引擎复杂度高Java 生态成熟方案少且规则调试成本远超团队接受阈值。而 RBAC基于角色的访问控制通过「用户-角色-权限-资源」四层解耦天然适配 Spring Security 的Authentication→GrantedAuthority→FilterSecurityInterceptor链路。更重要的是它能直接对应企业组织架构一个用户可属多个角色如“运维审计”一个角色可绑多组权限如“订单管理”含“查询/导出/审核”权限粒度可精确到接口级/api/order/export或按钮级btn:order:cancel。这种结构让权限变更可审计、可回滚、可批量操作是金融、政务、ERP 类系统上线前的合规硬性要求。2.2 四张核心表设计字段命名直连 Spring Security 接口契约Spring Security 不强制依赖特定表结构但若字段名与UserDetails、GrantedAuthority接口约定一致可省去大量UserDetailsService转换逻辑。以下是生产环境验证过的最小可行表结构MySQL 8.0表名关键字段说明Spring Security 映射点sys_userid,username,password,status,create_time用户主表status必须支持禁用非物理删除UserDetails.getUsername()/isAccountNonExpired()sys_roleid,code,name,remark角色编码如ROLE_ADMIN需带ROLE_前缀否则hasRole()失效GrantedAuthority.getAuthority()sys_permissionid,code,name,url,method,typeMENU/BUTTON/APIcode为权限标识符如sys:user:listurlmethod构成接口级权限唯一键PreAuthorize(hasAuthority(sys:user:list))sys_user_role/sys_role_permission联合主键(user_id, role_id)/(role_id, perm_id)中间表禁止使用自增 ID避免脏数据导致权限漏绑UserDetails.getAuthorities()返回集合来源提示sys_permission.type字段必须区分MENU前端菜单、BUTTON按钮显隐、API后端接口拦截这是实现精细化权限控制的前提。若混用会导致前端菜单渲染和后端鉴权逻辑耦合后期无法独立迭代。2.3 MyBatis-Plus 实体类与 Mapper 层关键代码规避 N1 查询与循环依赖// SysUser.java TableName(sys_user) public class SysUser extends ModelSysUser { TableId(type IdType.ASSIGN_ID) private Long id; private String username; private String password; // 存 BCrypt 加密后密文 private Integer status; // 0-禁用 1-启用 // ... getter/setter } // SysRole.java TableName(sys_role) public class SysRole extends ModelSysRole { TableId(type IdType.ASSIGN_ID) private Long id; private String code; // 必须以 ROLE_ 开头 private String name; // ... getter/setter } // 权限查询一次查出用户所有权限含角色继承 Select(SELECT p.* FROM sys_permission p JOIN sys_role_permission rp ON p.id rp.perm_id JOIN sys_user_role ur ON rp.role_id ur.role_id WHERE ur.user_id #{userId} AND p.status 1) ListSysPermission selectPermissionsByUserId(Param(userId) Long userId);2.3.1 为什么不用TableField(exist false)ListRole做嵌套MyBatis-Plus 的TableField(exist false)在多表关联时极易触发 N1 查询先查用户再为每个用户查角色再为每个角色查权限。当用户量达千级接口响应时间从 50ms 暴涨至 2s。正确做法是用单条 SQL 扁平化查询返回SysPermission列表由 Service 层按type分组归类菜单树、按钮码、API 权限集再注入到UserDetails实现类中。2.3.2UserDetails实现类必须重写getAuthorities()的深层原因Service public class UserDetailsServiceImpl implements UserDetailsService { Override public UserDetails loadUserByUsername(String username) throws UsernameNotFoundException { SysUser user userMapper.selectOne(new QueryWrapperSysUser().eq(username, username)); if (user null || user.getStatus() ! 1) { throw new UsernameNotFoundException(用户不存在或已禁用); } // 关键此处必须将权限转为 GrantedAuthority 集合 ListSimpleGrantedAuthority authorities permissionMapper .selectPermissionsByUserId(user.getId()) .stream() .map(p - new SimpleGrantedAuthority(p.getCode())) // code 即权限标识符 .collect(Collectors.toList()); return new org.springframework.security.core.userdetails.User( user.getUsername(), user.getPassword(), user.getStatus() 1, // accountNonExpired true, // credentialsNonExpired true, // accountNonLocked true, // enabled authorities ); } }注意SimpleGrantedAuthority构造参数必须是权限code如sys:user:add而非name如“新增用户”。Spring Security 的PreAuthorize和hasAuthority()方法只认getAuthority()返回值中文名仅用于前端展示。3. Spring Security 深度定制从 URL 拦截到按钮级权限的三层校验链3.1 WebSecurityConfigurerAdapter 已废弃用 SecurityFilterChain 替代的必调参数Spring Boot 2.7 强制使用函数式配置WebSecurityConfigurerAdapter被标记为Deprecated。以下是最小可用且生产就绪的SecurityFilterChain配置Configuration EnableWebSecurity public class SecurityConfig { Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf().disable() // 前后端分离项目通常禁用 CSRF由 JWT 令牌保障 .sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS) // 无状态 .and() .authorizeHttpRequests(authz - authz .requestMatchers(/login, /logout, /favicon.ico, /actuator/**).permitAll() // 放行路径 .requestMatchers(HttpMethod.GET, /api/public/**).permitAll() // 公共接口 .requestMatchers(HttpMethod.POST, /api/auth/login).permitAll() .requestMatchers(/api/**).authenticated() // 其他 API 需认证 .anyRequest().authenticated() ) .exceptionHandling(e - e .authenticationEntryPoint(new JwtAuthenticationEntryPoint()) // 未登录处理 .accessDeniedHandler(new JwtAccessDeniedHandler()) // 无权限处理 ) .addFilterBefore(jwtAuthenticationFilter(), UsernamePasswordAuthenticationFilter.class); return http.build(); } Bean public JwtAuthenticationFilter jwtAuthenticationFilter() { return new JwtAuthenticationFilter(); } }3.1.1SessionCreationPolicy.STATELESS的真实含义与陷阱设为STATELESS并非简单“不创建 session”而是彻底禁用HttpSession机制Spring Security 不再调用request.getSession()SecurityContext也不存入 session。这意味着所有认证信息必须通过请求头如Authorization: Bearer xxx传递SecurityContextHolder.getContext().getAuthentication()返回的对象生命周期仅限本次请求若误在 Filter 中调用request.getSession()会抛IllegalStateException。提示/actuator/**放行是必须的否则健康检查探针失败导致 K8s Pod 反复重启。但生产环境应配合management.endpoints.web.exposure.includehealth,info严格限制暴露端点。3.2 JWT 认证过滤器解析、校验、注入 SecurityContext 的三步原子操作Component public class JwtAuthenticationFilter extends OncePerRequestFilter { Override protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException { String token resolveToken(request); if (token ! null jwtUtil.validateToken(token)) { String username jwtUtil.getUsernameFromToken(token); UserDetails userDetails userDetailsService.loadUserByUsername(username); UsernamePasswordAuthenticationToken authentication new UsernamePasswordAuthenticationToken( userDetails, null, userDetails.getAuthorities()); authentication.setDetails(new WebAuthenticationDetailsSource().buildDetails(request)); SecurityContextHolder.getContext().setAuthentication(authentication); } filterChain.doFilter(request, response); } private String resolveToken(HttpServletRequest request) { String bearerToken request.getHeader(Authorization); if (bearerToken ! null bearerToken.startsWith(Bearer )) { return bearerToken.substring(7); // 去掉 Bearer 前缀 } return null; } }3.2.1jwtUtil.validateToken(token)必须包含的 4 项校验签名有效性用 HS512 密钥验签防止 token 被篡改过期时间exp字段必须大于当前时间System.currentTimeMillis()生效时间nbfNot Before字段必须小于等于当前时间防止提前使用黑名单校验检查 Redis 中是否存在该 token登出时存入TTLtoken剩余有效期避免 token 泄露后无法主动作废。// 示例Redis 黑名单校验实际需加 try-catch 和空值判断 String blackToken redisTemplate.opsForValue().get(blacklist: token); if (blackToken ! null 1.equals(blackToken)) { throw new TokenBlacklistException(Token 已登出或已被撤销); }3.3 按钮级权限控制前端传参 后端校验的双重保险实现单纯依赖前端隐藏按钮存在严重风险攻击者可直接构造/api/user/delete?id123请求。必须在 Controller 层做二次校验RestController RequestMapping(/api/user) public class UserController { DeleteMapping(/{id}) PreAuthorize(hasAuthority(sys:user:delete)) // 接口级权限 public Result delete(PathVariable Long id) { // 按钮级权限校验确认当前用户是否有删除指定用户的权限 // 例如普通管理员只能删同部门用户超级管理员可删全部 SysUser currentUser getCurrentUser(); SysUser targetUser userMapper.selectById(id); if (!canDeleteUser(currentUser, targetUser)) { throw new AccessDeniedException(无权删除该用户); } userMapper.deleteById(id); return Result.success(); } private boolean canDeleteUser(SysUser current, SysUser target) { // 规则1超级管理员放行 if (current.getRoles().contains(ROLE_SUPER_ADMIN)) { return true; } // 规则2部门负责人只能删本部门用户 return Objects.equals(current.getDeptId(), target.getDeptId()); } }3.3.1PreAuthorize与自定义方法校验的分工边界PreAuthorize(hasAuthority(sys:user:delete))粗粒度拦截确保请求至少具备该权限标识防止未授权用户直接访问接口路径canDeleteUser()细粒度业务校验基于当前用户身份、目标对象属性、组织架构等上下文做动态决策属于领域逻辑不可省略。注意PreAuthorize注解需在启动类添加EnableMethodSecuritySpring Security 6.0否则注解无效。若用旧版EnableGlobalMethodSecurity(prePostEnabled true)需确保 Spring Boot 版本兼容性2.6.x 及以下。4. 权限数据动态加载前端菜单树生成与按钮权限缓存策略4.1 菜单树递归查询用 MyBatis-Plus LambdaQueryWrapper 构建父子关系前端侧边栏菜单需按parent_id递归生成树形结构。为避免手写递归 SQL利用 MyBatis-Plus 的LambdaQueryWrapper Java 8 Stream 实现Service public class MenuService { Autowired private SysMenuMapper menuMapper; public ListSysMenu buildMenuTree(Long userId) { // 1. 查出用户所有菜单权限含角色继承 ListSysMenu allMenus menuMapper.selectMenusByUserId(userId); // 2. 构建 id - menu 映射 MapLong, SysMenu menuMap allMenus.stream() .collect(Collectors.toMap(SysMenu::getId, m - m, (v1, v2) - v1)); // 3. 找出根节点parent_id 0 ListSysMenu rootMenus allMenus.stream() .filter(m - m.getParentId() 0L) .sorted(Comparator.comparing(SysMenu::getOrderNum)) .collect(Collectors.toList()); // 4. 递归挂载子节点 rootMenus.forEach(menu - buildChildren(menu, menuMap)); return rootMenus; } private void buildChildren(SysMenu parent, MapLong, SysMenu menuMap) { ListSysMenu children menuMap.values().stream() .filter(m - Objects.equals(m.getParentId(), parent.getId())) .sorted(Comparator.comparing(SysMenu::getOrderNum)) .collect(Collectors.toList()); parent.setChildren(children); children.forEach(child - buildChildren(child, menuMap)); } }4.1.1order_num字段为何比sort更可靠order_num是整型排序字段如 10, 20, 30支持在不修改其他节点的情况下插入新菜单如在 10 和 20 之间插入 15而字符串型sort如 01, 02在插入时需重排全部序号易引发并发更新冲突。生产环境必须用数值型排序字段。4.2 按钮权限缓存用 Caffeine 替代 Redis 的本地高性能方案按钮权限如btn:user:edit,btn:order:export变更频率低、数据量小单用户通常 100 项用 Redis 远程调用反而增加 RT。Caffeine 是 JVM 内存级缓存命中率 99%且支持自动刷新Configuration public class CacheConfig { Bean public CacheString, SetString buttonPermissionCache() { return Caffeine.newBuilder() .maximumSize(1000) // 最多缓存 1000 个用户按钮集 .expireAfterWrite(30, TimeUnit.MINUTES) // 写入后 30 分钟过期 .refreshAfterWrite(10, TimeUnit.MINUTES) // 10 分钟后异步刷新 .recordStats() // 开启统计便于监控 .build(); } } Service public class ButtonPermissionService { Resource private CacheString, SetString buttonPermissionCache; public SetString getButtonPermissions(Long userId) { String cacheKey button: userId; return buttonPermissionCache.get(cacheKey, id - { // 缓存未命中时查 DB 构建按钮权限集 return permissionMapper.selectButtonCodesByUserId(userId); }); } }4.2.1refreshAfterWrite与expireAfterWrite的关键区别expireAfterWrite(30, MINUTES)30 分钟后缓存项立即失效下次访问触发重建refreshAfterWrite(10, MINUTES)10 分钟后异步刷新当前请求仍返回旧值新值构建完成后才替换——避免高并发下大量请求同时重建缓存缓存雪崩。提示Caffeine 统计指标可通过buttonPermissionCache.stats()获取建议接入 Prometheus 暴露hitRate,loadSuccessCount等指标及时发现缓存击穿。5. 生产级加固与排错JWT 密钥轮换、敏感信息过滤、常见 403 场景定位5.1 JWT 密钥安全从硬编码到 Spring Boot Config Server 动态加载将密钥写死在application.yml中是重大安全隐患# ❌ 危险密钥泄露即全站沦陷 jwt: secret: mySecretKey123456 # 绝对不能提交到 Git expire: 7200正确做法是通过 Spring Boot 2.4 的Config Data Location机制从外部配置中心或环境变量加载# application.yml spring: config: import: optional:configserver:http://config-server:8888 # 或 # spring: # config: # import: optional:file:/etc/myapp/config/Component ConfigurationProperties(prefix jwt) Data public class JwtProperties { private String secret; // 从 Config Server 或文件读取 private int expire; private String header; }5.1.1 密钥轮换方案双密钥并行校验过渡期密钥不能突然切换否则在线用户 token 全部失效。需支持新旧密钥并存校验public class JwtUtil { Autowired private JwtProperties jwtProperties; Autowired private JwtOldProperties jwtOldProperties; // 旧密钥配置 public boolean validateToken(String token) { try { Jwts.parserBuilder() .setSigningKey(jwtProperties.getSecret()) .build() .parseClaimsJws(token); return true; } catch (SignatureException e) { // 签名失败尝试用旧密钥验证 try { Jwts.parserBuilder() .setSigningKey(jwtOldProperties.getSecret()) .build() .parseClaimsJws(token); return true; } catch (Exception ex) { throw new JwtException(Token 签名校验失败, ex); } } } }5.2 敏感字段脱敏用 Jackson 注解 自定义序列化器拦截密码、手机号Spring Boot 默认 JSON 序列化会暴露SysUser.password、SysUser.phone等字段。必须全局拦截// 全局脱敏配置 Configuration public class JacksonConfig { Bean Primary public ObjectMapper objectMapper() { ObjectMapper mapper new ObjectMapper(); // 注册自定义序列化器 SimpleModule module new SimpleModule(); module.addSerializer(String.class, new SensitiveStringSerializer()); mapper.registerModule(module); return mapper; } } // 脱敏序列化器对标注 Sensitive 注解的字段生效 public class SensitiveStringSerializer extends JsonSerializerString { Override public void serialize(String value, JsonGenerator gen, SerializerProvider serializers) throws IOException { if (value null || value.length() 4) { gen.writeString(value); } else if (value.matches(\\d{11})) { // 手机号 gen.writeString(value.replaceAll((\\d{3})\\d{4}(\\d{4}), $1****$2)); } else if (value.length() 20) { // 密码等长字符串 gen.writeString(******); } else { gen.writeString(value); } } } // 在实体类字段上标注 public class SysUser { private String username; Sensitive // 触发脱敏 private String password; Sensitive private String phone; }5.3 403 错误精准定位三步法排查权限拦截失效根源当接口返回 403 但日志无异常按以下顺序逐层验证步骤检查点命令/操作预期结果1. 认证是否成功SecurityContextHolder.getContext().getAuthentication()是否为null在 Controller 入口加log.info(Auth: {}, SecurityContextHolder.getContext().getAuthentication());非 null且getPrincipal()为UserDetails实例2. 权限是否加载Authentication.getAuthorities()是否包含目标权限log.info(Authorities: {}, auth.getAuthorities().stream().map(GrantedAuthority::getAuthority).collect(Collectors.toList()));列表中存在sys:user:list等目标权限码3.PreAuthorize是否生效对应方法是否被EnableMethodSecurity代理检查启动类是否有EnableMethodSecurity用jstack查看目标方法是否在SecuredAnnotationSecurityMetadataSource调用栈中方法调用前有MethodSecurityInterceptor拦截日志提示若第 2 步权限为空重点检查UserDetailsServiceImpl.loadUserByUsername()中selectPermissionsByUserId()是否返回空集合——常见原因是sys_user_role表未绑定角色或sys_role_permission表未配置权限。5.3.1 一个典型坑PreAuthorize在同一个类内调用失效Service public class UserService { public void updateUser(Long id) { checkPermission(); // ❌ 直接调用AOP 代理不生效 // ... 业务逻辑 } PreAuthorize(hasAuthority(sys:user:update)) public void checkPermission() { // ✅ 此注解无效因非代理对象调用 } }正确解法注入自身 Bean通过代理调用Service public class UserService { Autowired private UserService self; // 自注入 public void updateUser(Long id) { self.checkPermission(); // ✅ 通过代理调用注解生效 } PreAuthorize(hasAuthority(sys:user:update)) public void checkPermission() { } }本文还有配套的精品资源点击获取
