Sa-Token v1.41.0 发布 🚀，来看看有没有令你心动的功能！

Sa-Token 是一个轻量级 Java 权限认证框架，主要解决：登录认证 、权限认证 、单点登录 、OAuth2.0 、微服务网关鉴权 等一系列权限相关问题。🔐

目前最新版本 v1.41.0 已推送至 Maven 中央仓库 🎉，大家可以通过如下方式引入：

<!-- Sa-Token 权限认证 -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.41.0</version>
</dependency>

该版本包含大量 ⛏️️️新增特性、⛏️底层重构、⛏️️️代码优化 等，下面容我列举几条比较重要的更新内容供大家参阅：

🛡️ 更新点1：防火墙模块新增 hooks 扩展机制

本次更新针对防火墙新增了多条校验规则，之前的规则为：

• path 白名单放行。
• path 黑名单拦截。
• path 危险字符校验。

本次新增规则为：

• path 禁止字符校验。
• path 目录遍历符检测（优化了检测算法）。
• 请求 host 检测。
• 请求 Method 检测。
• 请求 Header 头检测。
• 请求参数检测。

并且本次更新开放了 hooks 机制，允许开发者注册自定义的校验规则 🛠️，参考如下：

@PostConstruct
public void saTokenPostConstruct() {
    // 注册新 hook 演示，拦截所有带有 pwd 参数的请求，拒绝响应 
    SaFirewallStrategy.instance.registerHook((req, res, extArg)->{
        if(req.getParam("pwd") != null) {
            throw new FirewallCheckException("请求中不可包含 pwd 参数");
        }
    });
}

文档直达地址：Sa-Token 防火墙 🔗

💡 更新点2：新增基于 SPI 机制的插件体系

之前在 Sa-Token 中也有插件体系，不过都是利用 SpringBoot 的 SPI 机制完成组件注册的。

这种注册机制有一个问题，就是插件只能在 SpringBoot 环境下正常工作，在其它环境，比如 Solon 项目中，就只能手动注册插件才行 😫。

也就是说，严格来讲，这些插件只能算是 SpringBoot 的插件，而非 Sa-Token 框架的插件 🌐。

为了提高插件的通用性，Sa-Token 设计了自己的 SPI 机制，使得这些插件可以在更多的项目环境下正常工作 🚀。

第一步：实现插件注册类，此类需要 implements SaTokenPlugin 接口 👨💻：

/**
 * SaToken 插件安装：插件作用描述
 */
public class SaTokenPluginForXxx implements SaTokenPlugin {
    @Override
    public void install() {
        // 书写需要在项目启动时执行的代码，例如：
        // SaManager.setXxx(new SaXxxForXxx());
    }
}

第二步：在项目的 resources\META-INF\satoken\ 文件夹下 📂 创建 cn.dev33.satoken.plugin.SaTokenPlugin 文件，内容为该插件注册类的完全限定名：

cn.dev33.satoken.plugin.SaTokenPluginForXxx

这样便可以在项目启动时，被 Sa-Token 插件管理器加载到此插件，执行插件注册类的 install 方法，完成插件安装 ✅。

文档直达地址：Sa-Token 插件开发指南 🔗

🎛️ 更新点3：重构缓存体系，将数据读写与序列化操作分离

在之前的版本中，Redis 集成通常和具体的序列化方式耦合在一起，这不仅让 Redis 相关插件产生大量的重复冗余代码，也让大家在选择 Redis 插件时严重受限。⚠️

本次版本更新彻底重构了此模块，将数据读写与序列化操作分离，使其每一块都可以单独自定义实现类，做到灵活扩展 ✨，例如：

• 1️⃣ SaTokenDao 数据读写可以选择：RedisTemplate、Redisson、ConcurrentHashMap、Hutool-Timed-Cache 等不同实现类。
• 2️⃣ SaSerializerTemplate 序列化器可以选择：Base64编码、Hex编码、ISO-8859-1编码、JSON序列化等不同方式。
• 3️⃣ JSON 序列化可以选择：Jackson、Fastjson、Snack3 等组件。

所有实现类均可以按需选择，自由搭配，大大提高灵活性🏗️。

⚙️️ 更新点4：SaLoginParameter 登录参数类新增大量配置项

SaLoginParameter (前SaLoginModel) 用于控制登录操作中的部分细节行为，本次新增的配置项有：

• isConcurrent：决定是否允许同一账号多地同时登录（为 true 时允许一起登录, 为 false 时新登录挤掉旧登录）。🌍
• isShare：在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token）。🔄
• maxLoginCount：同一账号最大登录数量，超出此数量的客户端将被自动注销，-1代表不限制数量。🚫
• maxTryTimes：在创建 token 时的最高循环次数，用于保证 token 唯一性（-1=不循环尝试，直接使用。⏳
• deviceId：此次登录的客户端设备id，用于判断后续某次登录是否为可信任设备。📱
• terminalExtraData：本次登录挂载到 SaTerminalInfo 的自定义扩展数据。📦

以上大部分配置项在之前的版本中也有支持，不过它们都被定义在了全局配置类 SaTokenConfig 之上，本次更新支持在 SaLoginParameter 中定义这些配置项，

这将让登录策略的控制变得更加灵活。✨

🚪 更新点5：新增 SaLogoutParameter 注销参数类

SaLogoutParameter 用于控制注销操作中的部分细节行为️，例如：

通过 Range 参数决定注销范围 🎯：

// 注销范围： TOKEN=只注销当前 token 的会话，ACCOUNT=注销当前 token 指向的 loginId 其所有客户端会话
StpUtil.logout(new SaLogoutParameter().setRange(SaLogoutRange.TOKEN));

通过 DeviceType 参数决定哪些登录设备类型参与注销 💻：

// 指定 10001 账号，所有 PC 端注销下线，其它端如 APP 端不受影响 
StpUtil.logout(10001, new SaLogoutParameter().setDeviceType("PC"));

还有其它参数此处暂不逐一列举，文档直达地址：Sa-Token 登录参数 & 注销参数 🔗

🐞 更新点6：修复 StpUtil.setTokenValue("xxx")、loginParameter.getIsWriteHeader() 空指针的问题。

这个没啥好说的，有 bug 🐛 必须修复。

fix issue：#IBKSM0 🔗

✨ 更新点7：API 参数签名模块升级

• 1、新增了 @SaCheckSign 注解，现在 API 参数签名模块也支持注解鉴权了。🆕
• 2、新增自定义签名的摘要算法，现在不仅可以 md5 算法计算签名，也支持 sha1、sha256 等算法了。🔐
• 3、新增多应用模式：

多应用模式就是指，允许在对接多个系统时分别使用不同的秘钥等配置项，配置示例如下 📝：

sa-token: 
    # API 签名配置 多应用模式
    sign-many:
        # 应用1
        xm-shop:
            secret-key: 0123456789abcdefg
            digest-algo: md5
        # 应用2
        xm-forum:
            secret-key: 0123456789hijklmnopq
            digest-algo: sha256
        # 应用3
        xm-video:
            secret-key: 12341234aaaaccccdddd
            digest-algo: sha512

然后在签名时通过指定 appid 的方式获取对应的 SignTemplate 进行操作 👨💻：

// 创建签名示例
String paramStr = SaSignMany.getSignTemplate("xm-shop").addSignParamsAndJoin(paramMap);

// 校验签名示例
SaSignMany.getSignTemplate("xm-shop").checkRequest(SaHolder.getRequest());

⚡ 更新点8：新增 sa-token-caffeine 插件，用于整合 Caffeine

Caffeine 是一个基于 Java 的高性能本地缓存库，本次新增 sa-token-caffeine 插件用于将 Caffeine 作为 Sa-Token 的缓存层，存储会话鉴权数据。🚀

这进一步丰富了 Sa-Token 的缓存层插件生态。🌱

<!-- Sa-Token 整合 Caffeine -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-caffeine</artifactId>
    <version>1.41.0</version>
</dependency>

🎪 更新点9：新增 sa-token-serializer-features 序列化扩展包

引入此插件可以为 Sa-Token 提供一些有意思的序列化方案。（娱乐向，不建议上生产 🎭）

例如：以base64 编码，采用：元素周期表 🧪、特殊符号 🔣、或 emoji 😊 作为元字符集存储数据 ：

📜 完整更新日志

除了以上提到的几点以外，还有更多更新点无法逐一详细介绍，下面是 v1.41.0 版本的完整更新日志：

• core:
  • 修复：修复 StpUtil.setTokenValue("xxx")、loginParameter.getIsWriteHeader() 空指针的问题。 fix: #IBKSM0
  • 修复：将 SaDisableWrapperInfo.createNotDisabled() 默认返回值封禁等级改为 -2，以保证向之前版本兼容。
  • 新增：新增基于 SPI 的插件体系。 [重要]
  • 重构：JSON 转换器模块。 [重要]
  • 新增：新增 serializer 序列化模块，控制 Object 与 String 的序列化方式。 [重要]
  • 重构：重构防火墙模块，增加 hooks 机制。 [重要]
  • 新增：防火墙新增：请求 path 禁止字符校验、Host 检测、请求 Method 检测、请求头检测、请求参数检测。重构目录遍历符检测算法。
  • 重构：重构 SaTokenDao 模块，将序列化与存储操作分离。 [重要]
  • 重构：重构 SaTokenDao 默认实现类，优化底层设计。
  • 新增：isLastingCookie 配置项支持在全局配置中定义了。
  • 重构：SaLoginModel -> SaLoginParameter。 [不向下兼容]
  • 重构：TokenSign -> SaTerminalInfo。 [不向下兼容]
  • 新增：SaTerminalInfo 新增 extraData 自定义扩展数据设置。
  • 新增：SaLoginParameter 支持配置 isConcurrent、isShare、maxLoginCount、maxTryTimes。
  • 新增：新增 SaLogoutParameter，用于控制注销会话时的各种细节。 [重要]
  • 新增：新增 StpLogic#isTrustDeviceId 方法，用于判断指定设备是否为可信任设备。
  • 新增：新增 StpUtil.getTerminalListByLoginId(loginId)、StpUtil.forEachTerminalList(loginId) 方法，以更方便的实现单账号会话管理。
  • 升级：API 参数签名配置支持自定义摘要算法。
  • 新增：新增 @SaCheckSign 注解鉴权，用于 API 签名参数校验。
  • 新增：API 参数签名模块新增多应用模式。 fix: #IAK2BI, #I9SPI1, #IAC0P9 [重要]
  • 重构：全局配置 is-share 默认值改为 false。 [不向下兼容]
  • 重构：踢人下线、顶人下线默认将删除对应的 token-session 对象。
  • 优化：优化注销会话相关 API。
  • 重构：登录默认设备类型值改为 DEF。 [不向下兼容]
  • 重构：BCrypt 标注为 @Deprecated。
  • 新增：sa-token-quick-login 支持 SpringBoot3 项目。 fix: #IAFQNE、#673
  • 新增：SaTokenConfig 新增 replacedRange、overflowLogoutMode、logoutRange、isLogoutKeepFreezeOps、isLogoutKeepTokenSession 配置项。
• OAuth2：
  • 重构：重构 sa-token-oauth2 插件，使注解鉴权处理器的注册过程改为 SPI 插件加载。
• 插件：
  • 新增：sa-token-serializer-features 插件，用于实现各种形式的自定义字符集序列化方案。
  • 新增：sa-token-fastjson 插件。
  • 新增：sa-token-fastjson2 插件。
  • 新增：sa-token-snack3 插件。
  • 新增：sa-token-caffeine 插件。
• 单元测试：
  • 新增：sa-token-json-test json 模块单元测试。
  • 新增：sa-token-serializer-test 序列化模块单元测试。
• 文档：
  • 新增：QA "多个项目共用同一个 redis，怎么防止冲突？"
  • 优化：补全 OAuth2 模块遗漏的相关配置项。
  • 优化：优化 OAuth2 简述章节描述文档。
  • 优化：完善 "SSO 用户数据同步 / 迁移" 章节文档。
  • 修正：补全项目目录结构介绍文档。
  • 新增：文档新增 "登录参数 & 注销参数" 章节。
  • 优化：优化"技术求助"按钮的提示文字。
  • 新增：新增 preview-doc.bat 文件，一键启动文档预览。
  • 完善：完善 Redis 集成文档。
  • 新增：新增单账号会话查询的操作示例。
  • 新增：新增顶人下线 API 介绍。
  • 新增：新增 自定义序列化插件 章节。
• 其它：
  • 新增：新增 sa-token-demo/pom.xml 以便在 idea 中一键导入所有 demo 项目。
  • 删除：删除不必要的 .gitignore 文件
  • 重构：重构 sa-token-solon-plugin 插件。
  • 新增：新增设备锁登录示例。

更新日志在线文档直达链接：https://sa-token.cc/doc.html#/more/update-log

🌟 其它

代码仓库地址：https://gitee.com/dromara/sa-token

框架功能结构图：