Solon 权限认证之 Sa-Token 的使用与详解

昝梓菱 · 2025-11-6 11:08:28

本文详细介绍了 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-TokenSolon Auth学习成本低低功能丰富度高低集成难度低低性能表现高高社区支持活跃一般扩展性高中二、Sa-Token的基本语法

在实际项目中，Sa-Token 通过简单的配置和API调用，即可实现完整的权限管理功能。以下将通过一个完整的 Solon 示例，演示如何集成和使用Sa-Token。
1. 创建 Solon Web 项目

首先，创建一个新的 Solon 项目，可以使用IDEA的项目向导或 Solon Initializr。
引入必要的依赖：

<dependencies>
<dependency>
<groupId>org.noear</groupId>
solon-web</artifactId>
</dependency>
<dependency>
<groupId>cn.dev33</groupId>
sa-token-solon-plugin</artifactId>
<version>1.44.0</version>
</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 List<String> getPermissionList(Object loginId, String loginKey) {
// 模拟从数据库获取权限
List<String> permissionList = new ArrayList<>();
if("10001".equals(loginId.toString())) {
permissionList.add("user:update");
permissionList.add("user:delete");
}
return permissionList;
}
// 返回一个用户所拥有的角色标识集合 (权限与角色可分开校验)
@Override
public List<String> getRoleList(Object loginId, String loginKey) {
// 模拟从数据库获取角色
List<String> 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.dev33</groupId>
sa-token-redisx</artifactId>
<version>1.44.0</version>
</dependency>
<dependency>
<groupId>cn.dev33</groupId>
sa-token-snack3</artifactId>
<version>1.44.0</version>
</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.dev33</groupId>
sa-token-sso</artifactId>
<version>1.44.0</version>
</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.dev33</groupId>
sa-token-oauth2</artifactId>
<version>1.44.0</version>
</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

来源：程序园用户自行投稿发布，如果侵权，请联系站长删除
免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！

百谖夷 · 2025-11-28 00:55:40

收藏一下不知道什么时候能用到

龙梨丝 · 2025-11-30 17:05:03

谢谢分享，辛苦了

账号		自动登录	找回密码
密码			立即注册

Solon 权限认证之 Sa-Token 的使用与详解

相关帖子

回复

签约作者

Solon 权限认证之 Sa-Token 的使用与详解

相关帖子

相关推荐

回复

签约作者