Spring Boot 整合 SA-Token 的使用详解

Spring Boot 整合 SA-Token 的使用详解涉及多个方面，包括SA-Token的介绍、整合步骤、配置方法、具体使用场景以及代码示例等。以下是一个详细的解析，旨在帮助读者全面理解和应用SA-Token在Spring Boot项目中的权限认证和登录认证功能。

一、SA-Token介绍

SA-Token是一个轻量级的Java权限认证框架，由国人开发，主要解决登录认证、权限认证、单点登录、OAuth2.0、分布式Session会话、微服务网关鉴权等一系列权限相关问题。SA-Token旨在以简单、优雅的方式完成系统的权限认证部分，其特点包括：

• 轻量级：SA-Token不依赖任何第三方框架，只依赖JDK原生API，易于学习和使用。
• 零配置：SA-Token提供了丰富的内置功能，用户可以通过简单的配置即可使用，无需编写大量的代码。
• 注解式鉴权：SA-Token提供了丰富的注解，如@SaCheckPermission、@SaCheckRole等，可以很方便地在Controller层进行权限控制。
• 丰富的会话管理：SA-Token支持多种会话管理方式，包括Account-Session、Token-Session、Custom-Session等，并提供了丰富的会话操作方法。

二、Spring Boot整合SA-Token的步骤

1. 引入SA-Token依赖

首先，你需要在Spring Boot项目的pom.xml文件中引入SA-Token的依赖。如果你使用的是Spring Boot 3.x版本，需要引入sa-token-spring-boot3-starter依赖；如果是Spring Boot 2.x版本，则引入sa-token-spring-boot-starter依赖。以Spring Boot 3.x为例，添加依赖如下：

<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot3-starter</artifactId>
    <version>最新版本</version> <!-- 请替换为最新版本号 -->
</dependency>

2. 配置SA-Token

在application.yml或application.properties配置文件中，你可以根据需要配置SA-Token的相关参数。以下是一个配置示例：

sa-token:
  token-name: Authorization  # token名称 (header中key)
  token-type: bearer         # token类型 (header中value的前缀)
  timeout: 3600              # token过期时间, 单位秒
  activity-timeout: -1       # 临时token有效时间, 单位秒,-1表示永不过期
  is-concurrent: true        # 是否允许同一账号并发登录, 默认false
  is-share: false            # 在多个服务之间共享token时,需要设置为true

3. 编写登录和注销逻辑

SA-Token提供了简单的API来处理登录和注销逻辑。你可以在你的Controller中编写登录接口，使用StpUtil.login(Object id)方法来实现登录，使用StpUtil.logout()方法来实现注销。以下是一个登录接口的示例：

@RestController
@RequestMapping("/user")
public class UserController {

    @PostMapping("/login")
    public SaResult login(@RequestBody UserDTO userDTO) {
        // 假设UserDTO中包含了用户名和密码
        // 这里只是示例，实际项目中应该从数据库中查询用户信息并进行比对
        if ("zhangsan".equals(userDTO.getUsername()) && "123456".equals(userDTO.getPassword())) {
            // 登录成功，id为用户的唯一标识，这里假设为1
            StpUtil.login(1);
            return SaResult.ok("登录成功");
        }
        return SaResult.error("登录失败");
    }

    @GetMapping("/logout")
    public SaResult logout() {
        // 注销当前会话
        StpUtil.logout();
        return SaResult.ok("注销成功");
    }
}

三、SA-Token的具体使用场景

1. 权限认证

SA-Token提供了丰富的权限认证功能，包括权限码认证、角色认证等。你可以通过实现StpInterface接口来自定义权限和角色的加载逻辑，然后在Controller层使用@SaCheckPermission和@SaCheckRole注解来进行权限控制。

2. 会话管理

SA-Token支持多种会话管理方式，包括Account-Session、Token-Session、Custom-Session等。你可以通过StpUtil类提供的方法来获取当前会话的Token值、登录ID等信息，也可以对会话进行操作，如踢出用户、延长会话有效期等。

3. 分布式Session管理

在分布式系统中，Session共享是一个常见问题。SA-Token通过其内置的分布式Session支持，可以轻松实现Session的跨服务共享。SA-Token支持Redis、JWT等多种方式来存储和同步Session信息，用户可以根据实际需求选择合适的方案。

四、代码示例：使用SA-Token进行权限控制

在Spring Boot项目中，你可以很方便地利用SA-Token的注解功能进行权限控制。以下是一个使用@SaCheckPermission注解进行权限码校验的示例：

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

    @GetMapping("/data")
    @SaCheckPermission("admin:data:view") // 需要拥有admin:data:view权限码的用户才能访问
    public SaResult getData() {
        // 假设这里是获取敏感数据的逻辑
        return SaResult.ok().setData("敏感数据");
    }

    @PostMapping("/modify")
    @SaCheckPermission("admin:data:modify") // 需要拥有admin:data:modify权限码的用户才能访问
    public SaResult modifyData(@RequestBody DataDTO dataDTO) {
        // 假设这里是修改数据的逻辑
        return SaResult.ok("数据修改成功");
    }
}

在这个例子中，getData方法和modifyData方法分别通过@SaCheckPermission注解指定了访问这两个接口所需的权限码。当用户访问这些接口时，SA-Token会自动检查当前会话是否拥有相应的权限码，如果没有，则会抛出权限不足的异常。

五、配置和使用JWT

SA-Token也支持JWT（Json Web Token）作为Token的存储方式。如果你想要使用JWT来实现无状态的Token认证，可以在配置文件中进行相应的设置，并在登录时生成JWT Token。

首先，在配置文件中启用JWT模式，并设置JWT的密钥等信息：

sa-token:
  token-style: jwt # 使用jwt方式
  jwt-secret-key: your-secret-key # jwt密钥
  jwt-public-key:  # jwt公钥（非必须，如果使用RSA非对称加密时才需要）
  jwt-algorithm: HS256 # jwt加密算法

然后，在登录时生成JWT Token并返回给客户端：

@PostMapping("/login")
public ResponseEntity<String> login(@RequestBody UserDTO userDTO) {
    // 假设验证用户信息成功后
    String jwtToken = StpUtil.createToken(userDTO.getId(), "自定义数据", 3600*24); // 生成jwt token，有效期为24小时
    HttpHeaders headers = new HttpHeaders();
    headers.add("Authorization", "Bearer " + jwtToken); // 将token放入Header中返回
    return new ResponseEntity<>("登录成功", HttpStatus.OK, headers);
}

客户端在后续请求中，需要将JWT Token放在请求的Header中（如Authorization: Bearer 你的JWTToken），SA-Token会自动从Header中解析JWT Token，并进行相应的认证和授权操作。

六、总结

SA-Token作为一个轻量级的Java权限认证框架，以其简单易用、功能丰富等特点，在Spring Boot项目中得到了广泛的应用。通过整合SA-Token，你可以很方便地实现登录认证、权限认证、会话管理等一系列权限相关功能。希望本文的详细解析能够帮助你更好地理解和使用SA-Token。