Apache Shiro 3.0.1 介绍与选型指南

本文为 A1 认知篇：面向软件选型与架构认知场景，系统介绍 Apache Shiro 3.0.1 的定位、核心架构、功能特性、适用场景与同类对比。全部信息来自官方资料溯源（官网、官方博客、官方下载目录、Maven Central），不包含本地安装与运行实测内容。

一、信息基准

• 查询日期：2026-10-18
• 本次介绍版本：Apache Shiro 3.0.1（官方当前最新稳定版，官方博客发布于 2026-08-24）
• 项目状态：Apache 顶级项目（TLP），2010 年 9 月毕业；前身 JSecurity。
• 版本线现状（重要）：官方已明确 v1 与 v2 版本线生命周期终止——按官方通告，2024-02-28 起 v1 被 v2 取代，2026-06-29 起 v2 被 v3 取代；仍在维护的是 3.x 线（3.0.0 于 2026-06-29 发布，3.0.1 为其补丁版）。
• 版本判定依据：Maven Central org.apache.shiro:shiro-core 与 shiro-spring-boot-starter maven-metadata.xml latest/release 均为 3.0.1；官方发行目录 downloads.apache.org/shiro/ 最新发行目录亦为 3.0.1；官方博客与仓库发布流交叉一致。

官方来源清单：

二、软件概述

本文介绍的是 Apache Shiro 3.0.1。官方定位：强大且易用的 Java 应用安全框架，覆盖四大基石——认证（Authentication）、授权（Authorization）、企业级会话管理（Session Management）与密码学（Cryptography）。Shiro 以直观 API 与「默认合理」的配置哲学著称，可运行于从命令行应用到大型企业 Web/集群应用的任意环境，不依赖特定应用服务器。

3.0 线是一次重大演进（官方 3.0.0 公告原文要点）：最低基线提升至 JDK 17；命名空间全面切换至 Jakarta EE 9/10/11+（不再支持 javax.* 命名空间）；适配 Spring 6/7 与 Spring Boot 3/4、Guice 7/8；在 JDK 25+ 上以 Scoped Values 替代 ThreadLocal 管理 Subject 与 SecurityManager；改进 Shiro 原生会话实现的线程安全性。同时包含强化默认值的安全变化（详见 4.2）与破坏性 API 变更（PrincipalCollection 默认实现改为不可变的 ImmutablePrincipalCollection）。升级用户需按 3.0 迁移要求评估（1.x/2.x 已 EOL）。

三、核心架构

3.1 Subject 与 SecurityManager

官方架构的核心是两个概念：Subject 是与当前应用交互主体的安全视角 API（登录、角色/权限判断、会话获取均经 Subject 完成）；SecurityManager 是 Shiro 内部的安全组件协调中枢，将认证、授权、会话、缓存、Realm 等组件编排为整体。3.0 起，Subject/SecurityManager 的运行时绑定在 JDK 25+ 改用 Scoped Values 实现，提升线程安全与并发性能。

3.2 Realm：安全数据源桥接层

Realm 是连接 Shiro 与应用安全数据（用户、角色、权限）的桥：官方与社区提供 JDBC、LDAP、Active Directory 等多种 Realm 实现，也可按 AuthorizingRealm 等基类自定义。认证时 SecurityManager 调用 Realm 获取凭据完成比对，授权时经 Realm 解析角色与权限。

3.3 会话与会话管理

Shiro 内置会话体系（Session/SessionManager），官方强调会话可在「任何环境」使用——不依赖 Web 服务器或 EJB 的会话机制，并支持分布式会话存储（经 CacheManager 对接缓存设施）。3.0 对 SimpleSession、SimpleSessionFactory、CachingSessionDAO 等原生会话实现做了线程安全强化。

3.4 Web 过滤器链与框架集成

Web 场景下，Shiro 以 Servlet 过滤器（ShiroFilterChainDefinition 定义 URL 到过滤器的映射）方式织入认证/授权逻辑；与 Spring Boot 集成经 shiro-spring-boot-starter 完成，与 Guice 有官方集成模块。3.0 适配 Jakarta EE 命名空间后，可运行于 Jakarta EE 9/10/11+ 与 Spring Boot 3/4 应用。

四、功能特性

4.1 四大基石

1. 认证：跨一个或多个可插拔数据源（LDAP、JDBC、Active Directory 等）完成登录校验。
2. 授权：基于角色与细粒度权限（支持 资源:操作:实例 形式的权限字符串）的访问控制。
3. 会话管理：环境无关的会话 API 与集群会话支持。
4. 密码学：哈希、加密与盐值处理的易用封装（以 AesCipherService 等服务类提供）。

4.2 3.0 线强化默认值的安全变化（官方公告要点）

• 路径匹配默认大小写不敏感（hardened by default）；
• 默认过滤器链加入 NoAccessFilter（破坏性变更，未匹配默认拒绝）；
• 默认放行 CORS 预检请求。

4.3 工程特性

• 与 Spring/Spring Boot/Guice 的官方集成；
• INI/配置文件到编程式配置的灵活配置模型；
• 可插拔缓存（CacheManager）与事件总线。

五、快速上手

以下内容引自官方《10 Minute Tutorial》（已更新至 3.0.1 示例），属官方资料整理，本文未在本地执行实测。完整教程见：https://shiro.apache.org/10-minute-tutorial.html

5.1 配置（官方教程 shiro.ini 样例，节选）

[users]
# 用户 lonestarr，密码 vespa，角色 goodguy
lonestarr = vespa, goodguy

[roles]
# 'goodguy' 角色允许 'drive' 'winnebago' 的 'eagle5' 实例
goodguy = winnebago:drive:eagle5

5.2 核心 API（官方教程代码范式）

Subject currentUser = SecurityUtils.getSubject();   // 获取当前 Subject
if (!currentUser.isAuthenticated()) {
    UsernamePasswordToken token = new UsernamePasswordToken("lonestarr", "vespa");
    token.setRememberMe(true);
    currentUser.login(token);                       // 认证（失败抛 AuthenticationException）
}
currentUser.hasRole("schwartz");                    // 角色判断
currentUser.isPermitted("lightsaber:wield");        // 权限判断
currentUser.logout();                               // 登出

官方教程以源码分发包内的 quickstart 工程为例（3.0.1 发行包），经 Maven 构建后在 main 方法中演示上述 API；Spring Boot 应用则以 shiro-spring-boot-starter（版本 3.0.1）接入过滤器链与 Realm 配置。

六、适用场景与限制

6.1 适用场景

1. 非 Spring 独占的 Java 应用安全：命令行、桌面、服务端任意 Java 应用需要轻量直观的认证授权与会话能力。
2. Spring Boot 3/4 新项目：偏好 Shiro 简洁模型、无需 Spring Security 全家桶复杂度的团队（3.0 起官方适配 Spring Boot 3/4）。
3. 环境无关会话：需要脱离 Web 会话机制、统一会话管理面（含缓存集成）的场景。
4. 存量 1.x/2.x 用户：官方已宣布 1.x/2.x EOL，应规划向 3.x 迁移（JDK 17+、Jakarta 命名空间）。

6.2 限制

1. JDK 基线：3.0 要求 JDK 17+，存量低版本 JDK 应用无法直接升级。
2. 命名空间断层：仅支持 Jakarta EE 9/10/11+，javax.* 时代的运行时环境与框架需评估兼容性。
3. 默认行为变化：NoAccessFilter 与大小写不敏感路径匹配等强化默认值属破坏性变更，升级需回归安全策略。
4. 生态体量：第三方示例与集成资料少于 Spring Security。

七、同类选型对比

对比对象：Spring Security、Jakarta Security、JAAS。数据为 2026-10-18 联网实查，来源逐项标注。

来源说明：Shiro/Spring Security stars 取自 shields.io 徽章实查；Spring Security 版本取自 Maven Central maven-metadata.xml；Shiro 发版时间取自官方博客；Jakarta Security 与 JAAS 无独立 GitHub 版本流，如实标注。

选型建议：Spring 全家桶深度用户且需要最大生态与文档覆盖选 Spring Security；追求标准可移植、绑定 Jakarta EE 运行时选 Jakarta Security；需要环境无关、直观易用且四大安全能力开箱即用的 Java 应用（尤其非纯 Spring 栈）选 Shiro 3.x——但务必注意 1.x/2.x 已 EOL，新项目应直接采用 3.x 并确认 JDK 17+ 基线；JAAS 不建议用于新项目。

八、参考链接

1. Apache Shiro 官网：https://shiro.apache.org/
2. 3.0.0 发布公告：https://shiro.apache.org/blog/2026/06/apache-shiro-300-released.html
3. 3.0.1 发布公告：https://shiro.apache.org/blog/2026/08/apache-shiro-301-released.html
4. 官方 10 分钟教程：https://shiro.apache.org/10-minute-tutorial.html
5. 官方发行目录：https://downloads.apache.org/shiro/
6. Maven Central（org.apache.shiro）：https://repo1.maven.org/maven2/org/apache/shiro/
7. Spring Security 官网：https://spring.io/projects/spring-security
8. Jakarta Security 规范页：https://jakarta.ee/specifications/security/