​

本文详细介绍了Sa-Token在Java项目中的使用方法，包括Sa-Token的基本概念、与其他权限框架的比较、基本语法和高级用法，并通过实例讲解了如何在项目中集成和使用Sa-Token。作为一款轻量级Java权限认证框架，Sa-Token在简化权限管理、提高开发效率方面发挥了重要作用。本文还将深入探讨Sa-Token的核心原理，通过内部代码展示其工作机制。最后，总结了Sa-Token的优缺点及其在实际开发中的应用场景，为开发者提供全面的指导。

---

一、Sa-Token介绍

1. Sa-Token简介

Sa-Token是一款轻量级Java权限认证框架，旨在解决Web系统中常见的登录认证、权限验证、Session会话、单点登录等问题。其核心目标是以最简洁的方式，实现强大的权限控制功能，帮助开发者快速完成权限系统的搭建。

Sa-Token具有如下优势：

| 优势 | 描述 |

|----------------------|--------------------------------------------------------------|

| **简单易用** | API设计简洁明了，易于集成和使用，上手快，学习成本低。 |

| **功能丰富** | 支持多种权限控制需求，满足复杂业务场景。支持登录认证、权限验证、角色验证、Session会话、多账号体系等功能。 |

| **高性能** | 轻量级设计，对系统性能影响小。 |

| **高度可扩展** | 提供丰富的扩展接口，与Spring、Spring Boot等常用框架高度兼容，支持自定义持久化、注解方式验证、单点登录等高级特性。 |

| **社区活跃** | 有良好的社区支持和文档资源。 |

2. Sa-Token原理解析

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

其主要工作流程如下：

① **登录认证**：用户登录成功后，服务器生成一个全局唯一的Token，并将其返回给客户端。

② **Token存储**：Token与用户身份信息的映射关系保存在服务器的会话中（如Redis、内存等）。

③ **权限验证**：客户端请求时携带Token，服务器根据Token获取用户信息，验证其权限是否满足要求。

④ **会话管理**：支持Session会话管理，可以获取和操作当前会话的属性。

流程图例如下：

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

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

| 特性 | Sa-Token | Shiro | Spring Security |

|----------------|-------------------|-------------------|-------------------|

| **学习成本** | 低 | 中 | 高 |

| **功能丰富度** | 高 | 中 | 高 |

| **集成难度** | 低 | 中 | 高 |

| **性能表现** | 高 | 中 | 中 |

| **社区支持** | 活跃 | 一般 | 活跃 |

| **扩展性** | 高 | 中 | 高 |

---

二、Sa-Token的基本语法

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

1. 创建Spring Boot项目

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

**引入必要的依赖：**

```xml

<!-- Spring Boot Starter Web -->

<dependency>

    <groupId>org.springframework.boot</groupId>

    <artifactId>spring-boot-starter-web</artifactId>

</dependency>


<!-- Sa-Token核心依赖 -->

<dependency>

    <groupId>cn.dev33</groupId>

    <artifactId>sa-token-spring-boot-starter</artifactId>

    <version>1.34.0</version>

</dependency>

```

2. 配置Sa-Token

**application.yml**

```yaml

Sa-Token配置，可根据需要进行调整

sa-token:

token有效期，单位秒，默认30天

timeout: 2592000

是否打开二级登录校验

open-safe: false

```

3. 配置拦截器

创建配置类，添加Sa-Token的拦截器，以拦截请求并进行权限验证。

**SaTokenConfigure.java**

```java

import cn.dev33.satoken.interceptor.SaAnnotationInterceptor;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.*;

@Configuration

public class SaTokenConfigure implements WebMvcConfigurer {

@Override

public void addInterceptors(InterceptorRegistry registry) {

    // 注册Sa-Token的注解拦截器，拦截所有路径

    registry.addInterceptor(new SaAnnotationInterceptor()).addPathPatterns("/\*\*");

}

}

```

4. 登录认证

创建登录接口，实现用户登录功能。

**LoginController.java**

```java

import cn.dev33.satoken.stp.StpUtil;

import org.springframework.web.bind.annotation.*;

@RestController

public class LoginController {

@PostMapping("/login")

public String login(@RequestParam String username, @RequestParam 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**

```java

import cn.dev33.satoken.annotation.SaCheckPermission;

import cn.dev33.satoken.stp.StpUtil;

import org.springframework.web.bind.annotation.*;

@RestController

@RequestMapping("/user")

public class UserController {

// 查询用户信息，需登录

@GetMapping("/info")

public String getUserInfo() {

    // 校验是否登录

    StpUtil.checkLogin();

    // 获取用户ID

    int userId = StpUtil.getLoginIdAsInt();

    return "当前用户信息，ID：" + userId;

}


// 修改用户信息，需有权限"user:update"

@SaCheckPermission("user:update")

@PostMapping("/update")

public String updateUser() {

    return "用户信息更新成功";

}

}

```

**说明：**

• 使用`StpUtil.checkLogin()`方法手动校验登录状态。
• 使用`@SaCheckPermission("user:update")`注解，声明该接口需要权限`user:update`。

6. 角色验证

如果需要基于角色进行权限控制，可以使用`@SaCheckRole`注解。

```java

import cn.dev33.satoken.annotation.SaCheckRole;

import org.springframework.web.bind.annotation.*;

@RestController

@RequestMapping("/admin")

public class AdminController {

// 仅管理员角色可访问

@SaCheckRole("admin")

@GetMapping("/dashboard")

public String adminDashboard() {

    return "欢迎进入管理员控制台";

}

}

```

7. 自定义权限验证逻辑

需要自定义获取用户权限和角色的逻辑，可以实现`StpInterface`接口。

**StpInterfaceImpl.java**

```java

import cn.dev33.satoken.stp.StpInterface;

import org.springframework.stereotype.Component;

import java.util.*;

@Component

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中存储和获取数据。

```java

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强制用户下线。

```java

// 将用户ID为10001的用户踢下线

StpUtil.logoutByLoginId(10001);

// 检查用户是否已被踢下线

boolean isLogout = StpUtil.isLogin();

System.out.println("用户是否登录：" + isLogout);

```

10. 注销登录

用户主动注销登录，可以调用`StpUtil.logout()`方法。

```java

// 注销登录

StpUtil.logout();

// 检查登录状态

boolean isLogin = StpUtil.isLogin();

System.out.println("用户是否登录：" + isLogin);

```

---

三、Sa-Token的高级用法

1. 自定义持久化

Sa-Token默认使用内存来存储Token信息，在分布式环境中，可以使用Redis作为持久化介质。

**引入Redis依赖：**

```xml

<groupId>cn.dev33</groupId>

<artifactId>sa-token-dao-redis</artifactId>

<version>1.34.0</version>

```

**配置Redis持久化：**

```java

import cn.dev33.satoken.dao.SaTokenDao;

import cn.dev33.satoken.dao.SaTokenDaoRedis;

import org.springframework.context.annotation.Bean;

import org.springframework.context.annotation.Configuration;

@Configuration

public class SaTokenDaoConfig {

@Bean

public SaTokenDao saTokenDao() {

    // 返回Redis实现

    return new SaTokenDaoRedis();

}

}

```

**配置Redis连接信息：**

**application.yml**

```yaml

配置Redis连接信息

spring:

redis:

host: localhost

port: 6379

password:

```

2. 单点登录（SSO）

Sa-Token提供了SSO模块，可以快速实现单点登录功能。

**引入SSO依赖：**

```xml

<groupId>cn.dev33</groupId>

<artifactId>sa-token-sso</artifactId>

<version>1.34.0</version>

```

**配置SSO相关参数：**

**application.yml**

```yaml

SSO单点登录配置

sa-token:

sso:

mode: client

server-url: sso-server.com

client-url: client1.com

```

```

**实现SSO登录逻辑：**

在客户端应用中，配置SSO的拦截器，自动处理单点登录。

**SaTokenConfigure.java**

```java

import cn.dev33.satoken.sso.SaSsoHandle;

import org.springframework.context.annotation.Configuration;

import org.springframework.web.servlet.config.annotation.*;

@Configuration

public class SaTokenConfigure implements WebMvcConfigurer {

@Override

public void addInterceptors(InterceptorRegistry registry) {

    // 注册SSO拦截器

    registry.addInterceptor(new SaSsoHandle()).addPathPatterns("/\*\*");

}

}

```

3. OAuth2.0支持

Sa-Token也支持OAuth2.0协议，可以实现与第三方平台的对接。

**引入OAuth2.0依赖：**

```xml

<groupId>cn.dev33</groupId>

<artifactId>sa-token-oauth2</artifactId>

<version>1.34.0</version>

```

配置OAuth2.0参数和实现授权流程（此处略，具体可参考官方文档）。

4. 多账号体系

如果系统中存在多种身份的用户，例如普通用户、管理员、商家等，可以使用多账号体系进行区分。

**登录指定账号体系：**

```java

// 管理员登录，loginKey为"admin"

StpUtil.login(10001, "admin");

```

**检查登录状态：**

```java

// 检查当前账号体系下是否登录

boolean isLogin = StpUtil.isLogin("admin");

```

**权限验证：**

```java

// 在指定账号体系下进行权限验证

StpUtil.checkPermission("user:update", "admin");

```

---

四、Sa-Token使用总结

Sa-Token是一款轻量级的Java权限认证框架，因其简单易用和功能丰富而备受开发者青睐。它以简洁明了的API设计，使得集成和使用变得非常方便，开发者可以快速上手，降低了学习成本。Sa-Token支持多种权限控制需求，满足复杂业务场景，包括登录认证、权限验证、角色验证、Session会话、多账号体系等功能，全面覆盖了权限管理的各个方面。其轻量级的设计对系统性能影响小，适用于高并发的应用环境。此外，Sa-Token提供了丰富的扩展接口，与Spring、Spring Boot等常用框架高度兼容，支持自定义持久化、注解方式验证、单点登录等高级特性，方便开发者根据项目需求进行定制开发。活跃的社区支持和丰富的文档资源也使得开发者能够轻松获取帮助和指导。

由于这些优势，Sa-Token非常适合中小型项目的快速开发和微服务架构下的权限管理。当项目需要快速搭建权限系统时，选择Sa-Token是一个理想的方案。然而，在使用过程中需要注意Token的安全性，防止泄露带来风险；对于高并发场景，建议使用Redis等持久化介质来提高系统性能和扩展性；同时，关注Sa-Token的版本更新，及时获取新功能和安全补丁，以确保系统的安全性和稳定性。