本文详细介绍了 sa-token 在 java 项目中的使用方法，包括 sa-token 的基本概念、与其他权限框架的比较、基本语法和高级用法，并通过实例讲解了如何在项目中集成和使用 sa-token 。
作为一款轻量级 Java 权限认证框架，Sa-Token 在简化权限管理、提高开发效率方面发挥了重要作用。本文还将深入探讨 Sa-Token 的核心原理，通过内部代码展示其工作机制。最后，总结了 Sa-Token 的优缺点及其在实际开发中的应用场景，为开发者提供全面的指导。
一、Sa-Token 介绍
1. Sa-Token 简介
Sa-Token 是一款轻量级 Java 权限认证框架，旨在解决 Java Web 系统中常见的登录认证、权限验证、Session 会话、单点登录等问题。其核心目标是以最简洁的方式，实现强大的权限控制功能，帮助开发者快速完成权限系统的搭建。
Sa-Token 具有如下优势：
| 优势 | 描述 |
|---|---|
| 简单易用 | API设计简洁明了，易于集成和使用，上手快，学习成本低。 |
| 功能丰富 | 支持多种权限控制需求，满足复杂业务场景。支持登录认证、权限验证、角色验证、Session会话、多账号体系等功能。 |
| 高性能 | 轻量级设计，对系统性能影响小。 |
| 高度可扩展 | 提供丰富的扩展接口，与 Spring、SpringBoot、Solon 等常用框架高度兼容，支持自定义持久化、注解方式验证、单点登录等高级特性。 |
| 社区活跃 | 有良好的社区支持和文档资源。 |
2. Sa-Token原理解析
Sa-Token 的核心原理是通过 Token 机制实现用户的身份认证和权限校验。
其主要工作流程如下：
- 登录认证：用户登录成功后，服务器生成一个全局唯一的 Token，并将其返回给客户端。
- Token存储：Token 与用户身份信息的映射关系保存在服务器的会话中（如 Redis、内存等）。
- 权限验证：客户端请求时携带 Token，服务器根据Token获取用户信息，验证其权限是否满足要求。
- 会话管理：支持 Session 会话管理，可以获取和操作当前会话的属性。
流程图例如下：
3. Sa-Token 与其他权限框架比较
Sa-Token 与其他常见权限框架在学习成本、集成难度上有显著优势：
| 特性 | Sa-Token | Solon Auth |
|---|---|---|
| 学习成本 | 低 | 低 |
| 功能丰富度 | 高 | 低 |
| 集成难度 | 低 | 低 |
| 性能表现 | 高 | 高 |
| 社区支持 | 活跃 | 一般 |
| 扩展性 | 高 | 中 |
二、Sa-Token的基本语法
在实际项目中，Sa-Token 通过简单的配置和API调用，即可实现完整的权限管理功能。以下将通过一个完整的 Solon 示例，演示如何集成和使用Sa-Token。
1. 创建 Solon Web 项目
首先，创建一个新的 Solon 项目，可以使用IDEA的项目向导或 Solon Initializr。
引入必要的依赖：
<dependencies> <dependency> <groupId>org.noeargroupId> <artifactId>solon-webartifactId> dependency> <dependency> <groupId>cn.dev33groupId> <artifactId>sa-token-solon-pluginartifactId> <version>1.44.0version> dependency> dependencies>
2. 配置 Sa-Token：app.yml
# Sa-Token配置，可根据需要进行调整 sa-token: # token有效期，单位秒，默认30天 timeout: 2592000 # 是否打开二级登录校验 open-safe: false
3. 配置拦截器
创建配置类，添加Sa-Token的拦截器，以拦截请求并进行权限验证。SaTokenConfig.java
import cn.dev33.satoken.solon.integration.SaTokenInterceptor; import org.noear.solon.annotation.Configuration; import org.noear.solon.annotation.Managed; @Configuration public class SaTokenConfig { @Managed(index = -100) //-100，是顺序位（低值优先） public SaTokenInterceptor saTokenInterceptor() { return new SaTokenInterceptor(); //用于支持规划处理及注解处理 } }
4. 登录认证
创建登录接口，实现用户登录功能。LoginController.java
import cn.dev33.satoken.stp.StpUtil; import org.noear.solon.annotation.Controller; import org.noear.solon.annotation.Mapping; import org.noear.solon.annotation.Param; import org.noear.solon.annotation.Post; @Controller public class LoginController { @Post @Mapping("/login") public String login(@Param String username, @Param String password) { // 1. 校验用户名和密码（这里模拟一个简单的校验） if ("admin".equals(username) && "123456".equals(password)) { // 2. 登录，保存用户ID为10001 StpUtil.login(10001); return "登录成功，Token：" + StpUtil.getTokenValue(); } return "用户名或密码错误"; } }
说明：
- 调用
StpUtil.login(10001)
方法，实现登录操作，参数为用户的唯一标识 ID。 - 登录成功后，可以通过
StpUtil.getTokenValue()
获取当前会话的 Token。
5. 权限验证
创建需要权限验证的接口，例如获取用户信息的接口。UserController.java
import cn.dev33.satoken.annotation.SaCheckPermission; import cn.dev33.satoken.stp.StpUtil; import org.noear.solon.annotation.Controller; import org.noear.solon.annotation.Get; import org.noear.solon.annotation.Mapping; import org.noear.solon.annotation.Post; @Controller @Mapping("/user") public class UserController { // 查询用户信息，需登录 @Get @Mapping("/info") public String getUserInfo() { // 校验是否登录 StpUtil.checkLogin(); // 获取用户ID int userId = StpUtil.getLoginIdAsInt(); return "当前用户信息，ID：" + userId; } // 修改用户信息，需有权限"user:update" @SaCheckPermission("user:update") @Post @Mapping("/update") public String updateUser() { return "用户信息更新成功"; } }
说明：
- 使用
StpUtil.checkLogin()
方法手动校验登录状态。 - 使用
@SaCheckPermission("user:update")注解，声明该接口需要权限user:update。
6. 角色验证
如果需要基于角色进行权限控制，可以使用
@SaCheckRole注解。
import cn.dev33.satoken.annotation.SaCheckRole; import org.noear.solon.annotation.Controller; import org.noear.solon.annotation.Get; import org.noear.solon.annotation.Mapping; @Controller @Mapping("/admin") public class AdminController { // 仅管理员角色可访问 @SaCheckRole("admin") @Get @Mapping("/dashboard") public String adminDashboard() { return "欢迎进入管理员控制台"; } }
7. 自定义权限验证逻辑
需要自定义获取用户权限和角色的逻辑，可以实现
StpInterface接口。StpInterfaceImpl.java
import cn.dev33.satoken.stp.StpInterface; import org.noear.solon.annotation.Managed; import java.util.ArrayList; import java.util.List; @Managed public class StpInterfaceImpl implements StpInterface { // 返回一个用户所拥有的权限码集合 @Override public ListgetPermissionList(Object loginId, String loginKey) { // 模拟从数据库获取权限 List permissionList = new ArrayList<>(); if("10001".equals(loginId.toString())) { permissionList.add("user:update"); permissionList.add("user:delete"); } return permissionList; } // 返回一个用户所拥有的角色标识集合 (权限与角色可分开校验) @Override public List getRoleList(Object loginId, String loginKey) { // 模拟从数据库获取角色 List roleList = new ArrayList<>(); if("10001".equals(loginId.toString())) { roleList.add("admin"); } return roleList; } }
说明：
- 实现
getPermissionList
方法，返回指定用户的权限列表。 - 实现
getRoleList
方法，返回指定用户的角色列表。
8. 会话管理
Sa-Token 提供了会话管理功能，可以在 Session 中存储和获取数据。
import cn.dev33.satoken.session.SaSession; import cn.dev33.satoken.stp.StpUtil; public void sessionDemo() { // 获取当前会话的Session SaSession session = StpUtil.getSession(); // 存储数据 session.set("name", "张三"); session.set("email", "zhangsan@example.com"); // 获取数据 String name = session.getString("name"); String email = session.getString("email"); // 输出 System.out.println("姓名：" + name); System.out.println("邮箱：" + email); }
9. 踢人下线
可以通过用户ID强制用户下线。
// 将用户ID为10001的用户踢下线 StpUtil.logoutByLoginId(10001); // 检查用户是否已被踢下线 boolean isLogout = StpUtil.isLogin(); System.out.println("用户是否登录：" + isLogout);
10. 注销登录
用户主动注销登录，可以调用
StpUtil.logout()方法。
// 注销登录 StpUtil.logout(); // 检查登录状态 boolean isLogin = StpUtil.isLogin(); System.out.println("用户是否登录：" + isLogin);
三、Sa-Token 的高级用法
1. 自定义持久化
Sa-Token 默认使用内存来存储 Token 信息，在分布式环境中，可以使用 Redis 作为持久化介质。
引入Redis依赖：
<dependency> <groupId>cn.dev33groupId> <artifactId>sa-token-redisxartifactId> <version>1.44.0version> dependency> <dependency> <groupId>cn.dev33groupId> <artifactId>sa-token-snack3artifactId> <version>1.44.0version> dependency>
配置 Redis Dao 连接信息：app.yml
sa-token: # 不同的扩展插件，配置可能会不同 dao: server: "localhost:6379" password: 123456 db: 1 maxTotal: 200
配置 Redis 持久化：
import cn.dev33.satoken.dao.SaTokenDao; import cn.dev33.satoken.dao.SaTokenDaoForRedisx; import org.noear.solon.annotation.Configuration; import org.noear.solon.annotation.Inject; import org.noear.solon.annotation.Managed; @Configuration public class SaTokenDaoConfig { @Managed public SaTokenDao saTokenDaoInit(@Inject("${sa-token.dao}") SaTokenDaoForRedisx saTokenDao) { return saTokenDao; } }
2. 单点登录（SSO）
Sa-Token提供了SSO模块，可以快速实现单点登录功能。
引入SSO依赖：
<dependency> <groupId>cn.dev33groupId> <artifactId>sa-token-ssoartifactId> <version>1.44.0version> dependency>
配置 SSO 相关参数：app.yml
sa-token: sso-client: client: demo-app server-url: http://sso-server.com is-http: true secret-key: SSO-C3-kQwIOrYvnXmSDkwEiFngrKidMcdrgKor
3. OAuth2.0支持
Sa-Token也支持
OAuth2.0协议，可以实现与第三方平台的对接。
引入
OAuth2.0依赖：
<dependency> <groupId>cn.dev33groupId> <artifactId>sa-token-oauth2artifactId> <version>1.44.0version> dependency>
配置
OAuth2.0参数和实现授权流程（此处略，具体可参考官方文档）。
4. 多账号体系
如果系统中存在多种身份的用户，例如普通用户、管理员、商家等，可以使用多账号体系进行区分。
登录指定账号体系：
// 管理员登录，loginKey为"admin" StpUtil.login(10001, "admin");
检查登录状态：
// 检查当前账号体系下是否登录 boolean isLogin = StpUtil.isLogin("admin");
权限验证：
// 在指定账号体系下进行权限验证 StpUtil.checkPermission("user:update", "admin");
四、Sa-Token使用总结
Sa-Token 是一款轻量级的 Java 权限认证框架，因其简单易用和功能丰富而备受开发者青睐。它以简洁明了的API设计，使得集成和使用变得非常方便，开发者可以快速上手，降低了学习成本。Sa-Token 支持多种权限控制需求，满足复杂业务场景，包括登录认证、权限验证、角色验证、Session 会话、多账号体系等功能，全面覆盖了权限管理的各个方面。其轻量级的设计对系统性能影响小，适用于高并发的应用环境。此外，Sa-Token 提供了丰富的扩展接口，与 Spring、SpringBoot、Solon 等常用框架高度兼容，支持自定义持久化、注解方式验证、单点登录等高级特性，方便开发者根据项目需求进行定制开发。活跃的社区支持和丰富的文档资源也使得开发者能够轻松获取帮助和指导。
由于这些优势，Sa-Token 非常适 Web 项目的快速开发和微服务架构下的权限管理。当项目需要快速搭建权限系统时，选择 Sa-Token 是一个理想的方案。然而，在使用过程中需要注意 Token 的安全性，防止泄露带来风险；对于高并发场景，建议使用Redis等持久化介质来提高系统性能和扩展性；同时，关注 Sa-Token 的版本更新，及时获取新功能和安全补丁，以确保系统的安全性和稳定性。
此文参考自：https://www.cnblogs.com/liuguangzhi/articles/18415627
源码地址：点击下载
