ContextQMD
Back to Sa Token

和 jwt 集成

sa-token-doc/plugin/jwt-extend.md

1.45.07.5 KB
Original Source

和 jwt 集成

本插件的作用是让 Sa-Token 和 jwt 做一个整合。

1、引入依赖

首先在项目已经引入 Sa-Token 的基础上，继续添加：

<!---------------------------- tabs:start ----------------------------> <!-------- tab:Maven 方式 -------->
xml
<!-- Sa-Token 整合 jwt -->
<dependency>
	<groupId>cn.dev33</groupId>
	<artifactId>sa-token-jwt</artifactId>
	<version>${sa.top.version}</version>
</dependency>
<!-------- tab:Gradle 方式 -------->
gradle
// Sa-Token 整合 jwt
implementation 'cn.dev33:sa-token-jwt:${sa.top.version}'
<!---------------------------- tabs:end ---------------------------->

[!WARNING| label:版本兼容性]

  1. 注意: sa-token-jwt 显式依赖 hutool-jwt 5.7.14 版本，保险起见：你的项目中要么不引入 hutool，要么引入版本 >= 5.7.14 的 hutool 版本。
  2. hutool 5.8.13 和 5.8.14 版本下会出现类型转换问题，关联issue。

2、配置秘钥

在 application.yml 配置文件中配置 jwt 生成秘钥：

<!---------------------------- tabs:start ----------------------------> <!------------- tab:yaml 风格 ------------->
yaml
sa-token:
	# jwt秘钥 
	jwt-secret-key: asdasdasifhueuiwyurfewbfjsdafjk
<!------------- tab:properties 风格 ------------->
properties
# jwt秘钥 
sa-token.jwt-secret-key: asdasdasifhueuiwyurfewbfjsdafjk
<!---------------------------- tabs:end ---------------------------->

注：为了安全起见请不要直接复制官网示例这个字符串（随便按几个字符就好了）

3、注入jwt实现

根据不同的整合规则，插件提供了三种不同的模式，你需要 选择其中一种 注入到你的项目中

<!------------------------------ tabs:start ------------------------------> <!-- tab: Simple 简单模式 -->

Simple 模式：Token 风格替换

java
@Configuration
public class SaTokenConfigure {
    // Sa-Token 整合 jwt (Simple 简单模式)
	@Bean
    public StpLogic getStpLogicJwt() {
    	return new StpLogicJwtForSimple();
    }
}
<!-- tab: Mixin 混入模式 -->

Mixin 模式：混入部分逻辑

java
@Configuration
public class SaTokenConfigure {
    // Sa-Token 整合 jwt (Mixin 混入模式)
	@Bean
    public StpLogic getStpLogicJwt() {
    	return new StpLogicJwtForMixin();
    }
}
<!-- tab: Stateless 无状态模式 -->

Stateless 模式：服务器完全无状态

java
@Configuration
public class SaTokenConfigure {
    // Sa-Token 整合 jwt (Stateless 无状态模式)
	@Bean
    public StpLogic getStpLogicJwt() {
    	return new StpLogicJwtForStateless();
    }
}
<!---------------------------- tabs:end ------------------------------>

4、开始使用

然后我们就可以像之前一样使用 Sa-Token 了

java
/**
 * 登录测试 
 */
@RestController
@RequestMapping("/acc/")
public class LoginController {

    // 测试登录
    @RequestMapping("login")
    public SaResult login() {
		StpUtil.login(10001);
        return SaResult.ok("登录成功");
    }

    // 查询登录状态
    @RequestMapping("isLogin")
    public SaResult isLogin() {
        return SaResult.ok("是否登录：" + StpUtil.isLogin());
    }

    // 测试注销
    @RequestMapping("logout")
    public SaResult logout() {
        StpUtil.logout();
        return SaResult.ok();
    }

}

访问上述接口，观察Token生成的样式

java
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbklkIjoiMTAwMDEiLCJybiI6IjZYYzgySzBHVWV3Uk5NTTl1dFdjbnpFZFZHTVNYd3JOIn0.F_7fbHsFsDZmckHlGDaBuwDotZwAjZ0HB14DRujQfOQ

5、不同模式策略对比

注入不同模式会让框架具有不同的行为策略，以下是三种模式的差异点（为方便叙述，以下比较以同时引入 jwt 与 Redis 作为前提）：

功能点Simple 简单模式Mixin 混入模式Stateless 无状态模式
Token风格jwt风格jwt风格jwt风格
登录数据存储Redis中存储Token中存储Token中存储
Session存储Redis中存储Redis中存储无Session
注销下线前后端双清数据前后端双清数据前端清除数据
踢人下线API支持不支持不支持
顶人下线API支持不支持不支持
登录认证支持支持支持
角色认证支持支持支持
权限认证支持支持支持
timeout 有效期支持支持支持
active-timeout 有效期支持支持不支持
id反查Token支持支持不支持
会话管理支持部分支持不支持
注解鉴权支持支持支持
路由拦截鉴权支持支持支持
账号封禁支持支持不支持
身份切换支持支持支持
二级认证支持支持支持
模式总结Token风格替换jwt 与 Redis 逻辑混合完全舍弃Redis，只用jwt

6、扩展参数

你可以通过以下方式在登录时注入扩展参数：

java
// 登录10001账号，并为生成的 Token 追加扩展参数name
StpUtil.login(10001, new SaLoginParameter().setExtra("name", "zhangsan"));

// 连缀写法追加多个
StpUtil.login(10001, new SaLoginParameter()
				.setExtra("name", "zhangsan")
				.setExtra("age", 18)
				.setExtra("role", "超级管理员"));

// 获取扩展参数 
String name = StpUtil.getExtra("name");

// 获取任意 Token 的扩展参数 
String name = StpUtil.getExtra("tokenValue", "name");

7、在多账户模式中集成 jwt

sa-token-jwt 插件默认只为 StpUtil 注入 StpLogicJwtFoxXxx 实现，自定义的 StpUserUtil 是不会自动注入的，我们需要帮其手动注入：

java
/**
 * 为 StpUserUtil 注入 StpLogicJwt 实现 
 */
@PostConstruct
public void setUserStpLogic() {
	StpUserUtil.setStpLogic(new StpLogicJwtForSimple(StpUserUtil.TYPE));
}

8、自定义 SaJwtUtil 生成 token 的算法

如果需要自定义生成 token 的算法（例如更换sign方式），直接重写 SaJwtTemplate 对象即可：

java
/**
 * 自定义 SaJwtUtil 生成 token 的算法 
 */
@PostConstruct
public void setSaJwtTemplate() {
	SaJwtUtil.setSaJwtTemplate(new SaJwtTemplate() {
		@Override
		public String generateToken(JWT jwt, String keyt) {
			System.out.println("------ 自定义了 token 生成算法");
			return super.generateToken(jwt, keyt);
		}
	});
}

9、注意点

1、使用 jwt-simple 模式后，is-share=false 恒等于 false。

is-share=true 的意思是每次登录都产生一样的 token，这种策略和 [ 为每个 token 单独设定 setExtra 数据 ] 不兼容的， 为保证正确设定 Extra 数据，当使用 jwt-simple 模式后，is-share 配置项 恒等于 false。

2、使用 jwt-mixin 模式后，is-concurrent 必须为 true。

is-concurrent=false 代表每次登录都把旧登录顶下线，但是 jwt-mixin 模式登录的 token 并不会记录在持久库数据中， 技术上来讲无法将其踢下线，所以此时顶人下线和踢人下线等 API 都属于不可用状态，所以此时 is-concurrent 配置项必须配置为 true。

3、使用 jwt-mixin 模式后，max-try-times 恒等于 -1。

为防止框架错误判断 token 唯一性，当使用 jwt-mixin 模式后，max-try-times 恒等于 -1。