springboot整合Sa-Token实现登录认证和权限校验（万字长文）

目前在国内的后端开发中，常用的安全框架有spring security、shiro。现在，介绍一款由国人开发的安全框架Sa-Token。这个框架完全由国人开发，所提供的Api文档和一些设置都是比较符合国人的开发习惯的，本次就来介绍一下如何在spring boot框架中整合Sa-Token框架，以实现我们最常使用的登录认证和权限校验；

Sa-Token的官网地址如下：
Sa-Token

Sa-Token 是由国人开发的一个轻量级 Java 权限认证框架，主要解决：登录认证、权限认证、单点登录、OAuth2.0、分布式Session会话、微服务网关鉴权 等一系列权限相关问题。

版本：spring boot3.15、Sa-Token1.37.0

1、新建一个spring boot项目，并导入一些起始的依赖：

<dependency><groupId>com.alibaba</groupId><artifactId>fastjson</artifactId><version>2.0.32</version></dependency><dependency><groupId>cn.hutool</groupId><artifactId>hutool-all</artifactId><version>5.8.18</version></dependency><dependency><groupId>com.github.xiaoymin</groupId><artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId><version>4.3.0</version></dependency><!-- Sa-Token 权限认证，在线文档：https://sa-token.cc --><dependency><groupId>cn.dev33</groupId><artifactId>sa-token-spring-boot3-starter</artifactId><version>1.37.0</version></dependency><dependency><groupId>com.baomidou</groupId><artifactId>mybatis-plus-boot-starter</artifactId><version>3.5.3.1</version></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-web</artifactId></dependency><dependency><groupId>com.mysql</groupId><artifactId>mysql-connector-j</artifactId><scope>runtime</scope></dependency><dependency><groupId>org.projectlombok</groupId><artifactId>lombok</artifactId><optional>true</optional></dependency><dependency><groupId>org.springframework.boot</groupId><artifactId>spring-boot-starter-test</artifactId><scope>test</scope></dependency>

2、新建五张数据表，来展示登录认证和权限校验：

1、用户表

CREATE TABLE users (id INT AUTO_INCREMENT PRIMARY KEY,username VARCHAR(50) NOT NULL UNIQUE,password VARCHAR(100) NOT NULL,email VARCHAR(100) NOT NULL,created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

2、角色表

CREATE TABLE roles (id INT AUTO_INCREMENT PRIMARY KEY,name VARCHAR(50) NOT NULL UNIQUE,description VARCHAR(255),created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

3、权限表

CREATE TABLE permissions (id INT AUTO_INCREMENT PRIMARY KEY,name VARCHAR(50) NOT NULL UNIQUE,description VARCHAR(255),created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

4、用户角色表

CREATE TABLE user_roles (id INT AUTO_INCREMENT PRIMARY KEY,user_id INT NOT NULL,role_id INT NOT NULL,created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,FOREIGN KEY (user_id) REFERENCES users(id),FOREIGN KEY (role_id) REFERENCES roles(id)
);

5、角色权限表

CREATE TABLE role_permissions (id INT AUTO_INCREMENT PRIMARY KEY,role_id INT NOT NULL,permission_id INT NOT NULL,created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,FOREIGN KEY (role_id) REFERENCES roles(id),FOREIGN KEY (permission_id) REFERENCES permissions(id)
);

3、现在我们开始进行基于Sa-Token进行的登录校验和权限认证：

与spring security不同的是，引入了Sa-Token的依赖之后。并不会自动生效，需要我们自己编写相应的逻辑代码；

写一个TestController，用来进行测试；

@RestController
@RequestMapping("/test")
public class TestController {@GetMapping("/hello")public String hello() {System.out.println("说hello啊");return "test接口的hello";}}

我们现在启动项目，并访问/test/hello接口，发现能够正常访问。这一点与spring security是不同的，spring security默认会拦截所有请求；

Sa-Token已经为我们编写了很多我们经常使用的功能，我们只需要在yml配置文件中进行配置即可。以下是一些常用的配置：

############## 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

3.1、登录认证：

使用Sa-Token进行登录认证是非常简单的，只需要一句代码就可以搞定：

// 会话登录：参数填写要登录的账号id，建议的数据类型：long | int | String， 不可以传入复杂类型，如：User、Admin 等等
StpUtil.login(Object id);

只此一句代码，便可以使会话登录成功，实际上，Sa-Token 在背后做了大量的工作，包括但不限于：

检查此账号是否之前已有登录；
为账号生成 Token 凭证与 Session 会话；
记录 Token 活跃时间；
通知全局侦听器，xx 账号登录成功；
将 Token 注入到请求上下文；
等等其它工作……

我们暂时不需要完整了解整个登录过程，只需要记住关键一点：Sa-Token 为这个账号创建了一个Token凭证，且通过 Cookie 上下文返回给了前端。

一个登录接口：

@AutowiredIUsersService usersService;@PostMapping("/login")
public SaResult login(String username, String password){
//根据用户名从数据库中查询Users users = usersService.getOne(new LambdaQueryWrapper<Users>().eq(Users::getUsername, username));if(users == null){return SaResult.error("用户名不存在");}if(!users.getPassword().equals(password)){return SaResult.error("密码错误");}
//根据用户id登录StpUtil.login(users.getId());return SaResult.ok("登录成功");}

运行检验：

发现确实能够登录成功。

此处仅仅做了会话登录，但并没有主动向前端返回 token 信息。是因为不需要吗？严格来讲是需要的，只不过 StpUtil.login(id) 方法利用了 Cookie 自动注入的特性，省略了你手写返回 token 的代码。

如果你对 Cookie 功能还不太了解，也不用担心，我们会在之后的 [ 前后端分离 ] 章节中详细的阐述 Cookie 功能，现在你只需要了解最基本的两点：

Cookie 可以从后端控制往浏览器中写入 token 值。
Cookie 会在前端每次发起请求时自动提交 token 值。

因此，在 Cookie 功能的加持下，我们可以仅靠 StpUtil.login(id) 一句代码就完成登录认证。

除了登录方法，我们还需要：

// 当前会话注销登录
StpUtil.logout();// 获取当前会话是否已经登录，返回true=已登录，false=未登录
StpUtil.isLogin();// 检验当前会话是否已经登录, 如果未登录，则抛出异常：`NotLoginException`
StpUtil.checkLogin();

异常 NotLoginException 代表当前会话暂未登录，可能的原因有很多：前端没有提交 token、前端提交的 token 是无效的、前端提交的 token 已经过期 …… 等等

还有一些登录过程中常用的方法：

// 获取当前会话账号id, 如果未登录，则抛出异常：`NotLoginException`
StpUtil.getLoginId();// 类似查询API还有：
StpUtil.getLoginIdAsString();    // 获取当前会话账号id, 并转化为`String`类型
StpUtil.getLoginIdAsInt();       // 获取当前会话账号id, 并转化为`int`类型
StpUtil.getLoginIdAsLong();      // 获取当前会话账号id, 并转化为`long`类型// ---------- 指定未登录情形下返回的默认值 ----------// 获取当前会话账号id, 如果未登录，则返回 null 
StpUtil.getLoginIdDefaultNull();// 获取当前会话账号id, 如果未登录，则返回默认值 （`defaultValue`可以为任意类型）
StpUtil.getLoginId(T defaultValue);// 获取当前会话的 token 值
StpUtil.getTokenValue();// 获取当前`StpLogic`的 token 名称
StpUtil.getTokenName();// 获取指定 token 对应的账号id，如果未登录，则返回 null
StpUtil.getLoginIdByToken(String tokenValue);// 获取当前会话剩余有效期（单位：s，返回-1代表永久有效）
StpUtil.getTokenTimeout();// 获取当前会话的 token 信息参数
StpUtil.getTokenInfo();

3.1.1前后端分离模式下的登录（无cookie模式）

无 Cookie 模式：特指不支持 Cookie 功能的终端，通俗来讲就是我们常说的 —— 前后端分离模式。

常规 Web 端鉴权方法，一般由 Cookie模式 完成，而 Cookie 有两个特性：

可由后端控制写入。
每次请求自动提交。

这就使得我们在前端代码中，无需任何特殊操作，就能完成鉴权的全部流程（因为整个流程都是后端控制完成的）

而在app、小程序等前后端分离场景中，一般是没有 Cookie 这一功能的，此时大多数人都会一脸懵逼，咋进行鉴权啊？

见招拆招，其实答案很简单：

不能后端控制写入了，就前端自己写入。（后端将登录成功之后生成的Token 传递到前端）
每次请求不能自动提交了，那就手动提交。（前端将登陆成功后获取的Token封装到请求头中每次请求时都携带，后端将其读取出来，并判断用户信息）

修改我们之前写的登录接口，返回token给前端；

 @PostMapping("/login")
public SaResult login(String username, String password){
//根据用户名从数据库中查询Users users = usersService.getOne(new LambdaQueryWrapper<Users>().eq(Users::getUsername, username));if(users == null){return SaResult.error("用户名不存在");}if(!users.getPassword().equals(password)){return SaResult.error("密码错误");}
//根据用户id登录，第1步，先登录上StpUtil.login(users.getId());// 第2步，获取 Token  相关参数 SaTokenInfo tokenInfo = StpUtil.getTokenInfo();// 第3步，返回给前端 return SaResult.data(tokenInfo);}

在进行一次登录：

可以看到登录成功之后，返回了很多相关的数据，而我们的token也在其中，那么前端就可以将token取出来放到一个状态管理器（pinia中），并且在每次请求时都将token放在请求头中。

如果你对 Cookie 非常了解，那你就会明白，所谓 Cookie ，本质上就是一个特殊的header参数而已，而既然它只是一个 header 参数，我们就能手动模拟实现它，从而完成鉴权操作。

3.1.2路由拦截鉴权：

假设我们有如下需求：

项目中所有接口均需要登录认证，只有 “登录接口” 本身对外开放

我们怎么实现呢？给每个接口加上鉴权注解？手写全局拦截器？似乎都不是非常方便。

在这个需求中我们真正需要的是一种基于路由拦截的鉴权模式，那么在Sa-Token怎么实现路由拦截鉴权呢？

@Configuration
public class SaTokenConfigure implements WebMvcConfigurer {// 注册拦截器@Overridepublic void addInterceptors(InterceptorRegistry registry) {// 注册 Sa-Token 拦截器，校验规则为 StpUtil.checkLogin() 登录校验。registry.addInterceptor(new SaInterceptor(handle -> StpUtil.checkLogin())).addPathPatterns("/**").excludePathPatterns("/users/login");}}

以上代码，我们注册了一个基于 StpUtil.checkLogin() 的登录校验拦截器，并且排除了/user/login接口用来开放登录（除了/user/login以外的所有接口都需要登录才能访问）这就与我们spring security有了一点点相似了，因为spring security默认的就是所有的接口都被拦截到。

我们再启动项目，并访问我们最开始写的/test/hello接口；

可以看到这个接口被拦截了。那么我们带上之前登录成功，生成的token之后再去访问呢？

可以看到我们成功访问了这个接口；

new SaInterceptor(handle -> StpUtil.checkLogin()) 是最简单的写法，代表只进行登录校验功能。实际上Sa-Token还可以实现一些更详细的校验规则，在Sa-Token的官网上可以看到。

3.2权限认证：

我们已经了解了常用的登录认证方法，接下来，我们来看一下权限认证；

1、获取当前用户的权限码集合：

因为每个项目的需求不同，其权限设计也千变万化，因此 [ 获取当前账号权限码集合 ] 这一操作不可能内置到框架中，所以 Sa-Token 将此操作以接口的方式暴露给你，以方便你根据自己的业务逻辑进行重写。

你需要做的就是新建一个类，实现 StpInterface接口

/*** 自定义权限加载接口实现类*/
@Component    // 保证此类被 SpringBoot 扫描，完成 Sa-Token 的自定义权限验证扩展
public class StpInterfaceImpl implements StpInterface {/*** 返回一个账号所拥有的权限码集合 *///    角色权限表@AutowiredIRolePermissionsService rolePermissionsService;
//    用户角色表@AutowiredIUserRolesService userRolesService;
//权限表@AutowiredIPermissionsService permissionsService;//    角色表@AutowiredIRolesService rolesService;@Overridepublic List<String> getPermissionList(Object loginId, String loginType) {
//        根据用户id从用户角色表中获取角色idList<UserRoles> roleIds = userRolesService.list(new LambdaQueryWrapper<UserRoles>().eq(UserRoles::getUserId,Integer.parseInt(loginId.toString())));List<Integer> rolesList = roleIds.stream().map(UserRoles::getRoleId).toList();
if (!(rolesList.size() >0)){
//    没有任何权限return null;
}List<String> list = new ArrayList<>();rolesList.forEach(roleId ->{// 根据角色id从角色权限表中获取权限id   List<RolePermissions> rolePermissions = rolePermissionsService.list(new LambdaQueryWrapper<RolePermissions>().eq(RolePermissions::getRoleId, roleId));// 根据权限id从权限表中获取权限名称rolePermissions.forEach(permissionsId->{Permissions permissions = permissionsService.getById(permissionsId.getPermissionId());list.add(permissions.getName());});});// 返回用户所有权限，return list;}/*** 返回一个账号所拥有的角色标识集合 (权限与角色可分开校验)*/@Overridepublic List<String> getRoleList(Object loginId, String loginType) {// 本 list 仅做模拟，实际项目中要根据具体业务逻辑来查询角色//        根据用户id从用户角色表中获取角色idList<UserRoles> roleIds = userRolesService.list(new LambdaQueryWrapper<UserRoles>().eq(UserRoles::getUserId,Integer.parseInt(loginId.toString())));List<String> list = new ArrayList<>();if (!(roleIds.size() >0)){
//            用户没有分配角色return null;}roleIds.forEach(roleId ->{Roles byId = rolesService.getById(roleId.getRoleId());list.add(byId.getName());});
//        返回用户所有角色标识集合return list;}}

我所实现的是标准的RBAC（基于用户、角色、权限的访问控制模型）。所以，在得到用户id的情况下、先根据用户角色表查出角色id、在根据角色权限表查询权限id，在根据权限表查出具体权限名称。

上面使用了Mybatis-plus的条件构造器和stream流的形式进行查询。

参数解释：

loginId：账号id，即你在调用 StpUtil.login(id) 时写入的标识值。
loginType：账号体系标识，此处可以暂时忽略，在 [ 多账户认证 ] 章节下会对这个概念做详细的解释。

有同学会产生疑问：我实现了此接口，但是程序启动时好像并没有执行，是不是我写错了？答：不执行是正常现象，程序启动时不会执行这个接口的方法，在每次调用鉴权代码时，才会执行到此。

权限校验：
然后就可以用以下 api 来鉴权了：

// 获取：当前账号所拥有的权限集合
StpUtil.getPermissionList();// 判断：当前账号是否含有指定权限, 返回 true 或 false
StpUtil.hasPermission("user.add");        // 校验：当前账号是否含有指定权限, 如果验证未通过，则抛出异常: NotPermissionException 
StpUtil.checkPermission("user.add");        // 校验：当前账号是否含有指定权限 [指定多个，必须全部验证通过]
StpUtil.checkPermissionAnd("user.add", "user.delete", "user.get");        // 校验：当前账号是否含有指定权限 [指定多个，只要其一验证通过即可]
StpUtil.checkPermissionOr("user.add", "user.delete", "user.get");

扩展：NotPermissionException 对象可通过 getLoginType() 方法获取具体是哪个 StpLogic 抛出的异常

角色校验：
在 Sa-Token 中，角色和权限可以分开独立验证

// 获取：当前账号所拥有的角色集合
StpUtil.getRoleList();// 判断：当前账号是否拥有指定角色, 返回 true 或 false
StpUtil.hasRole("super-admin");        // 校验：当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException
StpUtil.checkRole("super-admin");        // 校验：当前账号是否含有指定角色标识 [指定多个，必须全部验证通过]
StpUtil.checkRoleAnd("super-admin", "shop-admin");        // 校验：当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可] 
StpUtil.checkRoleOr("super-admin", "shop-admin");

扩展：NotRoleException 对象可通过 getLoginType() 方法获取具体是哪个 StpLogic 抛出的异常

权限通配符：
Sa-Token允许你根据通配符指定泛权限，例如当一个账号拥有art.*的权限时，art.add、art.delete、art.update都将匹配通过

// 当拥有 art.* 权限时
StpUtil.hasPermission("art.add");        // true
StpUtil.hasPermission("art.update");     // true
StpUtil.hasPermission("goods.add");      // false// 当拥有 *.delete 权限时
StpUtil.hasPermission("art.delete");      // true
StpUtil.hasPermission("user.delete");     // true
StpUtil.hasPermission("user.update");     // false// 当拥有 *.js 权限时
StpUtil.hasPermission("index.js");        // true
StpUtil.hasPermission("index.css");       // false
StpUtil.hasPermission("index.html");      // false

上帝权限：当一个账号拥有 "*" 权限时，他可以验证通过任何权限码（角色认证同理）

在我们的项目的TestController中进行测试：

  @GetMapping("/hello")public String hello() {System.out.println("验证权限，是否具有‘所有权限’===============>"+StpUtil.hasPermission("所有权限"));System.out.println("验证角色，是否具有‘管理员’角色===============>"+StpUtil.hasRole("管理员"));  System.out.println("说hello啊");return "test接口的hello";}

我们测试的最终结果：

可以看到确实输出了两个true。并且，只有在每次调用鉴权代码时，才会执行到我们自定义的权限方法中。

总结：

我本来是想写一篇介绍spring boot项目中整合Sa-Token来实现最常用的登录校验和权限认证的，但是写着写着就变成官网的复制机了。我在本篇文章中大量复制了官网上的内容，原本只是想复制一些官方介绍就行了。但是这也从侧面说明了Sa-Token官网制作的确实是比较好的，基本上不需要额外的学习，只要你有做过登录和权限方面的项目经验，再看一遍官网的介绍就能直接上手了。

我之前写过一个B2C模式的购物商台，分为用户端和管理端。管理端的登录和权限校验是用spring security写的。现在又了解了Sa-Token之后，真的还是认为Sa-Token的使用是比较简单的。（也可能是我的项目还是比较简单的，并没有多少权限要实现）并且这也是我们国人写的开源框架，在一些方法的封装、Api的设计上还是能直接理解的。在这里也算是为Sa-Token这个框架打个广告吧，希望大家还是能够多多支持国产，国内的开源之路也是充满了坎坷与艰辛。