Spring Boot 2.x整合Apache Shiro权限控制实战指南-尧图网络科技

你的王牌特工，霹雳椒娃已上线：Spring Boot 2.x 整合 Apache Shiro 安全框架实战指南

在日常企业级应用开发中，权限控制与安全认证是每个后端开发者必须面对的核心问题。最近在重构一个内部管理系统时，我深刻体会到选择合适的安全框架对项目稳定性的重要性。本文将基于 Spring Boot 2.x 整合 Apache Shiro，手把手带你构建一个完整的权限管理系统，涵盖从环境搭建到生产部署的全流程。

无论你是刚接触安全框架的新手，还是希望优化现有权限体系的进阶开发者，本文提供的完整代码示例和避坑指南都能直接复用。我们将重点解决 Shiro 与 Spring Boot 的版本兼容性、动态权限管理、会话控制等实际开发中的高频问题。

1. 安全框架背景与核心概念

1.1 为什么需要权限控制框架

在现代 Web 应用中，不同用户需要访问不同的资源。比如普通员工只能查看个人信息，而部门经理可以审批请假，系统管理员则拥有全部权限。如果手动在每个接口编写权限判断逻辑，不仅代码冗余，还容易产生安全漏洞。

Apache Shiro 是一个强大易用的 Java 安全框架，提供了认证、授权、加密和会话管理等功能。与 Spring Security 相比，Shiro 的 API 设计更加直观，学习曲线平缓，特别适合中小型项目的快速集成。

1.2 Shiro 核心组件解析

Shiro 架构围绕三个核心概念构建：

Subject（主体）：代表当前执行操作的用户或程序，是 Shiro 的核心交互对象。开发者通过 Subject 进行登录、权限验证等操作。

SecurityManager（安全管理器）：Shiro 的核心组件，管理所有 Subject 的安全操作。它协调多个安全组件的工作，相当于 Spring 的 ApplicationContext。

Realm（域）：Shiro 与应用安全数据（用户、角色、权限）的桥梁。开发者需要自定义 Realm 实现，从数据库或其他数据源加载认证和授权信息。

// Shiro 核心工作流程示例 Subject currentUser = SecurityUtils.getSubject(); if (!currentUser.isAuthenticated()) { UsernamePasswordToken token = new UsernamePasswordToken("username", "password"); currentUser.login(token); // 认证 } if (currentUser.hasRole("admin")) { // 授权 // 执行管理员操作 }

2. 环境准备与版本说明

2.1 技术栈与版本要求

本次实战基于以下环境，建议读者保持相同版本以避免兼容性问题：

JDK 版本：1.8 或更高（推荐 OpenJDK 11）
Spring Boot：2.7.18（长期支持版本）
Apache Shiro：1.11.0（与 Spring Boot 2.x 兼容性最佳）
数据库：MySQL 8.0（也可适配其他关系型数据库）
构建工具：Maven 3.6+
IDE：IntelliJ IDEA 或 Eclipse

2.2 项目结构规划

在开始编码前，我们先规划清晰的项目结构：

shiro-demo/ ├── src/ │ ├── main/ │ │ ├── java/ │ │ │ └── com/ │ │ │ └── example/ │ │ │ └── shirodemo/ │ │ │ ├── config/ # 配置类 │ │ │ ├── controller/ # 控制器 │ │ │ ├── entity/ # 实体类 │ │ │ ├── realm/ # 自定义 Realm │ │ │ ├── service/ # 业务层 │ │ │ └── ShiroDemoApplication.java │ │ └── resources/ │ │ ├── application.yml # 主配置文件 │ │ └── shiro-config.ini # Shiro 配置（可选） │ └── test/ # 测试代码 ├── pom.xml # Maven 依赖 └── README.md

3. 核心依赖与基础配置

3.1 Maven 依赖配置

在pom.xml中添加 Spring Boot 和 Shiro 相关依赖。特别注意版本兼容性，错误版本组合会导致启动失败。

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.7.18</version> <relativePath/> </parent> <groupId>com.example</groupId> <artifactId>shiro-demo</artifactId> <version>1.0.0</version> <properties> <java.version>11</java.version> <shiro.version>1.11.0</shiro.version> </properties> <dependencies> <!-- Spring Boot Web 支持 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <!-- Spring Boot Thymeleaf 模板（可选，用于演示页面） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-thymeleaf</artifactId> </dependency> <!-- Shiro 核心 --> <dependency> <groupId>org.apache.shiro</groupId> <artifactId>shiro-spring-boot-web-starter</artifactId> <version>${shiro.version}</version> </dependency> <!-- 数据库相关（按需添加） --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-data-jpa</artifactId> </dependency> <dependency> <groupId>mysql</groupId> <artifactId>mysql-connector-java</artifactId> <scope>runtime</scope> </dependency> <!-- 测试依赖 --> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> </project>

3.2 应用配置文件

在application.yml中配置数据库连接、Shiro 基本参数等：

server: port: 8080 servlet: context-path: /shiro-demo spring: datasource: url: jdbc:mysql://localhost:3306/shiro_demo?useSSL=false&serverTimezone=UTC username: root password: 123456 driver-class-name: com.mysql.cj.jdbc.Driver jpa: hibernate: ddl-auto: update show-sql: true # Shiro 特定配置 shiro: enabled: true loginUrl: /login # 未认证时重定向地址 successUrl: /index # 登录成功默认跳转地址 unauthorizedUrl: /403 # 未授权访问跳转地址

4. Shiro 核心配置类详解

4.1 安全管理器配置

创建ShiroConfig类，这是整合 Spring Boot 与 Shiro 的核心配置：

package com.example.shirodemo.config; import org.apache.shiro.spring.web.ShiroFilterFactoryBean; import org.apache.shiro.web.mgt.DefaultWebSecurityManager; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import javax.servlet.Filter; import java.util.LinkedHashMap; import java.util.Map; @Configuration public class ShiroConfig { /** * 创建自定义 Realm */ @Bean public CustomRealm customRealm() { return new CustomRealm(); } /** * 创建安全管理器，并注入自定义 Realm */ @Bean public DefaultWebSecurityManager securityManager() { DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager(); securityManager.setRealm(customRealm()); return securityManager; } /** * Shiro 过滤器工厂，定义URL拦截规则 */ @Bean public ShiroFilterFactoryBean shiroFilterFactoryBean() { ShiroFilterFactoryBean factoryBean = new ShiroFilterFactoryBean(); factoryBean.setSecurityManager(securityManager()); // 设置登录页面 factoryBean.setLoginUrl("/login"); // 登录成功后跳转页面 factoryBean.setSuccessUrl("/index"); // 未授权页面 factoryBean.setUnauthorizedUrl("/403"); // 定义过滤器链（注意顺序很重要） Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>(); // 静态资源放行 filterChainDefinitionMap.put("/css/**", "anon"); filterChainDefinitionMap.put("/js/**", "anon"); filterChainDefinitionMap.put("/images/**", "anon"); // 登录相关接口放行 filterChainDefinitionMap.put("/login", "anon"); filterChainDefinitionMap.put("/doLogin", "anon"); // 需要认证的接口 filterChainDefinitionMap.put("/user/**", "authc"); filterChainDefinitionMap.put("/admin/**", "authc,roles[admin]"); // 其余接口需要登录访问 filterChainDefinitionMap.put("/**", "authc"); factoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap); return factoryBean; } }

4.2 自定义 Realm 实现

Realm 是 Shiro 连接应用数据的桥梁，我们需要实现认证和授权逻辑：

package com.example.shirodemo.realm; import org.apache.shiro.authc.*; import org.apache.shiro.authz.AuthorizationInfo; import org.apache.shiro.authz.SimpleAuthorizationInfo; import org.apache.shiro.realm.AuthorizingRealm; import org.apache.shiro.subject.PrincipalCollection; import org.springframework.stereotype.Component; @Component public class CustomRealm extends AuthorizingRealm { /** * 授权逻辑：获取用户的角色和权限信息 */ @Override protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) { String username = (String) principals.getPrimaryPrincipal(); SimpleAuthorizationInfo authorizationInfo = new SimpleAuthorizationInfo(); // 模拟从数据库查询用户角色和权限 if ("admin".equals(username)) { authorizationInfo.addRole("admin"); authorizationInfo.addStringPermission("user:delete"); authorizationInfo.addStringPermission("user:update"); } else if ("user".equals(username)) { authorizationInfo.addRole("user"); authorizationInfo.addStringPermission("user:view"); } return authorizationInfo; } /** * 认证逻辑：验证用户身份 */ @Override protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) throws AuthenticationException { UsernamePasswordToken upToken = (UsernamePasswordToken) token; String username = upToken.getUsername(); String password = new String(upToken.getPassword()); // 模拟数据库验证（实际项目中应查询数据库） if ("admin".equals(username) && "admin123".equals(password)) { return new SimpleAuthenticationInfo(username, password, getName()); } else if ("user".equals(username) && "user123".equals(password)) { return new SimpleAuthenticationInfo(username, password, getName()); } throw new UnknownAccountException("用户名或密码错误"); } }

5. 控制器层与页面实现

5.1 登录控制器

创建登录相关的控制器，处理用户认证请求：

package com.example.shirodemo.controller; import org.apache.shiro.SecurityUtils; import org.apache.shiro.authc.*; import org.apache.shiro.subject.Subject; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestParam; @Controller public class LoginController { @GetMapping("/login") public String loginPage() { // 如果已经登录，直接跳转到首页 Subject subject = SecurityUtils.getSubject(); if (subject.isAuthenticated()) { return "redirect:/index"; } return "login"; } @PostMapping("/doLogin") public String doLogin(@RequestParam String username, @RequestParam String password, Model model) { try { Subject subject = SecurityUtils.getSubject(); UsernamePasswordToken token = new UsernamePasswordToken(username, password); subject.login(token); return "redirect:/index"; } catch (UnknownAccountException e) { model.addAttribute("error", "用户名不存在"); } catch (IncorrectCredentialsException e) { model.addAttribute("error", "密码错误"); } catch (LockedAccountException e) { model.addAttribute("error", "账户被锁定"); } catch (AuthenticationException e) { model.addAttribute("error", "认证失败"); } return "login"; } @GetMapping("/logout") public String logout() { SecurityUtils.getSubject().logout(); return "redirect:/login"; } }

5.2 业务控制器

创建需要权限控制的业务接口：

package com.example.shirodemo.controller; import org.apache.shiro.authz.annotation.RequiresPermissions; import org.apache.shiro.authz.annotation.RequiresRoles; import org.springframework.stereotype.Controller; import org.springframework.ui.Model; import org.springframework.web.bind.annotation.GetMapping; @Controller public class BusinessController { @GetMapping("/index") public String index(Model model) { model.addAttribute("message", "欢迎来到首页"); return "index"; } @GetMapping("/user/list") @RequiresPermissions("user:view") public String userList(Model model) { model.addAttribute("users", "用户列表数据"); return "user/list"; } @GetMapping("/admin/dashboard") @RequiresRoles("admin") public String adminDashboard(Model model) { model.addAttribute("adminInfo", "管理员仪表板数据"); return "admin/dashboard"; } @GetMapping("/403") public String unauthorized() { return "error/403"; } }

5.3 前端页面模板

创建简单的 Thymeleaf 模板页面：

登录页面 (login.html)：

<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>用户登录</title> <link rel="stylesheet" th:href="@{/css/style.css}"> </head> <body> <div class="login-container"> <h2>系统登录</h2> <form th:action="@{/doLogin}" method="post"> <div class="form-group"> <input type="text" name="username" placeholder="用户名" required> </div> <div class="form-group"> <input type="password" name="password" placeholder="密码" required> </div> <button type="submit">登录</button> </form> <div th:if="${error}" class="error-message" th:text="${error}"></div> </div> </body> </html>

首页 (index.html)：

<!DOCTYPE html> <html xmlns:th="http://www.thymeleaf.org"> <head> <meta charset="UTF-8"> <title>系统首页</title> </head> <body> <h1 th:text="${message}">欢迎页面</h1> <div> <a th:href="@{/user/list}">查看用户列表</a> | <a th:href="@{/admin/dashboard}">管理员面板</a> | <a th:href="@{/logout}">退出登录</a> </div> </body> </html>

6. 高级特性与最佳实践

6.1 密码加密与安全

在实际项目中，明文存储密码是严重的安全隐患。Shiro 提供了强大的加密支持：

package com.example.shirodemo.config; import org.apache.shiro.authc.credential.HashedCredentialsMatcher; import org.apache.shiro.crypto.hash.Sha256Hash; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; @Configuration public class SecurityConfig { /** * 配置密码加密匹配器 */ @Bean public HashedCredentialsMatcher hashedCredentialsMatcher() { HashedCredentialsMatcher matcher = new HashedCredentialsMatcher(); matcher.setHashAlgorithmName(Sha256Hash.ALGORITHM_NAME); matcher.setHashIterations(1024); // 哈希迭代次数 matcher.setStoredCredentialsHexEncoded(true); // 十六进制编码 return matcher; } /** * 密码加密工具方法 */ public static String encryptPassword(String password, String salt) { return new Sha256Hash(password, salt, 1024).toHex(); } } // 在自定义 Realm 中设置加密匹配器 @Component public class CustomRealm extends AuthorizingRealm { @Autowired public void setCredentialsMatcher(HashedCredentialsMatcher matcher) { super.setCredentialsMatcher(matcher); } @Override protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) { // 认证时自动进行密码匹配 String username = (String) token.getPrincipal(); // 从数据库查询加密后的密码和盐值 String encryptedPassword = "从数据库查询的加密密码"; String salt = "用户对应的盐值"; return new SimpleAuthenticationInfo( username, encryptedPassword, ByteSource.Util.bytes(salt), getName() ); } }

6.2 会话管理配置

Shiro 提供了灵活的会话管理机制，可以替代 HttpSession：

@Configuration public class SessionConfig { /** * 配置会话管理器 */ @Bean public SessionManager sessionManager() { DefaultWebSessionManager sessionManager = new DefaultWebSessionManager(); // 设置会话超时时间（毫秒） sessionManager.setGlobalSessionTimeout(1800000); // 30分钟 // 删除无效session sessionManager.setDeleteInvalidSessions(true); // 定时验证session sessionManager.setSessionValidationSchedulerEnabled(true); return sessionManager; } /** * 在安全管理器中注入会话管理器 */ @Bean public DefaultWebSecurityManager securityManager(SessionManager sessionManager) { DefaultWebSecurityManager securityManager = new DefaultWebSecurityManager(); securityManager.setRealm(customRealm()); securityManager.setSessionManager(sessionManager); return securityManager; } }

6.3 注解式权限控制

除了在配置文件中定义权限规则，还可以使用注解进行细粒度控制：

@RestController @RequestMapping("/api") public class ApiController { @GetMapping("/userInfo") @RequiresAuthentication // 需要登录 public ResponseEntity<User> getUserInfo() { // 获取当前用户信息 return ResponseEntity.ok(userService.getCurrentUser()); } @PostMapping("/user") @RequiresPermissions("user:create") // 需要创建权限 public ResponseEntity createUser(@RequestBody User user) { userService.createUser(user); return ResponseEntity.ok().build(); } @DeleteMapping("/user/{id}") @RequiresPermissions("user:delete") // 需要删除权限 public ResponseEntity deleteUser(@PathVariable Long id) { userService.deleteUser(id); return ResponseEntity.ok().build(); } @GetMapping("/admin/report") @RequiresRoles("admin") // 需要管理员角色 public ResponseEntity<Report> getAdminReport() { return ResponseEntity.ok(reportService.generateAdminReport()); } }

7. 常见问题与解决方案

7.1 启动类配置要点

确保主启动类正确扫描到 Shiro 配置：

package com.example.shirodemo; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class ShiroDemoApplication { public static void main(String[] args) { SpringApplication.run(ShiroDemoApplication.class, args); } }

7.2 权限注解不生效问题

如果@RequiresRoles等注解不生效，需要在配置类中开启注解支持：

@Configuration public class ShiroAnnotationConfig { /** * 开启Shiro注解支持 */ @Bean public AuthorizationAttributeSourceAdvisor authorizationAttributeSourceAdvisor( DefaultWebSecurityManager securityManager) { AuthorizationAttributeSourceAdvisor advisor = new AuthorizationAttributeSourceAdvisor(); advisor.setSecurityManager(securityManager); return advisor; } /** * 支持AOP代理 */ @Bean @DependsOn("lifecycleBeanPostProcessor") public DefaultAdvisorAutoProxyCreator defaultAdvisorAutoProxyCreator() { DefaultAdvisorAutoProxyCreator creator = new DefaultAdvisorAutoProxyCreator(); creator.setProxyTargetClass(true); return creator; } }

7.3 静态资源被拦截问题

如果CSS、JS等静态资源被Shiro拦截，检查过滤器链配置：

// 在ShiroConfig的filterChainDefinitionMap中添加 filterChainDefinitionMap.put("/static/**", "anon"); filterChainDefinitionMap.put("/**.js", "anon"); filterChainDefinitionMap.put("/**.css", "anon");

7.4 会话持久化配置

生产环境建议配置Redis等外部会话存储：

@Bean public RedisSessionDAO redisSessionDAO() { RedisSessionDAO redisSessionDAO = new RedisSessionDAO(); redisSessionDAO.setRedisManager(redisManager()); return redisSessionDAO; } @Bean public SessionManager sessionManager() { DefaultWebSessionManager sessionManager = new DefaultWebSessionManager(); sessionManager.setSessionDAO(redisSessionDAO()); return sessionManager; }