从Shiro迁移到Sa-Token:老版JeecgBoot项目权限框架平滑升级方案
背景介绍
对于许多维护老版JeecgBoot项目的开发者来说，权限框架的升级一直是个棘手问题。这篇文章分享一种实用的方案，用于将老版JeecgBoot中的Apache Shiro替换为更现代的Sa-Token框架。需要特别说明的是，新版JeecgBoot已经采用了Spring Security，本文主要针对那些由于各种原因无法升级到新版的历史项目。
技术痛点
老版JeecgBoot采用Apache Shiro作为权限框架，存在以下问题：
- 配置复杂，使用成本高
- 核心权限逻辑封装在第三方依赖中，不便于修改和扩展
- 对分布式架构支持有限
- 使用注解进行权限控制时，代码侵入性较强
直接替换Shiro会带来巨大的工作量和风险，因此需要一种低侵入性的迁移方案。
技术方案
本方案采用"旁路接管"的思路：通过动态修改Shiro的过滤器链配置，使其放行所有请求，然后使用Sa-Token接管实际的权限控制逻辑。这种方式无需大量修改源码，可以实现平滑迁移。
实现步骤
1. 配置Bean覆盖
在application.yml中添加配置：
spring:
main:
allow-bean-definition-overriding: true
这个配置允许我们的自定义Bean覆盖原有Bean，是整个方案的基础。
2. 创建Shiro配置类
@Configuration
public class CustomShiroConfig {
private static final Logger log = LoggerFactory.getLogger(CustomShiroConfig.class);
public void updateShiroFilterChain(ShiroFilterFactoryBean shiroFilterFactoryBean) {
try {
log.info("======= 开始更新Shiro过滤器链，使所有请求被放行 =======");
// 使用常规方式更新过滤器链定义
Map<String, String> filterChainDefinitionMap = new LinkedHashMap<>();
filterChainDefinitionMap.put("/**", "anon");
shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);
// 使用底层API彻底更新过滤器链
AbstractShiroFilter shiroFilter = (AbstractShiroFilter) shiroFilterFactoryBean.getObject();
if (shiroFilter != null) {
PathMatchingFilterChainResolver filterChainResolver = (PathMatchingFilterChainResolver) shiroFilter.getFilterChainResolver();
DefaultFilterChainManager filterChainManager = (DefaultFilterChainManager) filterChainResolver.getFilterChainManager();
// 清除现有过滤器链
filterChainManager.getFilterChains().clear();
// 重建过滤器链
Map<String, String> chains = new HashMap<>();
chains.put("/**", "anon");
for (Map.Entry<String, String> entry : chains.entrySet()) {
filterChainManager.createChain(entry.getKey(), entry.getValue());
}
log.info("======= Shiro过滤器链更新成功 =======");
}
} catch (Exception e) {
log.error("======= Shiro过滤器链更新失败 =======", e);
}
}
}
这个类的核心是使用两层方式修改Shiro的过滤器链配置，确保Shiro对所有请求都直接放行。
3. 创建简化版ShiroRealm
@Component
public class CustomShiroRealm extends AuthorizingRealm {
private static final Logger log = LoggerFactory.getLogger(CustomShiroRealm.class);
@Override
protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection principals) {
log.info("======= 自定义ShiroRealm: 授权逻辑 =======");
return new SimpleAuthorizationInfo();
}
@Override
protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken auth) {
log.info("======= 自定义ShiroRealm: 认证逻辑 =======");
return null;
}
}
这个Realm实现提供了空的认证和授权逻辑，进一步确保Shiro不会拦截任何请求。
4. 创建启动初始化器
@Component
@Order(1)
public class ShiroInitializer implements ApplicationRunner {
private static final Logger log = LoggerFactory.getLogger(ShiroInitializer.class);
@Autowired
private CustomShiroConfig customShiroConfig;
@Autowired
private ShiroFilterFactoryBean shiroFilterFactoryBean;
@Override
public void run(ApplicationArguments args) throws Exception {
log.info("======= 初始化Shiro配置，确保请求放行 =======");
customShiroConfig.updateShiroFilterChain(shiroFilterFactoryBean);
log.info("======= Shiro配置初始化完成 =======");
}
}
这个初始化器实现了ApplicationRunner接口，确保应用启动时自动执行Shiro配置更新。
5. 配置Sa-Token拦截器
@Configuration
@Order(1)
public class SaTokenConfigure implements WebMvcConfigurer {
private static final Logger log = LoggerFactory.getLogger(SaTokenConfigure.class);
@Autowired
protected SecrityProperties secrityProperties;
@Override
public void addInterceptors(InterceptorRegistry registry) {
// 注册Sa-Token路由拦截器
registry.addInterceptor(new SaRouteInterceptor((req, res, handler)->{
log.info("======= Sa-Token拦截请求: {} =======", req.getUrl());
// 权限控制逻辑
SaRouter.match("/**").notMatch(secrityProperties.getPermitAllUrl()).check(r->{
if(StpUtil.isLogin()){
// 管理员权限检查
log.info("======= 管理员登录, ID: {} =======", StpUtil.getLoginIdAsString());
StpUtil.checkLogin();
// 可添加更多权限检查
// StpUtil.checkPermission("system:user:view");
// StpUtil.checkRole("admin");
} else {
// 普通用户权限检查
if(StpUserUtil.isLogin()) {
log.info("======= 普通用户登录, ID: {} =======", StpUserUtil.getLoginIdAsString());
} else {
log.info("======= 用户未登录，拦截请求 =======");
}
StpUserUtil.checkLogin();
}
});
})).addPathPatterns("/**");
}
}
这是整个方案的核心，Sa-Token拦截器接管了实际的权限控制逻辑。
6. 配置白名单
@Component
@ConfigurationProperties(prefix = "secrity")
public class SecrityProperties {
/**
* 白名单URL配置
*/
public List<String> permitAllUrl;
public List<String> getPermitAllUrl() {
return permitAllUrl;
}
public void setPermitAllUrl(List<String> permitAllUrl) {
this.permitAllUrl = permitAllUrl;
}
}
这个配置类用于加载白名单配置，定义哪些URL可以跳过权限检查。
实现原理分析
1. 动态修改Shiro过滤器链
本方案的一个关键点是修改Shiro的过滤器链配置。通过同时使用两种方式（常规配置和底层API）来确保修改生效：
// 常规方式
filterChainDefinitionMap.put("/**", "anon");
shiroFilterFactoryBean.setFilterChainDefinitionMap(filterChainDefinitionMap);
// 底层API方式
DefaultFilterChainManager filterChainManager = ...
filterChainManager.getFilterChains().clear();
filterChainManager.createChain("/**", "anon");
这样的双重保障确保了修改的可靠性。
2. 启动时自动配置
通过实现ApplicationRunner接口，在应用启动时自动执行配置：
@Override
public void run(ApplicationArguments args) throws Exception {
customShiroConfig.updateShiroFilterChain(shiroFilterFactoryBean);
}
这样确保了每次应用启动都会执行Shiro配置更新。
3. Bean覆盖机制
allow-bean-definition-overriding: true配置是整个方案的基础，它允许我们的自定义Bean覆盖原有Bean，从而实现对原有配置的非侵入式修改。
技术优势
- 低侵入性：不需要修改JeecgBoot源码，只需添加几个配置类
- 风险可控：可以逐步迁移，先让Shiro放行，再一步步实现Sa-Token的各项功能
- 保持兼容：原有基于Shiro的代码可以继续工作，减少迁移阻力
- 架构升级：Sa-Token提供了更现代的特性，如分布式Session、多端登录控制等
注意事项
- 性能考量：请求会经过Shiro和Sa-Token两层处理，有轻微性能影响，但对大多数应用影响不大
- 升级兼容性：升级JeecgBoot时需要检查Shiro配置是否变化，可能需要调整配置
- 权限迁移：需要逐步将基于Shiro的权限控制逻辑迁移到Sa-Token
扩展方向
- 自定义注解：开发基于Sa-Token的权限注解，替代原有Shiro注解
- 整合业务逻辑：在Sa-Token拦截器中增加特定业务场景的权限控制
- 分布式架构支持：利用Sa-Token的集成Redis等特性，支持分布式应用架构
- 权限管理前端：可以开发基于Sa-Token的权限管理界面，提升用户体验
总结
这种"旁路接管"方案为老版JeecgBoot项目提供了一条低风险的权限框架升级路径。通过动态修改Shiro配置并引入Sa-Token，实现了非侵入式的框架迁移。对于无法立即升级到新版JeecgBoot的项目，这种方案能够在保持系统稳定的同时，引入现代权限框架的优势。
这个方案的核心思想也适用于其他基于Shiro的系统，可以作为一种通用的迁移策略。通过技术框架的平滑升级，我们可以持续提升系统的安全性、可维护性和扩展性，延长历史项目的生命周期。
