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

本文介绍了Sa-Token实战，从环境搭建到核心功能的实现，涵盖了Sa-Token框架的各项关键操作，帮助开发者快速构建安全的用户认证系统。通过详细示例，读者可以学习到如何进行用户认证、权限控制等操作，并且提供了实战案例和测试优化建议。

Sa-Token 是什么

Sa-Token 是一款由开源爱好者开发的 Java 安全框架，专注于用户认证与权限控制。它提供了一套完整的认证与权限管理解决方案，可以帮助开发者快速构建安全的用户认证系统。Sa-Token 包含了丰富的功能，如 Token 生成与验证、用户登录与注销、权限控制与角色管理等。

Sa-Token 的主要功能

1. Token 生成与验证：Sa-Token 可以生成多种类型的 Token，并提供验证接口来确保 Token 的有效性。
2. 用户认证与登录：支持多种认证方式，如用户名密码认证、手机号认证等。
3. 权限控制与角色管理：通过角色与权限的管理，实现细粒度的权限控制。
4. 分布式会话支持：支持分布式环境下的会话管理，确保用户在不同服务器之间也能保持会话状态。
5. 缓存机制：通过缓存提高性能，减少数据库访问次数。
6. 黑白名单：支持 IP 白名单和黑名单管理，增加安全性。

Sa-Token 适用场景

1. Web 应用：为 Web 应用提供安全的用户认证与权限控制功能。
2. 移动应用：为移动应用提供安全的用户认证与 Token 管理功能。
3. 微服务架构：适用于微服务架构下的服务认证与权限控制。
4. 分布式系统：支持分布式系统中的会话管理与用户认证。

准备工作：环境搭建与依赖引入

在开始使用 Sa-Token 之前，你需要搭建好开发环境，并引入 Sa-Token 的相关依赖。以下是具体的步骤：

1. 搭建开发环境：确保你已经安装了 JDK 和 IDE（如 IntelliJ IDEA 或 Eclipse）。
2. 引入依赖：在你的项目中添加 Sa-Token 的依赖。如果使用 Maven 项目，可以在 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>com.github.shaoqiang</groupId>
    <artifactId>sa-token</artifactId>
    <version>1.31.0</version>
</dependency>

基本配置：初始化与简单使用

在引入依赖后，你需要对 Sa-Token 进行基本配置并初始化。以下是一个简单的配置示例：

初始化 Sa-Token

import com.github.shaoqiang.starter.web.config.SaTokenFilter;

@Configuration
public class SaTokenConfig {

    @Bean
    public FilterRegistrationBean saTokenFilterRegistration() {
        FilterRegistrationBean registration = new FilterRegistrationBean();
        registration.setFilter(new SaTokenFilter());
        registration.addUrlPatterns("/*");
        return registration;
    }
}

简单使用 Sa-Token

import com.github.shaoqiang.starter.web.SaTokenStarter;
import com.github.shaoqiang.starter.web.config.SaTokenConfig;
import com.github.shaoqiang.starter.web.config.SaTokenStarterAutoConfiguration;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class SaTokenApplication {

    public static void main(String[] args) {
        SpringApplication.run(SaTokenApplication.class, args);
    }

    @Bean
    public SaTokenStarter saTokenStarter() {
        return new SaTokenStarter();
    }

    @Bean
    public SaTokenConfig saTokenConfig() {
        return new SaTokenConfig();
    }
}

创建第一个认证功能

在完成基本配置后，你可以创建一个简单的认证功能。以下是一个示例代码，用于实现基于用户名和密码的用户认证：

用户认证接口

import com.github.shaoqiang.starter.web.SaTokenStarter;
import com.github.shaoqiang.starter.web.config.SaTokenConfig;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class AuthController {

    @PostMapping("/auth/login")
    public String login(@RequestParam String username, @RequestParam String password) {
        // 模拟用户认证
        if ("admin".equals(username) && "password".equals(password)) {
            // 登录成功，生成 Token
            SaTokenStarter st = new SaTokenStarter();
            String token = st.getTokenDao().createToken(username, "123456");
            return "登录成功，Token: " + token;
        } else {
            return "登录失败，用户名或密码错误";
        }
    }

    @PostMapping("/auth/verify")
    public String verifyToken(@RequestParam String token) {
        // 验证 Token 是否有效
        SaTokenStarter st = new SaTokenStarter();
        boolean isValid = st.getTokenDao().isValid(token);
        if (isValid) {
            return "Token 有效";
        } else {
            return "Token 无效";
        }
    }

    @PostMapping("/auth/logout")
    public String logout(@RequestParam String token) {
        // 通过 Token 进行注销操作
        SaTokenStarter st = new SaTokenStarter();
        st.getTokenTokenDao().delete(token);
        return "注销成功";
    }
}

用户认证与登录

用户认证是 Sa-Token 最核心的功能之一。Sa-Token 提供了多种认证方式，如用户名密码认证、手机号认证等。下面是一个简单的用户名密码认证示例：

用户认证与登录代码示例

import com.github.shaoqiang.starter.web.SaTokenStarter;

import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PostMapping("/user/login")
    public String login(@RequestParam String username, @RequestParam String password) {
        // 模拟用户认证
        if ("admin".equals(username) && "password".equals(password)) {
            // 登录成功，生成 Token
            SaTokenStarter st = new SaTokenStarter();
            String token = st.getTokenDao().createToken(username, "123456");
            return "登录成功，Token: " + token;
        } else {
            return "登录失败，用户名或密码错误";
        }
    }
}

权限控制与角色管理

Sa-Token 支持细粒度的权限控制与角色管理。以下是一个简单的权限控制示例：

权限控制与角色管理代码示例

import com.github.shaoqiang.starter.web.SaTokenStarter;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/admin")
public class AdminController {

    @GetMapping("/dashboard")
    public String dashboard() {
        // 检查权限
        SaTokenStarter st = new SaTokenStarter();
        if (!st.getSaManager().isLogin(SaTokenStarter.SaSessionLoginType.DEFAULT)) {
            return "未登录，请先登录";
        }
        if (!st.getSaManager().isRole("admin")) {
            return "无权限访问";
        }
        return "欢迎管理员!";
    }
}

Token 生成与验证

Token 生成与验证是 Sa-Token 的基础功能。以下是一个简单的 Token 生成与验证示例：

Token 生成与验证代码示例

import com.github.shaoqiang.starter.web.SaTokenStarter;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/token")
public class TokenController {

    @GetMapping("/create")
    public String createToken(@RequestParam String username) {
        // 生成 Token
        SaTokenStarter st = new SaTokenStarter();
        String token = st.getTokenDao().createToken(username, "123456");
        return "Token: " + token;
    }

    @GetMapping("/verify")
    public String verifyToken(@RequestParam String token) {
        // 验证 Token 是否有效
        SaTokenStarter st = new SaTokenStarter();
        boolean isValid = st.getTokenDao().isValid(token);
        if (isValid) {
            return "Token 有效";
        } else {
            return "Token 无效";
        }
    }
}

需求分析与设计

假设我们需要开发一个用户认证系统，该系统需要实现以下功能：

1. 用户注册：用户可以通过用户名和密码进行注册。
2. 用户登录：用户可以通过用户名和密码进行登录，并获取 Token。
3. 用户注销：用户可以通过 Token 进行注销操作。
4. 权限控制：管理员用户拥有更多的权限。

用户注册与登录功能设计

用户注册功能需要实现用户信息的存储与密码的加密。用户登录功能需要验证用户信息并生成 Token。

用户注销功能设计

用户注销功能需要通过 Token 来注销用户会话。

权限控制功能设计

权限控制功能需要根据用户的角色来限制用户的操作权限。

编码实现与调试

用户注册接口

import com.github.shaoqiang.starter.web.SaTokenStarter;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class UserController {

    @PostMapping("/user/register")
    public String register(@RequestParam String username, @RequestParam String password) {
        // 模拟用户注册
        // 这里可以实现用户信息的存储和密码的加密
        return "注册成功，用户: " + username;
    }

    @PostMapping("/user/login")
    public String login(@RequestParam String username, @RequestParam String password) {
        // 模拟用户认证
        if ("admin".equals(username) && "password".equals(password)) {
            // 登录成功，生成 Token
            SaTokenStarter st = new SaTokenStarter();
            String token = st.getTokenDao().createToken(username, "123456");
            return "登录成功，Token: " + token;
        } else {
            return "登录失败，用户名或密码错误";
        }
    }

    @PostMapping("/user/logout")
    public String logout(@RequestParam String token) {
        // 通过 Token 进行注销操作
        SaTokenStarter st = new SaTokenStarter();
        st.getTokenTokenDao().delete(token);
        return "注销成功";
    }
}

权限控制接口

import com.github.shaoqiang.starter.web.SaTokenStarter;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/admin")
public class AdminController {

    @GetMapping("/dashboard")
    public String dashboard() {
        // 检查权限
        SaTokenStarter st = new SaTokenStarter();
        if (!st.getSaManager().isLogin(SaTokenStarter.SaSessionLoginType.DEFAULT)) {
            return "未登录，请先登录";
        }
        if (!st.getSaManager().isRole("admin")) {
            return "无权限访问";
        }
        return "欢迎管理员!";
    }
}

系统测试与优化

在实现完上述功能后，你需要对系统进行测试和优化。测试包括：

1. 用户注册成功后，是否可以正常登录。
2. 用户登录成功后，是否可以正常注销。
3. 管理员用户是否可以访问管理员界面。

优化包括：

1. 对用户密码进行加密，提高安全性。
2. 对 Token 进行加密存储，防止泄露。

测试用户注册与登录

import org.springframework.web.client.RestTemplate;

public class UserTest {

    public static void main(String[] args) {
        RestTemplate restTemplate = new RestTemplate();
        String registerResult = restTemplate.postForObject("http://localhost:8080/user/register", null, String.class);
        System.out.println("注册结果: " + registerResult);

        String loginResult = restTemplate.postForObject("http://localhost:8080/user/login", Collections.singletonMap("username", "admin"), String.class);
        System.out.println("登录结果: " + loginResult);
    }
}

优化用户密码加密

import org.apache.commons.codec.digest.DigestUtils;

public class UserPasswordService {

    public String encryptPassword(String password) {
        // 使用 SHA-256 加密
        return DigestUtils.sha256Hex(password);
    }
}

常见错误与调试技巧

1. Token 无效：检查 Token 是否过期或被删除。
2. 权限不足：检查用户角色是否正确，是否具有相应权限。
3. 登录失败：检查用户名和密码是否正确。

性能优化与安全加固

1. 性能优化：

   • 使用缓存机制减少数据库访问。
   • 使用分布式会话管理提高并发性能。
2. 安全加固：
   • 对用户密码进行加密存储。
   • 对 Token 进行加密存储。
   • 使用黑白名单控制 IP 访问。

版本差异与迁移指南

1. 版本差异：

   • 不同版本的 Sa-Token 可能会有不同的 API 改变，确保使用最新的 API 文档。
2. 迁移指南：
   • 在升级版本时，注意查看官方文档中的迁移指南，确保代码兼容性。

回顾学习内容

在本教程中，我们学习了如何使用 Sa-Token 框架来实现用户认证与权限控制。我们从环境搭建、基本配置、核心功能到实战案例，详细介绍了 Sa-Token 的使用方法。通过本教程，你已经掌握了如何使用 Sa-Token 实现用户认证、权限控制等核心功能。

推荐进一步学习的资源与方向

1. 官方文档：熟悉 Sa-Token 官方文档，了解更多的高级用法和最佳实践。
2. 慕课网：可以参考慕课网上的相关课程，如《Java 安全框架实战》等。
3. GitHub 仓库：关注 Sa-Token 的 GitHub 仓库，了解最新的更新与问题反馈。
4. 社区交流：加入 Sa-Token 的社区，与其他开发者交流经验和问题。
5. 实际项目：在实际项目中应用 Sa-Token，不断巩固和提升自己的技能。