public/sa-token
1
0
Fork 0
mirror of https://gitee.com/dromara/sa-token.git synced 2026-05-14 04:42:09 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: 补全 StpUtil API 说明文档

Browse Source
This commit is contained in:
click33
2026-03-08 13:35:30 +08:00
parent 024d6e0491
commit 98f4de6514
1 changed files with 35 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
sa-token-doc/api/stp-util.md
View File

@@ -14,6 +14,8 @@ 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 的详细参数。
```
@@ -23,47 +25,44 @@ StpUtil.getTokenInfo(); // 获取当前 Token 的详细参数。
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 配置示例：
``` java
// SaLoginParameter 配置登录相关参数
StpUtil.login(10001, new SaLoginParameter()
.setDeviceType("PC") // 此次登录的客户端设备类型, 一般用于完成 [同端互斥登录] 功能
.setDeviceId("xxxxxxxxx") // 此次登录的客户端设备ID, 登录成功后该设备将标记为可信任设备
.setIsLastingCookie(true) // 是否为持久Cookie（临时Cookie在浏览器关闭时会自动删除，持久Cookie在重新打开后依然存在）
.setTimeout(60 * 60 * 24 * 7) // 指定此次登录 token 的有效期, 单位:秒，-1=永久有效
.setActiveTimeout(60 * 60 * 24 * 7) // 指定此次登录 token 的最低活跃频率, 单位:秒，-1=不进行活跃检查
.setIsConcurrent(true) // 是否允许同一账号多地同时登录 （为 true 时允许一起登录, 为 false 时新登录挤掉旧登录）
.setIsShare(false) // 在多人登录同一账号时，是否共用一个 token （为 true 时所有登录共用一个token, 为 false 时每次登录新建一个 token）
.setMaxLoginCount(12) // 同一账号最大登录数量，-1代表不限 （只有在 isConcurrent=true, isShare=false 时此配置项才有意义）
.setMaxTryTimes(12) // 在每次创建 token 时的最高循环次数，用于保证 token 唯一性（-1=不循环尝试，直接使用）
.setExtra("key", "value") // 记录在 Token 上的扩展参数（只在 jwt 模式下生效）
.setToken("xxxx-xxxx-xxxx-xxxx") // 预定此次登录的生成的Token
.setIsWriteHeader(false) // 是否在登录后将 Token 写入到响应头
.setTerminalExtra("key", "value")// 本次登录挂载到 SaTerminalInfo 的自定义扩展数据
);
```
更多 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, 如果未登录，则返回默认值
@@ -72,6 +71,7 @@ StpUtil.getLoginIdAsString(); // 获取当前会话账号id, 并转换为Strin
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模式下生效）
```
@@ -91,7 +91,7 @@ StpUtil.getTokenSessionByToken(token); // 获取指定Token-Session，如果Se
StpUtil.getAnonTokenSession(); // 获取当前匿名 Token-Session （可在未登录情况下使用的Token-Session）
// 其它
StpUtil.getSessionBySessionId("xxxx-xxxx-xxxx"); // 获取指定key的Session, 如果Session尚未创建，则返回 null
StpUtil.getSessionBySessionId("xxxx-xxxx-xxxx"); // 获取指定 sessionId 的 Session，若不存在则返回 null
StpUtil.isTrustDeviceId(123456, "xxxxxxxxxxxxxxxxxxxxxxxx"); // 判断对于指定 loginId 来讲，指定设备 id 是否为可信任设备
```
@@ -106,6 +106,7 @@ StpUtil.updateLastActiveToNow(); // 续签当前token：(将 [最后操作时
// Token 有效期
StpUtil.getTokenTimeout(); // 获取当前登录者的 token 剩余有效时间 (单位: 秒)
StpUtil.getTokenTimeout(token); // 获取指定 token 的剩余有效时间 (单位: 秒)
StpUtil.getSessionTimeout(); // 获取当前登录者的 Account-Session 剩余有效时间 (单位: 秒)
StpUtil.getTokenSessionTimeout(); // 获取当前 Token-Session 剩余有效时间 (单位: 秒)
StpUtil.renewTimeout(timeout); // 对当前 Token 的 timeout 值进行续期
@@ -149,8 +150,13 @@ StpUtil.getTokenValueListByLoginId(10001); // 获取指定账号id的tokenValu
StpUtil.getTokenValueListByLoginId(10001, "APP"); // 获取指定账号id指定设备类型端的tokenValue 集合
StpUtil.getTerminalListByLoginId(10001); // 获取指定账号 id 已登录设备信息集合
StpUtil.getTerminalListByLoginId(10001, "PC"); // 获取指定账号 id 指定设备类型端的已登录设备信息集合
StpUtil.getLoginDevice(); // 返回当前会话的登录设备类型
StpUtil.getLoginDeviceByToken(xxx); // 返回任意 token 的登录设备类型
StpUtil.forEachTerminalList(10001, (terminal) -> {}); // 遍历指定账号的已登录设备列表
StpUtil.getTerminalInfo(); // 获取当前会话的终端信息
StpUtil.getTerminalInfoByToken(token); // 获取指定 token 的终端信息
StpUtil.getLoginDeviceId(); // 返回当前会话的登录设备 id
StpUtil.getLoginDeviceIdByToken(token); // 返回指定 token 的登录设备 id
StpUtil.getLoginDeviceType(); // 返回当前会话的登录设备类型
StpUtil.getLoginDeviceTypeByToken(token); // 返回指定 token 的登录设备类型
```
@@ -177,18 +183,22 @@ StpUtil.untieDisable(loginId); // 解封：指定账号
``` java
StpUtil.disable(10001, "<业务标识>", 86400); // 封禁：指定账号的指定服务 指定时间(单位s)
StpUtil.isDisable(10001, "<业务标识>"); // 判断：指定账号的指定服务 是否已被封禁 (true=已被封禁, false=未被封禁)
StpUtil.checkDisable(10001, "<业务标识>"); // 校验：指定账号的指定服务 是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`
StpUtil.checkDisable(10001, "<业务标识>"); // 校验：指定账号的指定服务 是否已被封禁，如果被封禁则抛出异常 `DisableServiceException`（支持传入多个业务标识）
StpUtil.getDisableTime(10001, "<业务标识>"); // 获取：指定账号的指定服务 剩余封禁时间，单位：秒（-1=永久封禁，-2=未被封禁）
StpUtil.untieDisable(loginId, "<业务标识>"); // 解封：指定账号的指定服务
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); // 校验：指定账号是否被封禁到指定级别（无业务标识）
```
@@ -215,6 +225,7 @@ StpUtil.closeSafe(); // 在当前会话 结束二级认证
``` java
StpUtil.openSafe("<业务标识>", safeTime); // 在当前会话 指定业务标识开启二级认证
StpUtil.isSafe("<业务标识>"); // 当前会话 指定业务标识是否处于二级认证时间内
StpUtil.isSafe(tokenValue, "<业务标识>"); // 判断指定 token 的指定业务是否处于二级认证时间内
StpUtil.checkSafe("<业务标识>"); // 检查当前会话，指定业务标识是否已通过二级认证，如未通过则抛出异常
StpUtil.getSafeTime("<业务标识>"); // 获取当前会话的指定业务标识二级认证剩余有效时间 (单位: 秒, 返回-2代表尚未通过二级认证)
StpUtil.closeSafe("<业务标识>"); // 在当前会话 结束指定业务标识二级认证