feat: 新增 StpUtil.forEachTerminalList 方法，用于手动遍历一个账号的已登录终端信息列表，执行特定函数

sa-token-core/src/main/java/cn/dev33/satoken/fun/SaTwoParamFunction.java

@@ -0,0 +1,34 @@
+/*
+ * Copyright 2020-2099 sa-token.cc
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package cn.dev33.satoken.fun;
+
+/**
+ * 双形参、无返回值的函数式接口，方便开发者进行 lambda 表达式风格调用
+ *
+ * @author click33
+ * @since 1.41.0
+ */
+@FunctionalInterface
+public interface SaTwoParamFunction<T, T2> {
+	
+	/**
+	 * 执行的方法 
+	 * @param r 传入的参数
+	 * @param r2 传入的参数 2
+	 */
+	void run(T r, T2 r2);
+	
+}

sa-token-core/src/main/java/cn/dev33/satoken/session/SaSession.java

@@ -18,6 +18,7 @@ package cn.dev33.satoken.session;
 import cn.dev33.satoken.SaManager;
 import cn.dev33.satoken.application.SaSetValueInterface;
 import cn.dev33.satoken.dao.SaTokenDao;
+import cn.dev33.satoken.fun.SaTwoParamFunction;
 import cn.dev33.satoken.listener.SaTokenEventCenter;
 import cn.dev33.satoken.util.SaFoxUtil;
 
@@ -371,6 +372,17 @@ public class SaSession implements SaSetValueInterface, Serializable {
 		this.historyTerminalCount = historyTerminalCount;
 	}
 
+	/**
+	 * 遍历 terminalList 列表，执行特定函数
+	 *
+	 * @param function 需要执行的函数
+	 */
+	public void forEachTerminalList(SaTwoParamFunction<SaSession, SaTerminalInfo> function) {
+		for (SaTerminalInfo terminalInfo: terminalListCopy()) {
+			function.run(this, terminalInfo);
+		}
+	}
+
 
 	/**
 	 * 判断指定设备 id 是否为可信任设备

sa-token-core/src/main/java/cn/dev33/satoken/stp/StpUtil.java

@@ -17,6 +17,7 @@ package cn.dev33.satoken.stp;
 
 import cn.dev33.satoken.SaManager;
 import cn.dev33.satoken.fun.SaFunction;
+import cn.dev33.satoken.fun.SaTwoParamFunction;
 import cn.dev33.satoken.listener.SaTokenEventCenter;
 import cn.dev33.satoken.session.SaSession;
 import cn.dev33.satoken.session.SaTerminalInfo;
@@ -990,6 +991,16 @@ public class StpUtil {
 		return stpLogic.getTerminalListByLoginId(loginId, deviceType);
 	}
 
+	/**
+	 * 获取指定账号 id 已登录设备信息集合，执行特定函数
+	 *
+	 * @param loginId 账号id
+	 * @param function 需要执行的函数
+	 */
+	public static void forEachTerminalList(Object loginId, SaTwoParamFunction<SaSession, SaTerminalInfo> function) {
+		stpLogic.forEachTerminalList(loginId, function);
+	}
+
 	/**
 	 * 返回当前会话的登录设备类型
 	 *

sa-token-doc/up/login-parameter.md

@@ -70,3 +70,30 @@ StpUtil.logout(10001, new SaLogoutParameter()
 以上大部分参数在未指定时将使用全局配置作为默认值。
 
 
+### 3、遍历登录终端详细操作
+
+如果你的 登录策略 或 注销策略 非常复杂，凭借上述参数无法组合出你的业务场景，你可以手动遍历一个账号的已登录终端信息列表，手动决定某个设备是否下线，例如：
+
+``` java
+// 测试 
+@RequestMapping("logout")
+public SaResult logout() {
+	
+	// 遍历账号 10001 已登录终端列表，进行详细操作
+	StpUtil.forEachTerminalList(10001, (session, ter) -> {
+		// 根据登录顺序，奇数的保留，偶数的下线
+		if(ter.getIndex() % 2 == 0) {
+			StpUtil.removeTerminalByLogout(session, ter);   // 注销下线方式 移除这个登录客户端
+			// StpUtil.removeTerminalByKickout(session, ter);  // 踢人下线方式 移除这个登录客户端
+			// StpUtil.removeTerminalByReplaced(session, ter);  // 顶人下线方式 移除这个登录客户端
+		}
+	});
+	
+	return SaResult.ok();
+}
+```
+
+
+
+
+