Springboot 权限认证框架 -- SA-Token 简介（一）

news2025/1/20 1:48:42

引言

现今的软件开发中，权限认证与访问控制是每一个应用都必不可少的功能。SA-Token是一个简单、安全、易用的权限认证框架，它主要解决登录认证、权限认证、Session会话、单点登录等功能。SA-Token以其轻量级、零学习成本的特点，迅速赢得了开发者的青睐。本文将介绍如何在Spring Boot项目中集成SA-Token，实现快速、安全的权限认证。

一、SA-Token简介

SA-Token是一个轻量级Java权限认证框架，主要解决：登录认证、权限认证、Session会话、单点登录、OAuth2.0等功能。你可以使用SA-Token来轻松地实现项目的权限控制，并且几乎零学习成本。SA-Token以简单、易用、安全为主要设计目标，提供了丰富的API和灵活的扩展机制，可以满足大多数项目的需求。

官网文档：https://sa-token.cc/doc.html#/
Gitee开源地址: https://gitee.com/dromara/sa-token
GitHub开源地址: https://github.com/click33/sa-token

二、Spring Boot 项目集成

1. 添加依赖：

在Spring Boot项目的pom.xml文件中添加SA-Token的依赖。

<!-- Sa-Token 权限认证，在线文档：https://sa-token.cc -->
<dependency>
    <groupId>cn.dev33</groupId>
    <artifactId>sa-token-spring-boot-starter</artifactId>
    <version>1.38.0</version>
</dependency>

2. 配置SA-Token：

在Spring Boot的配置类或配置文件 application.yml 中配置SA-Token的相关参数。

application.yml 配置示例：

server:
    # 端口
    port: 8081
    
############## Sa-Token 配置 (文档: https://sa-token.cc) ##############
sa-token: 
    # token 名称（同时也是 cookie 名称）
    token-name: satoken
    # token 有效期（单位：秒） 默认30天，-1 代表永久有效
    timeout: 2592000
    # token 最低活跃频率（单位：秒），如果 token 超过此时间没有访问系统就会被冻结，默认-1 代表不限制，永不冻结
    active-timeout: -1
    # 是否允许同一账号多地同时登录 （为 true 时允许一起登录, 为 false 时新登录挤掉旧登录）
    is-concurrent: true
    # 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个 token, 为 false 时每次登录新建一个 token）
    is-share: true
    # token 风格（默认可取值：uuid、simple-uuid、random-32、random-64、random-128、tik）
    token-style: uuid
    # 是否输出操作日志 
    is-log: true

三、SA-Token 常用方法简介

SA-Token提供了一系列的API方法，使得在Java项目中实现权限认证变得简单和直观。以下是一些常用的SA-Token方法简介：

登录与登出

StpUtil.login(loginId): 会话登录，参数为用户的账号ID。
StpUtil.logout(): 当前会话注销登录。
StpUtil.logoutByLoginId(loginId): 根据账号ID踢人下线。

登录状态检查

StpUtil.isLogin(): 检查当前会话是否已经登录，返回布尔值。
StpUtil.checkLogin()：校验当前客户端是否已经登录，如果未登录则抛出NotLoginException异常。

权限与角色检查

StpUtil.hasRole(role): 查询当前账号是否含有指定角色标识。
StpUtil.hasPermission(permission): 查询当前账号是否含有指定权限。

Session管理

StpUtil.getSession(): 获取当前账号ID的Session。
StpUtil.getSessionByLoginId(loginId): 根据账号ID获取Session。

Token管理

StpUtil.getTokenValue(): 获取当前会话的Token值。
StpUtil.getTokenValueByLoginId(loginId): 根据账号ID获取Token值。

账号切换与模拟

StpUtil.switchTo(loginId): 将会话身份临时切换为其它账号。
StpUtil.kickout(loginId): 踢出账号，使其下线。

自定义Token生成

StpUtil.setLoginId(loginId, deviceId): 指定设备标识登录。
StpUtil.logoutByLoginId(loginId, deviceId): 指定设备标识进行强制注销。

权限注解

@SaCheckPermission(value = "permission"): 注解鉴权，方法上使用，只有具备指定权限的会话才可以访问该方法。

路由拦截鉴权

在拦截器中使用StpUtil.checkPermission(permission)来对请求进行权限校验。

密码加密

提供了多种密码加密方式，如MD5、SHA1、SHA256、AES等。

自动续签

StpUtil.setLoginId(loginId, timeout): 登录时可以指定Token的有效期，实现自动续签。

会话查询与治理

提供了会话查询接口，方便开发者进行会话治理。

这些方法覆盖了从用户登录、权限验证到会话管理的各个方面，使得使用SA-Token可以轻松实现复杂的权限控制逻辑。开发者可以根据项目需求选择合适的方法进行集成和扩展。

四、实际案例-- 实现登录逻辑：

1. 编写登录逻辑，使用SA-Token提供的API进行用户认证。

登录访问流程：

用户提交 name + password 参数，调用登录接口。
登录成功，返回这个用户的 Token 会话凭证。
用户后续的每次请求，都携带上这个 Token。
服务器根据 Token 判断此会话是否登录成功。

2. 创建 UserController 示例代码：

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

    // 测试登录，浏览器访问： http://localhost:8081/user/doLogin?username=zhang&password=123456
    @RequestMapping("doLogin")
    public String doLogin(String username, String password) {
        // 此处仅作模拟示例，真实项目需要从数据库中查询数据进行比对 
        if("zhang".equals(username) && "123456".equals(password)) {
            StpUtil.login(10001);
            return "登录成功";
        }
        return "登录失败";
    }

    // 查询登录状态，浏览器访问： http://localhost:8081/user/isLogin
    @RequestMapping("isLogin")
    public String isLogin() {
        return "当前会话是否登录：" + StpUtil.isLogin();
    }
    
}