企业官网建设流程全解析

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> <groupId>cn.dev33</groupId> <artifactId>sa-token-spring-boot-starter</artifactId> <version>${sa.top.version}</version> </dependency>

版本对应关系（务必按 SpringBoot 大版本选择）：

从源码结构看，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> <groupId>cn.dev33</groupId> <artifactId>sa-token-reactor-spring-boot-starter</artifactId> <version>${sa.top.version}</version> </dependency>

同样的版本对应关系：

• SpringBoot 3.x →sa-token-reactor-spring-boot3-starter
• SpringBoot 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> <groupId>cn.dev33</groupId> <artifactId>sa-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> <groupId>cn.dev33</groupId> <artifactId>sa-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> <groupId>cn.dev33</groupId> <artifactId>sa-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> <groupId>cn.dev33</groupId> <artifactId>sa-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> <groupId>io.quarkiverse.satoken</groupId> <artifactId>quarkus-satoken-resteasy</artifactId> <version>1.30.0</version> </dependency>

8. 裸 Servlet 容器环境（无 Spring）

如果你的项目没有使用 Spring，但 Web 框架基于 ServletAPI 规范，可以引入sa-token-servlet：

<!-- Sa-Token 权限认证（ServletAPI规范） --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-token-servlet</artifactId> <version>${sa.top.version}</version> </dependency>

引入此依赖后需要自行实现SaTokenContext完成请求/响应适配，参见自定义 SaTokenContext 指南。

9. 其它场景：直接使用 core 核心包

如果项目既没有使用 SpringMVC / WebFlux，也不基于 ServletAPI 规范（例如纯 RPC 服务、定时任务、非 Web 应用），可以直接引入 core 核心包：

<!-- Sa-Token 权限认证（core核心包） --> <dependency> <groupId>cn.dev33</groupId> <artifactId>sa-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 环境（ServletAPI）：

implementation 'cn.dev33:sa-token-spring-boot-starter:${sa.top.version}'

• SpringBoot 3.x →sa-token-spring-boot3-starter
• SpringBoot 4.x →sa-token-spring-boot4-starter

WebFlux 环境（Reactor）：

implementation 'cn.dev33:sa-token-reactor-spring-boot-starter:${sa.top.version}'

• SpringBoot 3.x →sa-token-reactor-spring-boot3-starter
• SpringBoot 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.bat（Windows）查看sa-token-doc文档站点；新版文档站对应脚本为preview-doc-new.bat。

六、配套实战：SpringBoot 环境 5 步接入示例

引入依赖只是第一步，下面以 SpringBoot 2.x 为例（完整可运行源码见 sa-token-demo-springboot），演示从零接入登录鉴权的完整链路，这也是依赖选型之后的"落地验证"环节。

1. 添加依赖

参照上文第一节，在pom.xml中加入sa-token-spring-boot-starter（3.x/4.x 项目对应更换为sa-token-spring-boot3-starter/sa-token-spring-boot4-starter）。官方 Demo 的完整依赖配置见 sa-token-demo-springboot/pom.xml。

2. 配置application.yml/application.properties

Sa-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: true

application.properties风格等价写法：

sa-token.token-name=satoken sa-token.timeout=2592000 sa-token.active-timeout=-1 sa-token.is-concurrent=true sa-token.is-share=false sa-token.token-style=uuid sa-token.is-log=true

这些配置项在核心包 SaTokenConfig.java 中均有对应字段与默认值，从源码 getter 集合可以确认框架还支持max-login-count（同一账号最大同时登录数）、max-try-times（登录失败锁定次数）、is-read-body/is-read-header/is-read-cookie（token 读取位置开关）、token-prefix（token 前缀，如 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. 创建测试 Controller

@RestController @RequestMapping("/user/") public class UserController { // 测试登录，浏览器访问： http://localhost:8081/user/doLogin?username=zhang&password=123456 @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.java（doLogin/isLogin/tokenInfo/logout）与 TestController.java（角色权限校验checkRole/checkPermission、注解鉴权@SaCheckLogin/@SaCheckRole/@SaCheckPermission、会话 Session、临时身份切换switchTo、踢人下线kickout等），是熟悉 API 的最佳活教材。鉴权能力可通过注册SaInterceptor拦截器与SaServletFilter全局过滤器打开（见 SaTokenConfigure.java）。

5. 运行与验证

启动项目后，依次访问：

• http://localhost:8081/user/doLogin?username=zhang&password=123456→ 登录成功
• http://localhost:8081/user/isLogin→ 查询当前会话登录状态

至此依赖引入、登录、鉴权的完整闭环已经跑通。

七、获取更多官方示例

官方仓库在sa-token-demo目录下为几乎所有技术点都准备了对应的可运行示例，共60+ Demo，涵盖登录认证、权限认证、SSO 单点登录、OAuth2 统一认证、微服务网关鉴权、API Key 认证、JWT 集成、跨系统参数签名校验等场景，例如：

• sa-token-demo-sso（SSO 单点登录全类型客户端/服务端）
• sa-token-demo-oauth2（OAuth2 服务端/客户端）
• sa-token-demo-jwt（JWT 集成）
• sa-token-demo-apikey（API Key 认证）
• sa-token-demo-springboot-redis（Redis 集成，对应插件见 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