From 850af6c131b9edc706246a41f0e9473aec458b0e Mon Sep 17 00:00:00 2001 From: click33 <2393584716@qq.com> Date: Sat, 8 Mar 2025 15:21:40 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E9=87=8D=E6=9E=84=20TokenSign=20->=20S?= =?UTF-8?q?aTerminalInfo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- sa-token-doc/api/sa-session.md | 20 ++++++++++---------- sa-token-doc/api/stp-util.md | 23 ++++++++++++++--------- sa-token-doc/fun/data-structure.md | 20 +++++++++++++++----- sa-token-doc/up/search-session.md | 6 +++--- sa-token-doc/use/config.md | 6 +++--- 5 files changed, 45 insertions(+), 30 deletions(-) diff --git a/sa-token-doc/api/sa-session.md b/sa-token-doc/api/sa-session.md index ebc9d6ac..91579cbf 100644 --- a/sa-token-doc/api/sa-session.md +++ b/sa-token-doc/api/sa-session.md @@ -21,16 +21,16 @@ session.setCreateTime(createTime); // 写入此 Session 的创建时间（时 ``` -### 3、TokenSign 相关 +### 3、SaTerminalInfo 相关 ``` java -session.setTokenSignList(tokenSignList); // 写入此 Session 绑定的 Token 签名列表 -session.getTokenSignList(); // 获取此 Session 绑定的 Token 签名列表 -session.tokenSignListCopy(); // 获取 Token 签名列表 的拷贝副本 -session.tokenSignListCopyByDevice(device); // 返回 Token 签名列表 的拷贝副本，根据 device 筛选 -session.getTokenSign(tokenValue); // 查找一个 Token 签名 -session.addTokenSign(tokenSign); // 添加一个 Token 签名 -session.addTokenSign(tokenValue, device); // 添加一个 Token 签名 -session.removeTokenSign(tokenValue); // 移除一个 Token 签名 +session.setTerminalList(terminalList); // 写入登录终端信息列表 +session.getTerminalList(); // 获取登录终端信息列表 +session.terminalListCopy(); // 获取 登录终端信息列表 (拷贝副本) +session.getTerminalListByDeviceType(deviceType); // 获取 登录终端信息列表 (拷贝副本)，根据 deviceType 筛选 +session.getTerminal(tokenValue); // 查找一个终端信息，根据 tokenValue +session.addTerminal(terminal); // 添加一个终端信息 +session.removeTerminal(tokenValue); // 移除一个终端信息 +session.maxTerminalIndex(); // 获取最大的终端索引值，如无返0 ``` @@ -38,7 +38,7 @@ session.removeTokenSign(tokenValue); // 移除一个 Token 签名 ``` java session.update(); // 更新Session（从持久库更新刷新一下） session.logout(); // 注销Session (从持久库删除) -session.logoutByTokenSignCountToZero(); // 当Session上的tokenSign数量为零时，注销会话 +session.logoutByTerminalCountToZero(); // 当 Session 上的 SaTerminalInfo 数量为零时，注销会话 session.getTimeout(); // 获取此Session的剩余存活时间 (单位: 秒) session.updateTimeout(timeout); // 修改此Session的剩余存活时间 session.updateMinTimeout(minTimeout); // 修改此Session的最小剩余存活时间 (只有在 Session 的过期时间低于指定的 minTimeout 时才会进行修改) diff --git a/sa-token-doc/api/stp-util.md b/sa-token-doc/api/stp-util.md index e5dc6a4c..457abf86 100644 --- a/sa-token-doc/api/stp-util.md +++ b/sa-token-doc/api/stp-util.md @@ -32,15 +32,20 @@ SaLoginParameter 配置示例： ``` java // SaLoginParameter 配置登录相关参数 StpUtil.login(10001, new SaLoginParameter() - .setDevice("PC") // 此次登录的客户端设备类型, 用于[同端互斥登录]时指定此次登录的设备类型 - .setIsLastingCookie(true) // 是否为持久Cookie（临时Cookie在浏览器关闭时会自动删除，持久Cookie在重新打开后依然存在） - .setTimeout(60 * 60 * 24 * 7) // 指定此次登录token的有效期, 单位:秒 （如未指定，自动取全局配置的 timeout 值） - .setToken("xxxx-xxxx-xxxx-xxxx") // 预定此次登录生成的Token - .setExtra("name", "zhangsan") // Token挂载的扩展参数 （此方法只有在集成jwt插件时才会生效） - .setIsWriteHeader(false) // 是否在登录后将 Token 写入到响应头 - .setActiveTimeout(300) // 指定此次登录token的最低活跃频率, 单位:秒，设置此参数需要在配置文件打开dynamicActiveTimeout=true - .setTokenSignTag("xxx") // 指定此次登录挂载在 TokenSign 上的 tag 值, 任意值 - ); + .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(true) // 在多人登录同一账号时，是否共用一个 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 的自定义扩展数据 +); ``` diff --git a/sa-token-doc/fun/data-structure.md b/sa-token-doc/fun/data-structure.md index bdaa1029..72f6a694 100644 --- a/sa-token-doc/fun/data-structure.md +++ b/sa-token-doc/fun/data-structure.md @@ -110,14 +110,24 @@ value 格式 "name": "张三" // 此 session 挂载数据 详情 // 更多值 ... }, - "tokenSignList": [ // 客户端 token 信息列表（Account-Session才会有值） + "terminalList": [ // 已登录终端信息列表（Account-Session才会有值） "java.util.Vector", [ { - "@class": "cn.dev33.satoken.session.TokenSign", - "value": "06d1f12b-614e-4c00-8d8e-c07fef5f4aa9", // 客户端 token 值 - "device": "default-device", // 登录设备 - "tag": null // 挂载自定义值 + "@class": "cn.dev33.satoken.session.SaTerminalInfo", + "index": 1, + "tokenValue": "2551663f-bb98-47d7-9af3-e2e6a28dadce", // 客户端 token 值 + "deviceType": "default-device", // 登录设备类型 + "deviceId": "xxxxxxxxx", // 登录设备id + "extraData": { + // 扩展信息列表 （手动自定义值） + "@class": "java.util.LinkedHashMap", + "deviceSimpleTitle": "XiaoMi 15 Ultra", + "loginAddress": "浙江省杭州市西湖区", + "loginIp": "127.0.0.1", + "loginTime": "2025-03-08 15:00:02" + }, + "createTime": 1741406340845 // 登录时间 } ] ] diff --git a/sa-token-doc/up/search-session.md b/sa-token-doc/up/search-session.md index b47c3ba5..3f10751f 100644 --- a/sa-token-doc/up/search-session.md +++ b/sa-token-doc/up/search-session.md @@ -65,9 +65,9 @@ for (String sessionId : sessionIdList) { // 根据会话id，查询对应的 SaSession 对象，此处一个 SaSession 对象即代表一个登录的账号 SaSession session = StpUtil.getSessionBySessionId(sessionId); - // 查询这个账号都在哪些设备登录了，依据上面的示例，账号A 的 tokenSign 数量是 3，账号B 的 tokenSign 数量是 2 - List tokenSignList = session.getTokenSignList(); - System.out.println("会话id：" + sessionId + "，共在 " + tokenSignList.size() + " 设备登录"); + // 查询这个账号都在哪些设备登录了，依据上面的示例，账号A 的 SaTerminalInfo 数量是 3，账号B 的 SaTerminalInfo 数量是 2 + List terminalList = session.terminalListCopy(); + System.out.println("会话id：" + sessionId + "，共在 " + terminalList.size() + " 设备登录"); } ``` diff --git a/sa-token-doc/use/config.md b/sa-token-doc/use/config.md index 0833a458..9e0ce28a 100644 --- a/sa-token-doc/use/config.md +++ b/sa-token-doc/use/config.md @@ -410,10 +410,10 @@ sa-token.oauth2-server.oidc.idTokenTimeout=600 配置含义：同一账号最大登录数量。 在配置 `isConcurrent=true`, `isShare=false` 时，Sa-Token 将允许同一账号并发登录，且每次登录都会产生一个新Token， -这些 Token 都会以 `TokenSign` 的形式记录在其 `Account-Session` 之上，这就造成一个问题： +这些 Token 都会以 `SaTerminalInfo` 的形式记录在其 `Account-Session` 之上，这就造成一个问题： -随着同一账号登录的次数越来越多，TokenSign 的列表也会越来越大，极端情况下，列表长度可能达到成百上千以上，严重拖慢数据处理速度， -为此 Sa-Token 对这个 TokenSign 列表的大小设定一个上限值，也就是 `maxLoginCount`，默认值=12。 +随着同一账号登录的次数越来越多，SaTerminalInfo 的列表也会越来越大，极端情况下，列表长度可能达到成百上千以上，严重拖慢数据处理速度， +为此 Sa-Token 对这个 SaTerminalInfo 列表的大小设定一个上限值，也就是 `maxLoginCount`，默认值=12。 假设一个账号的登录数量超过 `maxLoginCount` 后，将会主动注销第一个登录的会话（先进先出），以此保证队列中的有效会话数量始终 `<= maxLoginCount` 值。