本文详细介绍了 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 具有如下优势：

2. Sa-Token原理解析

Sa-Token 的核心原理是通过 Token 机制实现用户的身份认证和权限校验。

其主要工作流程如下：

• 登录认证：用户登录成功后，服务器生成一个全局唯一的 Token，并将其返回给客户端。
• Token存储：Token 与用户身份信息的映射关系保存在服务器的会话中（如 Redis、内存等）。
• 权限验证：客户端请求时携带 Token，服务器根据Token获取用户信息，验证其权限是否满足要求。
• 会话管理：支持 Session 会话管理，可以获取和操作当前会话的属性。

流程图例如下：

3. Sa-Token 与其他权限框架比较

Sa-Token 与其他常见权限框架在学习成本、集成难度上有显著优势：

二、Sa-Token的基本语法

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

1. 创建 Solon Web 项目

首先，创建一个新的 Solon 项目，可以使用IDEA的项目向导或 Solon Initializr。

引入必要的依赖：

<dependencies>
    <!-- Solon  Web -->
    <dependency>
        <groupId>org.noear</groupId>
        <artifactId>solon-web</artifactId>
    </dependency>

    <!-- Sa-Token核心依赖 -->
    <dependency>
        <groupId>cn.dev33</groupId>
        <artifactId>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>
    <artifactId>sa-token-redisx</artifactId>
    <version>1.44.0</version>
</dependency>

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>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>
    <artifactId>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>
    <artifactId>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