Sa-Token 多环境依赖引入与集成示例全攻略：SpringBoot / WebFlux / Solon / JFinal 等框架接入指南

Sa-Token 多环境依赖引入与集成示例全攻略SpringBoot / WebFlux / Solon / JFinal 等框架接入指南【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token本文以 Sa-Token 官方文档 其它环境引入 Sa-Token 的示例 为骨架结合仓库内 starter 源码与官方 Demo系统梳理不同 Web 框架下 Sa-Token 的依赖选择、配置参数、源码获取与示例运行方式。读完本篇你将能够根据自身技术栈SpringBoot 2.x/3.x/4.x、WebFlux、Solon、JFinal、Jboot、裸 Servlet 容器等准确挑选sa-token-*依赖并完成一次可运行的登录鉴权示例。一、按技术栈选择 Maven 依赖框架选型总览Sa-Token 采用「核心包 环境适配包」的分层设计所有鉴权能力沉淀在sa-token-core中而针对不同 Web 框架提供对应的 starter / plugin 完成环境适配。因此第一步永远是判断自己项目所处的基础框架再引入对应的依赖。以下依赖片段完整继承自官方文档${sa.top.version}请替换为当前发布的 Sa-Token 版本号示例 Demo 中使用1.46.0见 sa-token-demo-springboot/pom.xml 中的sa-token.version属性。1. SpringBoot 环境ServletAPI 体系如果你的框架基于 ServletAPI 构建SpringMVC、SpringBoot 等引入sa-token-spring-boot-starter!-- Sa-Token 权限认证 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-spring-boot-starter/artifactId version${sa.top.version}/version /dependency版本对应关系务必按 SpringBoot 大版本选择你的 SpringBoot 版本应引入的依赖SpringBoot 2.xsa-token-spring-boot-starterSpringBoot 3.xsa-token-spring-boot3-starterSpringBoot 4.xsa-token-spring-boot4-starter从源码结构看sa-token-spring-boot-starter见 pom.xml内部聚合了sa-token-servlet、sa-token-spring-boot-webmvc-reactor-v2v3v4-common与sa-token-jackson并导入sa-token-spring-boot2-dependencies进行版本管理——也就是说引入一个 starter 即可同时获得 Servlet 适配、Spring 集成与 JSON 序列化能力无需再手动拼装多个包。同理3.x / 4.x 各有对应的 starter 模块见 sa-token-starter 目录下的sa-token-spring-boot3-starter、sa-token-spring-boot4-starter。2. WebFlux 环境Reactor 响应式如果你的框架基于 Reactor 模型构建WebFlux、SpringCloud Gateway 等引入响应式集成包!-- Sa-Token 权限认证Reactor响应式集成 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-reactor-spring-boot-starter/artifactId version${sa.top.version}/version /dependency同样的版本对应关系SpringBoot 3.x →sa-token-reactor-spring-boot3-starterSpringBoot 4.x →sa-token-reactor-spring-boot4-starter仓库中 sa-token-starter/sa-token-reactor-spring-boot-starter 及 3.x/4.x 变体即为对应实现官方还提供了 sa-token-demo-webflux、sa-token-demo-webflux-springboot3 等可直接运行的 Demo。3. Solon 集成!-- Sa-Token 整合 Solon -- dependency groupIdcn.dev33/groupId artifactIdsa-token-solon-plugin/artifactId version${sa.top.version}/version /dependency对应实现见 sa-token-starter/sa-token-solon-plugin官方配套 Demo 为 sa-token-demo-solon另提供 Solon Redisson 的 sa-token-demo-solon-redisson详细起步可参考 Solon 环境示例。4. JFinal 集成!-- Sa-Token 整合 JFinal -- dependency groupIdcn.dev33/groupId artifactIdsa-token-jfinal-plugin/artifactId version${sa.top.version}/version /dependency对应实现见 sa-token-starter/sa-token-jfinal-plugin官方 Demo 为 sa-token-demo-jfinal。5. Jboot 集成!-- Sa-Token 整合 Jboot -- dependency groupIdcn.dev33/groupId artifactIdsa-token-jboot-plugin/artifactId version${sa.top.version}/version /dependency对应实现见 sa-token-starter/sa-token-jboot-plugin。6. LoveQQ-Framework 集成!-- Sa-Token 整合 LoveQQ-Framework -- dependency groupIdcn.dev33/groupId artifactIdsa-token-loveqq-boot-starter/artifactId version${sa.top.version}/version /dependency对应实现见 sa-token-starter/sa-token-loveqq-boot-starter。7. Quarkus 集成Quarkus 生态由第三方quarkiverse提供适配版本号为固定值不与 Sa-Token 主版本号联动!-- Sa-Token 整合 Quarkus -- dependency groupIdio.quarkiverse.satoken/groupId artifactIdquarkus-satoken-resteasy/artifactId version1.30.0/version /dependency8. 裸 Servlet 容器环境无 Spring如果你的项目没有使用 Spring但 Web 框架基于 ServletAPI 规范可以引入sa-token-servlet!-- Sa-Token 权限认证ServletAPI规范 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-servlet/artifactId version${sa.top.version}/version /dependency引入此依赖后需要自行实现SaTokenContext完成请求/响应适配参见自定义 SaTokenContext 指南。9. 其它场景直接使用 core 核心包如果项目既没有使用 SpringMVC / WebFlux也不基于 ServletAPI 规范例如纯 RPC 服务、定时任务、非 Web 应用可以直接引入 core 核心包!-- Sa-Token 权限认证core核心包 -- dependency groupIdcn.dev33/groupId artifactIdsa-token-core/artifactId version${sa.top.version}/version /dependency同样需要自定义SaTokenContext实现参考自定义 SaTokenContext 指南。提示sa-token-apikey、sa-token-sso、sa-token-oauth2、sa-token-sign、sa-token-jwt等功能模块均为可选包见 sa-token-plugin 目录需要对应能力时再按需引入框架核心不强制依赖它们。二、Gradle 依赖对照使用 Gradle 构建的项目可直接替换为以下implementation声明版本号${sa.top.version}同样替换为实际版本SpringBoot 环境ServletAPIimplementation cn.dev33:sa-token-spring-boot-starter:${sa.top.version}SpringBoot 3.x →sa-token-spring-boot3-starterSpringBoot 4.x →sa-token-spring-boot4-starterWebFlux 环境Reactorimplementation cn.dev33:sa-token-reactor-spring-boot-starter:${sa.top.version}SpringBoot 3.x →sa-token-reactor-spring-boot3-starterSpringBoot 4.x →sa-token-reactor-spring-boot4-starter其它环境implementation cn.dev33:sa-token-solon-plugin:${sa.top.version} // Solon implementation cn.dev33:sa-token-jfinal-plugin:${sa.top.version} // JFinal implementation cn.dev33:sa-token-jboot-plugin:${sa.top.version} // Jboot implementation cn.dev33:sa-token-loveqq-boot-starter:${sa.top.version} // LoveQQ implementation io.quarkiverse.satoken:quarkus-satoken-resteasy:1.30.0 // Quarkus implementation cn.dev33:sa-token-servlet:${sa.top.version} // 裸 Servlet 容器 implementation cn.dev33:sa-token-core:${sa.top.version} // 其它/核心包三、版本与环境要求JDK 版本v1.8。SpringBoot建议2.0以上低版本可使用 sa-token-demo-springboot-low-version 参考。测试版内测正式版本之外的开发中版本了解最新动态见 Sa-Token 最新版本。如果 Maven 依赖一直无法加载成功请参考依赖拉取失败排查方案官方建议依次尝试重启 IDE、等待依赖下载进度条完成、清理本地仓库~/.m2/repository/cn/dev33下的残缺文件、检查是否因阿里云镜像导致部分 jar 加载失败可注释掉镜像或换用其它镜像源以及父子 Maven 项目中的依赖识别问题。四、jar 包下载除通过构建工具拉取依赖外官方还提供了直连 jar 包下载入口当前提供sa-token-1.6.0.jar的网盘直链下载见原文档。更多版本请前往 Maven 中央仓库搜索sa-token获取。对于历史版本仓库的 update-log.md 记录了各版本的更新要点可作为选择版本的参考。五、获取源码与运行官方示例1. 获取源码Sa-Token 源码托管于 Gitee、GitHub、AtomGit 三个平台可从任意平台克隆。学习测试请拉取master分支dev为开发分支代码随时变动、部分特性不稳定仅适合提交 PR 的开发场景。git clone -b master 对应平台的仓库地址或直接在仓库页使用「克隆 / 下载」功能下载源码压缩包解压后即可使用。2. 从 IDE 导入项目使用 IDEA 选择Open打开源码根目录即可。源码目录结构说明见仓库目录。3. 运行 Demo 示例Sa-Token 本身是一个需要被引入的框架并非完整可运行的传统项目因此不存在运行源码这一说法——真正可运行的是sa-token-demo目录下的各 Demo 项目。打开sa-token-demo目录选择想要运行的示例添加为 Maven 项目运行其中的XxxApplication.java即可。首次在 IDEA 运行可能报错java: 程序包cn.dev33.satoken.apikey不存在。这是因为sa-token-apikey、sso、oauth2、sign、jwt等模块均为可选包IDEA 有时会跳过相关模块编译运行时又找不到这些类。解决方法是先运行 sa-token-demo-first-run 这个 Demo——它强制引入了上述所有模块会引导 IDEA 完成相关模块编译。若仍失败可把报错缺失的模块手动加入当前 Demo 的pom.xml后刷新 Maven 依赖再不行则在项目根目录执行mvn package后重新运行。4. 运行文档如需在本地预览文档可执行根目录的preview-doc.batWindows查看sa-token-doc文档站点新版文档站对应脚本为preview-doc-new.bat。六、配套实战SpringBoot 环境 5 步接入示例引入依赖只是第一步下面以 SpringBoot 2.x 为例完整可运行源码见 sa-token-demo-springboot演示从零接入登录鉴权的完整链路这也是依赖选型之后的落地验证环节。1. 添加依赖参照上文第一节在pom.xml中加入sa-token-spring-boot-starter3.x/4.x 项目对应更换为sa-token-spring-boot3-starter/sa-token-spring-boot4-starter。官方 Demo 的完整依赖配置见 sa-token-demo-springboot/pom.xml。2. 配置application.yml/application.propertiesSa-Token 支持零配置启动同时提供丰富的定制项。官方 Demo 的完整配置见 application.yml核心项如下############## Sa-Token 配置 ############## sa-token: # token 名称同时也是 cookie 名称 token-name: satoken # token 有效期单位秒 默认30天-1 代表永久有效 timeout: 2592000 # token 最低活跃频率单位秒如果 token 超过此时间没有访问系统就会被冻结默认-1 代表不限制永不冻结 active-timeout: -1 # 是否允许同一账号多地同时登录 为 true 时允许一起登录, 为 false 时新登录挤掉旧登录 is-concurrent: true # 在多人登录同一账号时是否共用一个 token 为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token is-share: false # token 风格默认可取值uuid、simple-uuid、random-32、random-64、random-128、tik token-style: uuid # 是否输出操作日志 is-log: trueapplication.properties风格等价写法sa-token.token-namesatoken sa-token.timeout2592000 sa-token.active-timeout-1 sa-token.is-concurrenttrue sa-token.is-sharefalse sa-token.token-styleuuid sa-token.is-logtrue这些配置项在核心包 SaTokenConfig.java 中均有对应字段与默认值从源码 getter 集合可以确认框架还支持max-login-count同一账号最大同时登录数、max-try-times登录失败锁定次数、is-read-body/is-read-header/is-read-cookietoken 读取位置开关、token-prefixtoken 前缀如 Bearer、auto-renew自动续签、jwt-secret-key集成 JWT 时的密钥、is-print启动时是否打印 banner、log-level日志级别等更多能力可按需查阅该类源码理解每个字段的语义。3. 创建启动类SpringBootApplication public class SaTokenDemoApplication { public static void main(String[] args) { SpringApplication.run(SaTokenDemoApplication.class, args); System.out.println(启动成功Sa-Token 配置如下 SaManager.getConfig()); } }4. 创建测试 ControllerRestController RequestMapping(/user/) public class UserController { // 测试登录浏览器访问 http://localhost:8081/user/doLogin?usernamezhangpassword123456 RequestMapping(doLogin) public String doLogin(String username, String password) { // 此处仅作模拟示例真实项目需要从数据库中查询数据进行比对 if(zhang.equals(username) 123456.equals(password)) { StpUtil.login(10001); return 登录成功; } return 登录失败; } // 查询登录状态浏览器访问 http://localhost:8081/user/isLogin RequestMapping(isLogin) public String isLogin() { return 当前会话是否登录 StpUtil.isLogin(); } }官方 Demo 中还提供了更完整的接口矩阵见 LoginController.javadoLogin/isLogin/tokenInfo/logout与 TestController.java角色权限校验checkRole/checkPermission、注解鉴权SaCheckLogin/SaCheckRole/SaCheckPermission、会话 Session、临时身份切换switchTo、踢人下线kickout等是熟悉 API 的最佳活教材。鉴权能力可通过注册SaInterceptor拦截器与SaServletFilter全局过滤器打开见 SaTokenConfigure.java。5. 运行与验证启动项目后依次访问http://localhost:8081/user/doLogin?usernamezhangpassword123456→ 登录成功http://localhost:8081/user/isLogin→ 查询当前会话登录状态至此依赖引入、登录、鉴权的完整闭环已经跑通。七、获取更多官方示例官方仓库在sa-token-demo目录下为几乎所有技术点都准备了对应的可运行示例共60 Demo涵盖登录认证、权限认证、SSO 单点登录、OAuth2 统一认证、微服务网关鉴权、API Key 认证、JWT 集成、跨系统参数签名校验等场景例如sa-token-demo-ssoSSO 单点登录全类型客户端/服务端sa-token-demo-oauth2OAuth2 服务端/客户端sa-token-demo-jwtJWT 集成sa-token-demo-apikeyAPI Key 认证sa-token-demo-springboot-redisRedis 集成对应插件见 sa-token-plugin 下的 redis/redisson 系列如需一次性获取全部示例的压缩包参见Sa-Token 集成示例大全下载。依赖引入与示例就绪后即可按需深入 登录认证 等进阶主题。【免费下载链接】Sa-Token✨ 开源、免费、一站式 Java 权限认证框架让鉴权变得简单、优雅—— 登录认证、权限认证、分布式 Session 会话、微服务网关鉴权、SSO 单点登录、OAuth2.0 统一认证、jwt 集成、API Key 秘钥授权、API 参数签名项目地址: https://gitcode.com/GitHub_Trending/sa/Sa-Token创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考