From 98f4de6514908784f189a3ceed1ca6ccc043ecf3 Mon Sep 17 00:00:00 2001 From: click33 <2393584716@qq.com> Date: Sun, 8 Mar 2026 13:35:30 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=A8=20StpUtil=20API=20?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sa-token-doc/api/stp-util.md | 59 +++++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 24 deletions(-) diff --git a/sa-token-doc/api/stp-util.md b/sa-token-doc/api/stp-util.md index 5f665c6c..d109a65b 100644 --- a/sa-token-doc/api/stp-util.md +++ b/sa-token-doc/api/stp-util.md @@ -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("<业务标识>"); // 在当前会话 结束指定业务标识二级认证