# StpUtil - 鉴权工具类

StpUtil 是 Sa-Token 整体功能的核心，大多数功能均由此工具类提供。

--- 

### 1、常规操作 
``` java
StpUtil.getStpLogic();   // 获取底层 StpLogic 对象。
StpUtil.setStpLogic(newStpLogic);   // 安全的重置底层 StpLogic 引用。
StpUtil.getLoginType();   // 获取账号类型 （例如：login、user、admin、teacher、student等等）。
StpUtil.getTokenName();   // 获取 Token 的名称 
StpUtil.getTokenValue();   // 获取本次请求前端提交的 Token。
StpUtil.getTokenValueNotCut();   // 获取本次请求前端提交的 Token (不裁剪前缀) 。
StpUtil.setTokenValue(tokenValue);   // 在当前会话中写入 Token 值。
StpUtil.setTokenValue(tokenValue, timeout);   // 在当前会话中写入 Token 值，并指定 Cookie 有效期。
StpUtil.setTokenValue(tokenValue, loginParameter);   // 在当前会话中写入 Token 值，并指定登录参数。
StpUtil.setTokenValueToStorage(tokenValue);   // 将 Token 写入当前请求的 Storage 存储器。
StpUtil.getTokenInfo();   // 获取当前 Token 的详细参数。
```


### 2、登录相关  
``` java
StpUtil.login(10001);   // 会话登录
StpUtil.login(10001, "APP");   // 会话登录，并指定设备类型
StpUtil.login(10001, true);   // 会话登录，并指定是否 [记住我]
StpUtil.login(10001, 86400);   // 会话登录，并指定此次 token 有效期（单位：秒）
StpUtil.login(10001, loginParameter);   // 会话登录，并指定所有登录参数Model
StpUtil.createLoginSession(10001);   // 创建指定账号id的登录会话，此方法不会将 Token 注入到上下文 
StpUtil.createLoginSession(10001, loginParameter);   // 创建指定账号id的登录会话，此方法不会将 Token 注入到上下文 
StpUtil.getOrCreateLoginSession(10001);   // 获取指定账号的登录会话，若不存在则创建并返回
```

更多 SaLoginParameter 登录参数的用法与示例，请参考 [登录参数示例章节](/up/login-parameter)。


### 3、注销相关
``` java
StpUtil.logout();   // 会话注销 
StpUtil.logout(logoutParameter);   // 会话注销，根据注销参数
StpUtil.logout(10001);   // 会话注销，根据账号id
StpUtil.logout(10001, "PC");   // 会话注销，根据账号id 和 设备类型
StpUtil.logout(10001, logoutParameter);   // 会话注销，根据账号id 和 注销参数
StpUtil.logoutByTokenValue(token);   // 指定 Token 强制注销
StpUtil.logoutByTokenValue(token, logoutParameter);   // 指定 Token 强制注销，带注销参数
StpUtil.kickout(10001);   // 踢人下线，根据账号id
StpUtil.kickout(10001, "PC");   // 踢人下线，根据账号id 和 设备类型
StpUtil.kickout(10001, logoutParameter);   // 踢人下线，根据账号id 和 注销参数
StpUtil.kickoutByTokenValue(token);   // 踢人下线，根据token
StpUtil.kickoutByTokenValue(token, logoutParameter);   // 踢人下线，根据token，带注销参数
StpUtil.replacedByTokenValue(token);   // 顶人下线，根据token
StpUtil.replacedByTokenValue(token, logoutParameter);   // 顶人下线，根据token，带注销参数
StpUtil.replaced(10001);   // 顶人下线，根据账号id
StpUtil.replaced(10001, "PC");   // 顶人下线，根据账号id 和 设备类型
StpUtil.replaced(10001, logoutParameter);   // 顶人下线，根据账号id 和 注销参数
```

更多 SaLogoutParameter 注销参数的用法与示例，请参考 [注销参数示例章节](/up/login-parameter?id=_2、注销参数)。


### 4、会话查询
``` java
StpUtil.isLogin();   // 当前会话是否已经登录 
StpUtil.isLogin(10001);   // 判断指定账号是否已登录
StpUtil.checkLogin();   // 检验当前会话是否已经登录，如未登录，则抛出异常
StpUtil.getLoginId();   // 获取当前会话账号id, 如果未登录，则抛出异常 
StpUtil.getLoginId(defaultValue);   // 获取当前会话账号id, 如果未登录，则返回默认值 
StpUtil.getLoginIdDefaultNull();   // 获取当前会话账号id, 如果未登录，则返回null 
StpUtil.getLoginIdAsString();   // 获取当前会话账号id, 并转换为String类型
StpUtil.getLoginIdAsInt();   // 获取当前会话账号id, 并转换为int类型
StpUtil.getLoginIdAsLong();   // 获取当前会话账号id, 并转换为long类型 
StpUtil.getLoginIdByToken(token);   // 获取指定Token对应的账号id，如果未登录，则返回 null 
StpUtil.getLoginIdByTokenNotThinkFreeze(token);   // 获取指定Token对应的账号id（不考虑冻结状态），如果未登录，则返回 null 
StpUtil.getExtra(key);   // 获取当前 Token 的扩展信息（此函数只在jwt模式下生效）
StpUtil.getExtra(token, key);   // 获取指定 Token 的扩展信息（此函数只在jwt模式下生效）
```


### 5、Session 相关
``` java
// Account-Session 相关 
StpUtil.getSession();   // 获取当前会话的Session，如果Session尚未创建，则新建并返回 
StpUtil.getSession(true);   // 获取当前会话的Session, 如果Session尚未创建，isCreate=是否新建并返回
StpUtil.getSessionByLoginId(10001);   // 获取指定账号id的Session，如果Session尚未创建，则新建并返回
StpUtil.getSessionByLoginId(10001, true);   // 获取指定账号id的Session, 如果Session尚未创建，isCreate=是否新建并返回

// Token-Session 相关 
StpUtil.getTokenSession();   // 获取当前会话的Session，如果Session尚未创建，则新建并返回 
StpUtil.getTokenSessionByToken(token);   // 获取指定Token-Session，如果Session尚未创建，则新建并返回
StpUtil.getAnonTokenSession();   // 获取当前匿名 Token-Session （可在未登录情况下使用的Token-Session）

// 其它
StpUtil.getSessionBySessionId("xxxx-xxxx-xxxx");   // 获取指定 sessionId 的 Session，若不存在则返回 null
StpUtil.isTrustDeviceId(123456, "xxxxxxxxxxxxxxxxxxxxxxxx");   // 判断对于指定 loginId 来讲，指定设备 id 是否为可信任设备
```


### 6、Token有效期相关
``` java
// Token 最低活跃频率
StpUtil.getTokenActiveTimeout();   // 获取当前 token 距离被冻结还剩多少时间 (单位: 秒)
StpUtil.getTokenLastActiveTime();  // 获取当前 token 最后活跃时间
StpUtil.checkActiveTimeout();   // 检查当前token 是否已经被冻结，如果是则抛出异常  
StpUtil.updateLastActiveToNow();   // 续签当前token：(将 [最后操作时间] 更新为当前时间戳)   

// Token 有效期
StpUtil.getTokenTimeout();   // 获取当前登录者的 token 剩余有效时间 (单位: 秒)
StpUtil.getTokenTimeout(token);   // 获取指定 token 的剩余有效时间 (单位: 秒)
StpUtil.getSessionTimeout();   // 获取当前登录者的 Account-Session 剩余有效时间 (单位: 秒)
StpUtil.getTokenSessionTimeout();   // 获取当前 Token-Session 剩余有效时间 (单位: 秒) 
StpUtil.renewTimeout(timeout);   // 对当前 Token 的 timeout 值进行续期 
StpUtil.renewTimeout(token, timeout);   // 对指定 Token 的 timeout 值进行续期 
```


### 7、角色认证
``` java
StpUtil.getRoleList();   // 获取：当前账号的角色集合
StpUtil.getRoleList(10001);   // 获取：指定账号的角色集合 
StpUtil.hasRole(role);   // 判断：当前账号是否拥有指定角色, 返回true或false 
StpUtil.hasRole(loginId, role);   // 判断：指定账号是否含有指定角色标识, 返回true或false 
StpUtil.hasRoleAnd(...roleArray);   // 判断：当前账号是否含有指定角色标识 [指定多个，必须全部验证通过] 
StpUtil.hasRoleOr(...roleArray);   // 判断：当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可] 
StpUtil.checkRole(role);   // 校验：当前账号是否含有指定角色标识, 如果验证未通过，则抛出异常: NotRoleException 
StpUtil.checkRoleAnd(...roleArray);   // 校验：当前账号是否含有指定角色标识 [指定多个，必须全部验证通过] 
StpUtil.checkRoleOr(...roleArray);   // 校验：当前账号是否含有指定角色标识 [指定多个，只要其一验证通过即可] 
```


### 8、权限认证
``` java
StpUtil.getPermissionList();   // 获取：当前账号的权限集合
StpUtil.getPermissionList(10001);   // 获取：指定账号的权限集合 
StpUtil.hasPermission(permission);   // 判断：当前账号是否拥有指定权限, 返回true或false 
StpUtil.hasPermission(loginId, permission);   // 判断：指定账号是否含有指定权限标识, 返回true或false 
StpUtil.hasPermissionAnd(...permissionArray);   // 判断：当前账号是否含有指定权限标识 [指定多个，必须全部验证通过] 
StpUtil.hasPermissionOr(...permissionArray);   // 判断：当前账号是否含有指定权限标识 [指定多个，只要其一验证通过即可] 
StpUtil.checkPermission(permission);   // 校验：当前账号是否含有指定权限标识, 如果验证未通过，则抛出异常: NotPermissionException 
StpUtil.checkPermissionAnd(...permissionArray);   // 校验：当前账号是否含有指定权限标识 [指定多个，必须全部验证通过] 
StpUtil.checkPermissionOr(...permissionArray);   // 校验：当前账号是否含有指定权限标识 [指定多个，只要其一验证通过即可] 
```


### 9、id 反查 Token
``` java
StpUtil.getTokenValueByLoginId(10001);   // 获取指定账号id的tokenValue 
StpUtil.getTokenValueByLoginId(10001, "PC");   // 获取指定账号id指定设备类型端的tokenValue
StpUtil.getTokenValueListByLoginId(10001);   // 获取指定账号id的tokenValue集合 
StpUtil.getTokenValueListByLoginId(10001, "APP");   // 获取指定账号id指定设备类型端的tokenValue 集合 
StpUtil.getTerminalListByLoginId(10001);   // 获取指定账号 id 已登录设备信息集合
StpUtil.getTerminalListByLoginId(10001, "PC");   // 获取指定账号 id 指定设备类型端的已登录设备信息集合
StpUtil.forEachTerminalList(10001, (terminal) -> {});   // 遍历指定账号的已登录设备列表
StpUtil.getTerminalInfo();   // 获取当前会话的终端信息
StpUtil.getTerminalInfoByToken(token);   // 获取指定 token 的终端信息
StpUtil.getLoginDeviceId();   // 返回当前会话的登录设备 id
StpUtil.getLoginDeviceIdByToken(token);   // 返回指定 token 的登录设备 id
StpUtil.getLoginDeviceType();   // 返回当前会话的登录设备类型
StpUtil.getLoginDeviceTypeByToken(token);   // 返回指定 token 的登录设备类型
```


### 10、会话管理
``` java
StpUtil.searchTokenValue(keyword, start, size, sortType);   // 根据条件查询Token
StpUtil.searchSessionId(keyword, start, size, sortType);   // 根据条件查询SessionId 
StpUtil.searchTokenSessionId(keyword, start, size, sortType);   // 根据条件查询Token专属Session的Id 
```
详细可参考：[会话治理](/up/search-session)


### 11、账号封禁
``` java
StpUtil.disable(10001, 1200);   // 封禁：指定账号 指定时间(单位s)
StpUtil.isDisable(10001);   // 判断：指定账号是否已被封禁 (true=已被封禁, false=未被封禁) 
StpUtil.checkDisable(10001);   // 校验：指定账号是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`
StpUtil.getDisableTime(10001);   // 获取：指定账号剩余封禁时间，单位：秒（-1=永久封禁，-2=未被封禁）
StpUtil.untieDisable(loginId);   // 解封：指定账号
```


### 12、分类封禁 (version >= 1.31.0)
``` java
StpUtil.disable(10001, "<业务标识>", 86400);   // 封禁：指定账号的指定服务 指定时间(单位s)
StpUtil.isDisable(10001, "<业务标识>");   // 判断：指定账号的指定服务 是否已被封禁 (true=已被封禁, false=未被封禁) 
StpUtil.checkDisable(10001, "<业务标识>");   // 校验：指定账号的指定服务 是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`（支持传入多个业务标识）
StpUtil.getDisableTime(10001, "<业务标识>");   // 获取：指定账号的指定服务 剩余封禁时间，单位：秒（-1=永久封禁，-2=未被封禁）
StpUtil.untieDisable(loginId, "<业务标识>");   // 解封：指定账号的指定服务（支持传入多个业务标识）
```


### 13、阶梯封禁 (version >= 1.31.0)
``` java
StpUtil.disableLevel(10001, "comment", 3, 10000);   // 分类阶梯封禁，参数：封禁账号、封禁服务、封禁级别、封禁时间 
StpUtil.disableLevel(10001, 3, 10000);   // 阶梯封禁（无业务标识，使用默认服务），参数：封禁账号、封禁级别、封禁时间
StpUtil.getDisableLevel(10001, "comment");   // 获取：指定账号的指定服务 封禁的级别 （如果此账号未被封禁则返回 -2）
StpUtil.getDisableLevel(10001);   // 获取：指定账号的封禁等级（无业务标识，未封禁返回 -2）
StpUtil.isDisableLevel(10001, "comment", 3);   // 判断：指定账号的指定服务 是否已被封禁到指定级别，返回 true 或 false
StpUtil.isDisableLevel(10001, 3);   // 判断：指定账号是否被封禁到指定级别（无业务标识）
StpUtil.checkDisableLevel(10001, "comment", 2);   // 校验：指定账号的指定服务 是否已被封禁到指定级别（例如 comment服务 已被3级封禁，这里校验是否达到2级），如果已达到此级别，则抛出异常 
StpUtil.checkDisableLevel(10001, 2);   // 校验：指定账号是否被封禁到指定级别（无业务标识）
```


### 14、身份切换
``` java
StpUtil.switchTo(10044);   // 临时切换身份为指定账号id 
StpUtil.endSwitch();   // 结束临时切换身份
StpUtil.isSwitch();   // 当前是否正处于[身份临时切换]中 
StpUtil.switchTo(10044, () -> {});   // 在一个代码段里方法内，临时切换身份为指定账号id
```


### 15、二级认证
``` java
StpUtil.openSafe(safeTime);   // 在当前会话 开启二级认证 
StpUtil.isSafe();   // 当前会话 是否处于二级认证时间内 
StpUtil.checkSafe();   // 检查当前会话是否已通过二级认证，如未通过则抛出异常 
StpUtil.getSafeTime();   // 获取当前会话的二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
StpUtil.closeSafe();   // 在当前会话 结束二级认证 
```


### 16、带有业务标识的二级认证
``` java
StpUtil.openSafe("<业务标识>", safeTime);   // 在当前会话 指定业务标识开启二级认证 
StpUtil.isSafe("<业务标识>");   // 当前会话 指定业务标识是否处于二级认证时间内 
StpUtil.isSafe(tokenValue, "<业务标识>");   // 判断指定 token 的指定业务是否处于二级认证时间内
StpUtil.checkSafe("<业务标识>");   // 检查当前会话，指定业务标识是否已通过二级认证，如未通过则抛出异常 
StpUtil.getSafeTime("<业务标识>");   // 获取当前会话的指定业务标识二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
StpUtil.closeSafe("<业务标识>");   // 在当前会话 结束指定业务标识二级认证 
```


