Sa-Token实战：新手入门教程

本文详细介绍了Sa-Token框架的基本功能和优势，涵盖了用户认证、权限管理、Token生成与验证等内容。文章还提供了新手入门教程，包括环境搭建、基础使用方法和实战案例。通过阅读本文，读者可以轻松掌握Sa-Token实战技巧。

什么是Sa-Token

Sa-Token 是一个 Java 语言的轻量级权限认证框架，适用于任何 Java 项目（JavaSE、Spring Boot、Spring MVC、Struts、Android、iOS、Node.js 等），其核心功能包括权限认证、登录认证、分布式会话等功能。Sa-Token 支持多种认证方式，如 JWT、Cookie、Session 等，具备良好的扩展性和灵活性。

Sa-Token的主要功能和优势

Sa-Token 主要提供以下功能：

• 用户认证与登录：提供多种登录方式，如用户名密码登录、手机号登录、社交账号登录等。
• 权限管理：支持多种权限管理策略，如角色权限、菜单权限等。
• Token生成与验证：提供生成和验证 Token 的功能，保证数据传输的安全性。
• 分布式会话：支持集群环境下会话共享，保证多节点一致性。
• 黑白名单：支持 IP 黑白名单管理，增强系统的安全性。
• 日志监控：支持操作日志记录，方便问题排查和审计。

其主要优势包括：

• 轻量级：Sa-Token 的核心代码量小，易于集成和使用。
• 高性能：框架经过优化，性能优异，适合高并发场景。
• 灵活扩展：提供多种接口和注解，易于扩展和二次开发。
• 多场景支持：适用于 Web、移动、微服务等多种场景。

Sa-Token的适用场景

• Web 应用：如 Spring Boot、Spring MVC、Struts 等。
• 移动应用：如 Android、iOS 等。
• 微服务架构：如 Dubbo、Spring Cloud 等。
• 分布式系统：支持多节点会话共享。
• 社区应用：如论坛、博客系统等。
• API 服务：为 RESTful API 提供安全认证。

准备工作

在开始使用 Sa-Token 之前，需要确保你已经搭建了一个基本的 Java 开发环境，包括 Java SDK 和开发工具。以下是准备工作步骤：

1. 安装 Java SDK：下载并安装 JDK。
2. 配置环境变量：确保 JAVA_HOME、PATH 等环境变量配置正确。
3. 安装 IDE：推荐使用 IntelliJ IDEA 或 Eclipse，以便进行代码开发。

添加Sa-Token依赖

在项目中引入 Sa-Token 依赖，需要添加对应的 Maven 或 Gradle 依赖。以下是 Maven 依赖配置示例：

<dependency>
    <groupId>cn.dreames</groupId>
    <artifactId>sa-token</artifactId>
    <version>1.23.0</version>
</dependency>

对于 Gradle 项目，需要在 build.gradle 文件中添加如下依赖：

dependencies {
    implementation 'cn.dreames:sa-token:1.23.0'
}

初始化配置

初始化 Sa-Token 配置，需要创建一个配置类，通常命名为 SaTokenConfig，并在其中配置基础参数。以下是一个配置类的示例：

import cn.dreames.sa.token.model.config.SaTokenConfig;

public class SaTokenConfig {

    public static void main(String[] args) {
        SaTokenConfig.init();

        // 配置 Sa-Token 的基础参数
        SaTokenConfig.setGlobalTimeout(30 * 60); // 设置全局的 Token 超时时间，单位：秒
        SaTokenConfig.setGlobalRefresh(false); // 设置是否全局开启 Token 自动刷新功能
        SaTokenConfig.setCacheTimeout(7 * 24 * 60 * 60); // 设置缓存超时时间，单位：秒
    }
}

用户认证与登录

用户认证流程

用户认证一般包括以下步骤：

1. 登录请求：用户提交用户名和密码。
2. 身份验证：验证用户提交的信息是否正确。
3. 生成 Token：身份验证通过后，生成一个用于标识用户的 Token。
4. 返回 Token：将生成的 Token 返回给客户端。

示例代码

以下是一个简单的用户登录示例，使用 Spring Boot 进行实现。

import cn.dreames.sa.token.model.config.SaTokenConfig;
import cn.dreames.sa.token.model.entity.SaUser;
import cn.dreames.sa.token.model.entity.SaTokenModel;
import cn.dreames.sa.token.model.result.SaResult;
import cn.dreames.sa.token.model.result.SaResultData;
import cn.dreames.sa.token.util.SaResultUtil;
import cn.dreames.sa.token.util.SaTokenUtil;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class LoginController {

    @PostMapping("/login")
    public SaResultData<String> login(@RequestBody SaTokenModel saTokenModel) {
        // 获取用户名和密码
        String username = saTokenModel.getUsername();
        String password = saTokenModel.getPassword();

        // 验证用户名和密码是否正确
        if ("admin".equals(username) && "123456".equals(password)) {
            // 用户名和密码正确，生成 Token 并返回
            String token = SaTokenUtil.createToken(username);
            return SaResultUtil.success(token);
        }

        // 用户名或密码错误，返回错误信息
        return SaResultUtil.error("用户名或密码错误");
    }
}

权限管理

权限管理流程

权限管理主要包括以下步骤：

1. 用户角色分配：为用户分配相应的角色。
2. 权限规则配置：配置每个角色对应的权限。
3. 权限验证：验证用户是否具有执行某个操作的权限。

示例代码

以下是一个简单的权限验证示例，使用 Spring Boot 进行实现。

import cn.dreames.sa.token.model.config.SaTokenConfig;
import cn.dreames.sa.token.model.entity.SaUser;
import cn.dreames.sa.token.model.entity.SaTokenModel;
import cn.dreames.sa.token.model.result.SaResult;
import cn.dreames.sa.token.model.result.SaResultData;
import cn.dreames.sa.token.util.SaResultUtil;
import cn.dreames.sa.token.util.SaTokenUtil;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PermissionController {

    @GetMapping("/api/data")
    public SaResultData<String> getData(@RequestParam String token) {
        // 验证 Token 是否有效
        if (SaTokenUtil.checkToken(token)) {
            // Token 有效，继续执行操作
            return SaResultUtil.success("获取数据成功");
        }

        // Token 无效，返回错误信息
        return SaResultUtil.error("Token 无效");
    }
}

Token生成与验证

Token生成流程

Token 生成一般包括以下步骤：

1. 生成 Token：使用 Sa-Token 提供的 API 生成一个新的 Token。
2. 存储 Token：将生成的 Token 存储到缓存中，以便后续验证。
3. 返回 Token：将生成的 Token 返回给客户端。

示例代码

以下是一个简单的 Token 生成示例，使用 Spring Boot 进行实现。

import cn.dreames.sa.token.model.config.SaTokenConfig;
import cn.dreames.sa.token.model.entity.SaUser;
import cn.dreames.sa.token.model.entity.SaTokenModel;
import cn.dreames.sa.token.model.result.SaResult;
import cn.dreames.sa.token.model.result.SaResultData;
import cn.dreames.sa.token.util.SaResultUtil;
import cn.dreames.sa.token.util.SaTokenUtil;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TokenController {

    @PostMapping("/createToken")
    public SaResultData<String> createToken(@RequestBody SaTokenModel saTokenModel) {
        // 获取用户名和密码
        String username = saTokenModel.getUsername();
        String password = saTokenModel.getPassword();

        // 验证用户名和密码是否正确
        if ("admin".equals(username) && "123456".equals(password)) {
            // 用户名和密码正确，生成 Token 并返回
            String token = SaTokenUtil.createToken(username);
            return SaResultUtil.success(token);
        }

        // 用户名或密码错误，返回错误信息
        return SaResultUtil.error("用户名或密码错误");
    }
}

用户登录示例

用户登录示例代码如下，使用 Spring Boot 进行实现。

import cn.dreames.sa.token.model.config.SaTokenConfig;
import cn.dreames.sa.token.model.entity.SaUser;
import cn.dreames.sa.token.model.entity.SaTokenModel;
import cn.dreames.sa.token.model.result.SaResult;
import cn.dreames.sa.token.model.result.SaResultData;
import cn.dreames.sa.token.util.SaResultUtil;
import cn.dreames.sa.token.util.SaTokenUtil;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class LoginController {

    @PostMapping("/login")
    public SaResultData<String> login(@RequestBody SaTokenModel saTokenModel) {
        // 获取用户名和密码
        String username = saTokenModel.getUsername();
        String password = saTokenModel.getPassword();

        // 验证用户名和密码是否正确
        if ("admin".equals(username) && "123456".equals(password)) {
            // 用户名和密码正确，生成 Token 并返回
            String token = SaTokenUtil.createToken(username);
            return SaResultUtil.success(token);
        }

        // 用户名或密码错误，返回错误信息
        return SaResultUtil.error("用户名或密码错误");
    }
}

权限控制示例

权限控制示例代码如下，使用 Spring Boot 进行实现。

import cn.dreames.sa.token.model.config.SaTokenConfig;
import cn.dreames.sa.token.model.entity.SaUser;
import cn.dreames.sa.token.model.entity.SaTokenModel;
import cn.dreames.sa.token.model.result.SaResult;
import cn.dreames.sa.token.model.result.SaResultData;
import cn.dreames.sa.token.util.SaResultUtil;
import cn.dreames.sa.token.util.SaTokenUtil;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class PermissionController {

    @GetMapping("/api/data")
    public SaResultData<String> getData(@RequestParam String token) {
        // 验证 Token 是否有效
        if (SaTokenUtil.checkToken(token)) {
            // Token 有效，继续执行操作
            return SaResultUtil.success("获取数据成功");
        }

        // Token 无效，返回错误信息
        return SaResultUtil.error("Token 无效");
    }
}

Token刷新和过期处理

Token刷新流程

Token 刷新一般包括以下步骤：

1. 判断 Token 是否过期：检查 Token 是否已经过期。
2. 刷新 Token：生成一个新的 Token 并替换旧的 Token。
3. 返回新 Token：将新生成的 Token 返回给客户端。

示例代码

以下是一个简单的 Token 刷新示例，使用 Spring Boot 进行实现。

import cn.dreames.sa.token.model.config.SaTokenConfig;
import cn.dreames.sa.token.model.entity.SaUser;
import cn.dreames.sa.token.model.entity.SaTokenModel;
import cn.dreames.sa.token.model.result.SaResult;
import cn.dreames.sa.token.model.result.SaResultData;
import cn.dreames.sa.token.util.SaResultUtil;
import cn.dreames.sa.token.util.SaTokenUtil;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class TokenController {

    @PostMapping("/refreshToken")
    public SaResultData<String> refreshToken(@RequestBody SaTokenModel saTokenModel) {
        // 获取 Token
        String token = saTokenModel.getToken();

        // 验证 Token 是否有效
        if (SaTokenUtil.checkToken(token)) {
            // Token 有效，刷新 Token 并返回
            String newToken = SaTokenUtil.refreshToken(token);
            return SaResultUtil.success(newToken);
        }

        // Token 无效，返回错误信息
        return SaResultUtil.error("Token 无效");
    }
}

常见错误及解决方法

1. Token 生成失败：检查用户名和密码是否正确。
2. Token 验证失败：检查 Token 是否已经过期，或者是否已经被撤销。
3. 权限不足：检查用户的角色和权限是否配置正确。

性能优化

1. 缓存优化：使用缓存技术（如 Redis）存储 Token，提高访问速度。
2. 并发处理：使用线程池处理并发请求，提高系统响应速度。
3. 配置优化：合理配置 Sa-Token 的超时时间，避免频繁生成 Token。

迁移和升级注意事项

1. 版本兼容性：检查新版本的 API 是否与旧版本兼容。
2. 数据迁移：确保旧数据可以顺利迁移到新版本。
3. 测试验证：在正式迁移之前，进行充分的测试验证。

Sa-Token社区和文档

Sa-Token 官方网站提供了详细的文档和示例代码，可以帮助你更好地理解和使用 Sa-Token。此外，Sa-Token 有一个活跃的社区，你可以在社区中提问和分享经验。以下是官方网站和社区链接：

• 官方网站：https://sa-token.cn
• GitHub 仓库：https://github.com/cyning/sa-token

进阶学习资源

为了帮助你进一步学习和掌握 Sa-Token，推荐以下资源：

• 慕课网课程：慕课网提供了许多关于 Java 和 Spring Boot 的课程，可以帮助你更好地理解相关技术。
• 官方文档：官方文档详细介绍了 Sa-Token 的各种功能和配置方法，是学习 Sa-Token 的重要资源。

希望以上内容对你有所帮助，祝你在编程道路上越走越远！