当前位置：首页 > article >正文

Apache Shiro 统一化实现多端登录（PC端移动端）

article 2026/2/20 11:38:58

Apache Shiro 是一个强大且易用的Java安全框架，提供了身份验证、授权、密码学和会话管理等功能。它被广泛用于保护各种类型的应用程序，包括Web应用、桌面应用、RESTful服务、移动端应用和大型企业级应用。

需求背景

在当今数字化浪潮的推动下，我们共同见证了互联网从萌芽到繁荣的辉煌历程，随后移动互联网的异军突起，更是将信息的触角延伸至社会的每一个角落。这一系列的变革，不仅重塑了人们的生活方式，也极大地丰富了我们的数字生活体验。如今，用户接入数字世界的终端类型呈现出前所未有的多样化态势，从传统的Web端，到便捷的APP端，再到轻量级的小程序端，每一种终端都承载着不同的使用场景与用户需求，共同编织起一张错综复杂的数字网络。

面对如此多元且复杂的终端环境，登录与注销作为用户进入和退出系统的出入口，看似简单，实则不然。从单一终端的视角审视，登录与注销功能或许显得简单直接，无非是输入凭证、验证身份、完成会话的建立或终止。然而，当我们转换视角，从多端协同的宏观层面去考量时，就会发现这一功能的实现远非想象中那般轻松。

根据以往经验，面对此问题，我们可能是这样做的：

Web端：开发一套接口，单独维护；
移动端：开发一套接口，单独维护；

当前方案功能实现无碍，但后续维护成本高昂。需求变更时需同步维护多套关联接口并开展回归测试，既耗时又易因版本差异引发非预期故障，影响系统稳定性。

需求分析

我们再来分析一下，多端会话ID在交互方式上呈现的差异化特征：

Web端：在常规应用场景中，会话 ID 一般会被存储在 Cookie 里，随后借助 Cookie 机制来实现交互操作。
移动端：在与服务端进行交互时，采用 RESTful 接口的方式，而会话 ID 一般会被放置在请求的 Header 中，以此来实现会话的标识与传递。

若期望通过一套代码来达成多端需求的统一实现，其核心思路在于将各类相关特征进行有机整合，并依据请求类型的差异，动态地启用相应的处理机制。这一理念在逻辑上清晰明了，然而令人遗憾的是，Apache Shiro 框架原生并不支持这种实现方式。

我曾查遍 Apache Shiro 官网文档，竟找不出任何关于支持移动端的任何描述。但方法总比困难多，通过阅读源码，逐步Debug，梳理出一条清晰的脉络，可以实现上述的思路。这就是开源的好处呀！

不得不说，Apache Shrio 的设计哲学真的太棒了，原理易懂，模块划分合理，它以简洁高效之姿，展现出独特的魅力与实用价值。

搞清楚这一点，你便会恍然大悟：Apache Shiro 凭借其强大的功能特性，可应用于各种需要认证与鉴权的场景，无论是传统的 Web 端，还是当下流行的移动端，亦或是便捷实用的小程序端，皆在其适用范畴之内。

建议：大家有时间，真的可以把Shiro源码跟着Debug阅读一下，必将大有脾益。那时，你不仅会愈发倾心于Apache Shiro的精巧设计，更能参透其蕴含的安全哲学。彼时，或许便能体会我此刻按捺不住的分享热忱。

相信此刻的你，已经迫不及待啦！我们一起揭开这神秘的面纱吧！从实战角度，一步步达成目标。

知晓了原理，代码实现很简单。

实战环境

Spring Boot 3
JDK 17
Redis

关于 Spring Boot 3 如何集成 Apache Shiro 可以参考这篇文章，本次实战，以此为基础。

SpringBoot3 集成 Shirohttps://blog.csdn.net/li277967151/article/details/140927139

实战

注：此次实战，仅展示核心Code。

完整代码，大家可以访问这个开源项目，直接Running，更有Feel

TyFast: 基于SpringBoot+Shiro搭建的快速开发平台https://gitee.com/tommycloud/TyFast

1、Yaml配置

#Shiro配置
shiro:loginUrl: /loginsuccessUrl: /indexunauthorizedUrl: /error/401.htmllogoutUrl: /logoutuserNativeSessionManager: true #false：表示基于Servlet容器 实现Session（即HttpSession）sessionManager:cookie:name: tysidpath: /

2、SpringBoot 自动装配类

package com.ty.web.spring.config;import at.pollux.thymeleaf.shiro.dialect.ShiroDialect;
import com.ty.web.shiro.AuthenticationFilter;
import com.ty.web.shiro.AuthorizationFilter;
import com.ty.web.shiro.CookieLogoutFilter;
import com.ty.web.shiro.DistributedSessionDao;
import com.ty.web.shiro.TyWebSessionManager;
import com.ty.web.shiro.realm.NormalRealm;
import com.ty.web.shiro.realm.WithoutPasswordRealm;
import com.ty.web.spring.config.properties.ShiroProperties;
import jakarta.servlet.DispatcherType;
import lombok.extern.slf4j.Slf4j;
import org.apache.commons.lang3.StringUtils;
import org.apache.shiro.SecurityUtils;
import org.apache.shiro.config.Ini;
import org.apache.shiro.mgt.SecurityManager;
import org.apache.shiro.realm.Realm;
import org.apache.shiro.session.mgt.SessionManager;
import org.apache.shiro.session.mgt.eis.SessionDAO;
import org.apache.shiro.spring.web.ShiroFilterFactoryBean;
import org.apache.shiro.spring.web.config.AbstractShiroWebConfiguration;
import org.apache.shiro.spring.web.config.DefaultShiroFilterChainDefinition;
import org.apache.shiro.util.CollectionUtils;
import org.apache.shiro.web.config.IniFilterChainResolverFactory;
import org.apache.shiro.web.mgt.DefaultWebSecurityManager;
import org.apache.shiro.web.servlet.AbstractShiroFilter;
import org.apache.shiro.web.session.mgt.DefaultWebSessionManager;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.autoconfigure.condition.ConditionalOnWebApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;import java.util.Map;import static com.ty.cm.constant.ShiroConstant.SESSION_TIMEOUT;
import static org.apache.shiro.spring.config.web.autoconfigure.ShiroWebFilterConfiguration.FILTER_NAME;
import static org.apache.shiro.spring.config.web.autoconfigure.ShiroWebFilterConfiguration.REGISTRATION_BEAN_NAME;/*** Shiro配置** @Author Tommy* @Date 2022/1/27*/
@Configuration
@EnableConfigurationProperties(ShiroProperties.class)
@ConditionalOnWebApplication(type = ConditionalOnWebApplication.Type.SERVLET)
@ConditionalOnProperty(name = "shiro.web.enabled", matchIfMissing = true)
@Slf4j
public class ShiroConfig extends AbstractShiroWebConfiguration {@Value("#{ @environment['shiro.sessionManager.cookie.name'] ?: 'x-auth-token'}")private String sessionIdHeader;/*** Shiro 常规认证Realm*/@Beanpublic Realm authenticationRealm() {return new NormalRealm();}/*** Shiro 免密认证Realm*/@Beanpublic Realm withoutPasswordRealm() {return new WithoutPasswordRealm();}/*** 分布式Session Dao*/@Beanpublic SessionDAO sessionDAO() {return new DistributedSessionDao();}/*** Shiro Session Manager*/@Beanpublic SessionManager sessionManager() {return super.sessionManager();}/*** Shiro 核心过滤器*/@Beanpublic ShiroFilterFactoryBean shiroFilterFactoryBean(SecurityManager securityManager, ShiroProperties shiroProperties) {final ShiroFilterFactoryBean filterFactoryBean = new ShiroFilterFactoryBean();filterFactoryBean.setSecurityManager(securityManager); // Shiro的核心安全接口,这个属性是必须的// 各URL参数filterFactoryBean.setLoginUrl(shiroProperties.getLoginUrl()); // 登录URL,非必须的属性filterFactoryBean.setSuccessUrl(shiroProperties.getSuccessUrl()); // 登录成功后要跳转的URLfilterFactoryBean.setUnauthorizedUrl(shiroProperties.getUnauthorizedUrl()); // 访问未经授权的资源时,转到的URL// 替换Shiro默认的Filter（ShiroFilter 集成了过滤器filterchain 模式，所以Shiro内部Filter不要通过SpringBoot实例化，否则就会成为全局Filter，拦截异常）filterFactoryBean.getFilters().put("authc", authenticationFilter());filterFactoryBean.getFilters().put("perms", authorizationFilter());filterFactoryBean.getFilters().put("logout", cookieLogoutFilter());// 设置鉴权规则filterFactoryBean.setFilterChainDefinitionMap(shiroFilterChainDefinition(shiroProperties));// 设置Session有效期（只有自己实现Session DAO时，才需要设置此项）// 基于Servlet容器的 Shiro Session，有效期同 HttpSessionDefaultWebSecurityManager webSecurityManager = (DefaultWebSecurityManager) securityManager;((DefaultWebSessionManager) webSecurityManager.getSessionManager()).setGlobalSessionTimeout(SESSION_TIMEOUT * 1000); // 单位：毫秒// 设置Shiro工具类，便于获取相关对象SecurityUtils.setSecurityManager(securityManager);log.info("Apache Shiro :: 初始化完成！");return filterFactoryBean;}/*** 手动配置 Shiro 核心过滤器 (建议手动配置，否则可能因SpringBoot问题，无法初始化)*/@Bean(name = REGISTRATION_BEAN_NAME)public FilterRegistrationBean<AbstractShiroFilter> filterShiroFilterRegistrationBean(ShiroFilterFactoryBean shiroFilterFactoryBean) throws Exception {FilterRegistrationBean<AbstractShiroFilter> filterRegistrationBean = new FilterRegistrationBean<>();filterRegistrationBean.setDispatcherTypes(DispatcherType.REQUEST, DispatcherType.FORWARD, DispatcherType.INCLUDE, DispatcherType.ERROR);filterRegistrationBean.setFilter((AbstractShiroFilter)shiroFilterFactoryBean.getObject());filterRegistrationBean.setName(FILTER_NAME);filterRegistrationBean.setOrder(1);return filterRegistrationBean;}/*** Shiro连接约束配置,即过滤链的定义* <b>*  <p> anon： 匿名访问</p>*	<p> authc：认证访问</p>*	<p> perms：授权访问</p>*	<p> logout：注销访问</p>* </b>*/private Map<String, String> shiroFilterChainDefinition(ShiroProperties shiroProperties) {final DefaultShiroFilterChainDefinition chainDefinition = new DefaultShiroFilterChainDefinition();if (StringUtils.isNotBlank(shiroProperties.getLoginUrl())) { // 登录chainDefinition.addPathDefinition(shiroProperties.getLoginUrl(), "authc");}if (StringUtils.isNotBlank(shiroProperties.getLogoutUrl())) { // 注销chainDefinition.addPathDefinition(shiroProperties.getLogoutUrl(), "logout");}// 设置无需鉴权的URLshiroProperties.getIgnoreUrls().stream().filter(url -> StringUtils.isNotBlank(url)).forEach(url -> chainDefinition.addPathDefinition(url, "anon"));// 读取鉴权配置信息if (StringUtils.isNotBlank(shiroProperties.getRules())) {final Ini ini = new Ini();ini.load(shiroProperties.getRules());Ini.Section section = ini.getSection(IniFilterChainResolverFactory.URLS);if (CollectionUtils.isEmpty(section)) {section = ini.getSection(Ini.DEFAULT_SECTION_NAME);}chainDefinition.addPathDefinitions(section);}log.info("Shiro::鉴权规则初始化完毕::DefaultShiroFilterChainDefinition! --> " + chainDefinition.getFilterChainMap());return chainDefinition.getFilterChainMap();}/*** 替换Shiro默认的Filter实现：认证过滤器*/@Beanpublic AuthenticationFilter authenticationFilter() {AuthenticationFilter authcFilter = new AuthenticationFilter();authcFilter.setUsernameParam("loginName");return authcFilter;}/*** 替换Shiro默认的Filter实现：鉴权过滤器*/private AuthorizationFilter authorizationFilter() {return new AuthorizationFilter();}/*** 替换Shiro默认的Filter实现：Logout过滤器*/private CookieLogoutFilter cookieLogoutFilter() {return new CookieLogoutFilter();}/*** 替换Shiro默认的 Native Session Manager*/@Overrideprotected SessionManager nativeSessionManager() {TyWebSessionManager webSessionManager = new TyWebSessionManager();webSessionManager.setSessionIdCookieEnabled(this.sessionIdCookieEnabled);webSessionManager.setSessionIdUrlRewritingEnabled(this.sessionIdUrlRewritingEnabled);webSessionManager.setSessionIdHeader(this.sessionIdHeader);webSessionManager.setSessionIdCookie(this.sessionCookieTemplate());webSessionManager.setSessionFactory(this.sessionFactory());webSessionManager.setSessionDAO(this.sessionDAO());webSessionManager.setDeleteInvalidSessions(this.sessionManagerDeleteInvalidSessions);return webSessionManager;}/*** Thymeleaf 与 Shiro 整合*/@Beanpublic ShiroDialect shiroDialect() {return new ShiroDialect();}
}

关于实现此需求，这个装配类的核心代码就2点

此类需继承：AbstractShiroWebConfiguration
替换Shiro默认的 Native Session Manager

    /*** 替换Shiro默认的 Native Session Manager*/@Overrideprotected SessionManager nativeSessionManager() {TyWebSessionManager webSessionManager = new TyWebSessionManager();webSessionManager.setSessionIdCookieEnabled(this.sessionIdCookieEnabled);webSessionManager.setSessionIdUrlRewritingEnabled(this.sessionIdUrlRewritingEnabled);webSessionManager.setSessionIdHeader(this.sessionIdHeader);webSessionManager.setSessionIdCookie(this.sessionCookieTemplate());webSessionManager.setSessionFactory(this.sessionFactory());webSessionManager.setSessionDAO(this.sessionDAO());webSessionManager.setDeleteInvalidSessions(this.sessionManagerDeleteInvalidSessions);return webSessionManager;}

注：为什么这两个是关键点，说来话长，这里不做阐述，若你Debug一下源码，自然分晓。

3、实现自己的认证接口Filter

package com.ty.web.shiro;import com.ty.api.log.service.LoginAuditLogService;
import com.ty.api.model.log.LoginAuditLog;
import com.ty.api.model.system.SysUser;
import com.ty.api.system.service.SysUserService;
import com.ty.cm.model.AjaxResult;
import com.ty.cm.utils.URLUtils;
import com.ty.web.push.TPush;
import com.ty.web.spring.SpringContextHolder;
import com.ty.web.utils.WebIpUtil;
import com.ty.web.utils.WebUtil;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServletResponse;
import lombok.extern.slf4j.Slf4j;
import org.apache.shiro.authc.AuthenticationException;
import org.apache.shiro.authc.AuthenticationToken;
import org.apache.shiro.subject.Subject;
import org.apache.shiro.web.filter.authc.FormAuthenticationFilter;
import org.apache.shiro.web.util.WebUtils;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Lazy;import java.io.IOException;
import java.util.Date;import static com.ty.cm.constant.Numbers.ONE;
import static com.ty.cm.constant.ShiroConstant.DEFAULT_CAPTCHA_PARAM;/*** Shiro认证服务** @Author Tommy* @Date 2022/1/27*/
@Slf4j
public class AuthenticationFilter extends FormAuthenticationFilter {/** 账户业务接口 **/@Autowired@Lazyprivate SysUserService sysUserService;/** 登录日志接口 **/@Autowired@Lazyprivate LoginAuditLogService loginAuditLogService;/** TPush消息推送 **/@Autowired@Lazyprivate TPush tpush;/** "验证码"参数名称 */private String captchaParam = DEFAULT_CAPTCHA_PARAM;/*** 创建令牌*/@Overrideprotected AuthenticationToken createToken(ServletRequest request, ServletResponse response) {String username = getUsername(request);String password = getPassword(request);boolean rememberMe = isRememberMe(request);String host = getHost(request);String captcha = getCaptcha(request);return new com.ty.web.shiro.AuthenticationToken(username, password, rememberMe, host, captcha);}/*** 未经认证时访问系统在此拦截*/@Overrideprotected boolean onAccessDenied(ServletRequest request, ServletResponse response) throws Exception {final boolean isLoginRequest = super.isLoginRequest(request, response);if (!isLoginRequest && WebUtil.isAjax()) { // 登录URL不能拦截WebUtil.sendError(WebUtils.toHttp(response), HttpServletResponse.SC_UNAUTHORIZED);return false;}return super.onAccessDenied(request, response);}/*** 登录失败的回调函数*/@Overrideprotected boolean onLoginFailure(AuthenticationToken token, AuthenticationException ex, ServletRequest request, ServletResponse response) {final boolean isAjax = WebUtil.isAjax();/** 转换标准异常为自定义异常（因框架架构设计问题，只在多Realm情况下，才需要此操作）*/if (token instanceof com.ty.web.shiro.AuthenticationToken) {com.ty.web.shiro.AuthenticationToken authenticationToken = (com.ty.web.shiro.AuthenticationToken) token;ex = null != authenticationToken.getAex()? authenticationToken.getAex() : ex;}try {WebUtil.writeJSON(WebUtils.toHttp(response), AjaxResult.warn(SpringContextHolder.getMessage(ex.getMessage())));} catch (IOException ioe) {log.error(ioe.getMessage(), ioe);} finally {log.warn("登录校验失败::" + (isAjax? "异步":"同步") + "::" + ex.getMessage());}return !isAjax;}/*** 登录成功的回调函数*/@Overrideprotected boolean onLoginSuccess(AuthenticationToken token, Subject subject, ServletRequest request, ServletResponse response) throws Exception {final boolean isAjax = WebUtil.isAjax();// 进入系统前的业务处理this.postHandle(subject, isAjax, request, response);// 输出成功信息try {WebUtil.writeJSON(WebUtils.toHttp(response), AjaxResult.success(subject.getSession().getId()));} catch (IOException ioe) {log.error(ioe.getMessage(), ioe);}return !isAjax? super.onLoginSuccess(token, subject, request, response) : !isAjax;}/*** 获取验证码** @param request* @return 验证码*/protected String getCaptcha(ServletRequest request) {return WebUtils.getCleanParam(request, captchaParam);}/*** 认证后，进入系统前的处理** @param subject* @param isAjax* @throws Exception*/public void postHandle(Subject subject, boolean isAjax, ServletRequest request, ServletResponse response) throws Exception {String loginIp = WebIpUtil.getClientIP();String domain = URLUtils.getPrimaryDomain(WebUtil.getDomain(), true);final SysUser account = (SysUser) subject.getPrincipal();log.info(account.getLoginName() + " 登录成功::" + (isAjax? "异步":"同步") + " :: From " + loginIp);// 此处可写业务代码// 如：获取员工信息等，可在账户表中，添加辅助字段，用于存储业务数据// ......// 更新用户的登录信息(IP & 登录时间)SysUser sysUser = new SysUser();sysUser.setUserId(account.getUserId());sysUser.setLoginTime(new Date());sysUser.setLoginIp(loginIp);sysUserService.update(sysUser);// 记录登录日志loginAuditLogService.save(new LoginAuditLog(account.getLoginName(), loginIp, WebUtil.getUserAgent(), ONE));// 实现登录互踢boolean result = sysUserService.kickOut(account, subject.getSession().getId().toString());if (result) { // 将下线消息通知到同账户的其它客户端tpush.kickOut(account.getLoginName());}}
}

关于实现此需求，核心代码如下：

    /*** 登录成功的回调函数*/@Overrideprotected boolean onLoginSuccess(AuthenticationToken token, Subject subject, ServletRequest request, ServletResponse response) throws Exception {final boolean isAjax = WebUtil.isAjax();// 进入系统前的业务处理this.postHandle(subject, isAjax, request, response);// 输出成功信息try {WebUtil.writeJSON(WebUtils.toHttp(response), AjaxResult.success(subject.getSession().getId()));} catch (IOException ioe) {log.error(ioe.getMessage(), ioe);}return !isAjax? super.onLoginSuccess(token, subject, request, response) : !isAjax;}

此段代码，当移动端以异步请求登录成功后，服务端会将Session ID返回。而Web端登录成功后，走Shiro原生逻辑。

4、实现自己的Logout Filter

package com.ty.web.shiro;import com.ty.cm.model.AjaxResult;
import com.ty.cm.utils.URLUtils;
import com.ty.web.utils.WebUtil;
import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.apache.shiro.web.filter.authc.LogoutFilter;
import org.apache.shiro.web.util.WebUtils;/*** 基于Cookie机制的注销登录服务** @Author Tommy* @Date 2022/1/27*/
public class CookieLogoutFilter extends LogoutFilter {/*** 注销登录业务逻辑处理*/@Overrideprotected boolean preHandle(ServletRequest request, ServletResponse response)throws Exception {getSubject(request, response).logout(); // Shiro内部实现// Cookie 登出处理String domain = URLUtils.getPrimaryDomain(WebUtil.getDomain(), true);WebUtil.removeAllCookie((HttpServletRequest) request, (HttpServletResponse) response, domain);// 登出后的前端交互if (WebUtil.isAjax()) {WebUtil.writeJSON(WebUtils.toHttp(response), AjaxResult.success());} else {issueRedirect(request, response, getRedirectUrl());}return false;}
}

5、【核心】实现自己的Web Session Manager

package com.ty.web.shiro;import jakarta.servlet.ServletRequest;
import jakarta.servlet.ServletResponse;
import jakarta.servlet.http.HttpServletRequest;
import lombok.Data;
import org.apache.commons.lang3.StringUtils;
import org.apache.shiro.web.session.mgt.DefaultWebSessionManager;import java.io.Serializable;/*** 增强 Web Session Manager，支持从Header中获取Session ID** @Author Tommy* @Date 2025/3/11*/
@Data
public class TyWebSessionManager extends DefaultWebSessionManager {private String sessionIdHeader;@Overrideprotected Serializable getSessionId(ServletRequest request, ServletResponse response) {Serializable id = super.getSessionId(request, response);// 若 Shiro 原生获取不到SessionID，则从Header中尝试获取HttpServletRequest httpRequest = (HttpServletRequest) request;String sessionId = httpRequest.getHeader(sessionIdHeader);if (StringUtils.isNotBlank(sessionId)) {id = sessionId;}return id;}
}

若Debug源码后，你会发现，这段代码实现，其实是对原生Shiro的补充，以支持移动端场景。

经过上述的5个步骤，我们的代码工作就完成了，是不是很简单呢。若你想知晓，为什么是这么写，那就只能Debug源码喽！因为这个事情，真的不太好通过Blog文字的方式，讲清楚呢！