From cd66564ffd15c004078c7b9cec13b538864c71e4 Mon Sep 17 00:00:00 2001
From: yangfeng <1790182087@qq.com>
Date: Thu, 22 Jan 2026 09:14:17 +0800
Subject: [PATCH] =?UTF-8?q?feat(BooleanUtil):=20=E6=96=B0=E5=A2=9E=20exact?=
 =?UTF-8?q?lyOneTrue=20=E6=96=B9=E6=B3=95=E7=94=A8=E4=BA=8E=E4=BA=92?=
 =?UTF-8?q?=E6=96=A5=E6=9D=A1=E4=BB=B6=E6=A0=A1=E9=AA=8C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .../java/cn/hutool/core/util/BooleanUtil.java | 33 ++++++++++++++++++-
 .../cn/hutool/core/util/BooleanUtilTest.java  | 20 +++++++++++
 2 files changed, 52 insertions(+), 1 deletion(-)

diff --git a/hutool-core/src/main/java/cn/hutool/core/util/BooleanUtil.java b/hutool-core/src/main/java/cn/hutool/core/util/BooleanUtil.java
index a6ac07d94c..f0b32bec8b 100644
--- a/hutool-core/src/main/java/cn/hutool/core/util/BooleanUtil.java
+++ b/hutool-core/src/main/java/cn/hutool/core/util/BooleanUtil.java
@@ -445,6 +445,10 @@ public class BooleanUtil {
 
 	/**
 	 * 对Boolean数组取异或
+	 * 当前实现的语义为：当数组中 true 的数量为奇数时返回 true，数量为偶数时返回 false。
+	 *
+	 * 注意：该方法并不是判断“是否恰好只有一个 true”，
+	 * 不适用于互斥条件校验（例如：多个条件只能有一个成立的场景）。
 	 *
 	 * <pre>
 	 *   BooleanUtil.xor(true, true)   = false
@@ -453,8 +457,10 @@ public class BooleanUtil {
 	 *   BooleanUtil.xor(true, true)   = false
 	 *   BooleanUtil.xor(false, false) = false
 	 *   BooleanUtil.xor(true, false)  = true
+	 *   BooleanUtil.xor(true, true, true)   = true
+	 *   BooleanUtil.xor(true, true, false)  = false
 	 * </pre>
-	 *
+	 * 如需判断“是否恰好只有一个 true”，请使用 {@link #exactlyOneTrue(boolean...)}。
 	 * @param array {@code boolean}数组
 	 * @return 如果异或计算为true返回 {@code true}
 	 */
@@ -471,6 +477,31 @@ public class BooleanUtil {
 		return result;
 	}
 
+	/**
+	 * 判断 boolean 数组中是否 恰好只有一个 元素为 true。
+	 * 常用于互斥条件校验场景，例如：
+	 * 多个角色只能同时存在一个
+	 * 多个条件只能命中一个分支
+	 * 与 {@link #xor(boolean...)} 不同，
+	 * 本方法在出现多个 true 时会直接返回 false。
+	 *
+	 * @param array boolean 数组
+	 * @return 当且仅当数组中恰好只有一个 true 时返回 true
+	 */
+	public static boolean exactlyOneTrue(final boolean... array) {
+		if (ArrayUtil.isEmpty(array)) {
+			throw new IllegalArgumentException("The Array must not be empty");
+		}
+
+		int count = 0;
+		for (boolean b : array) {
+			if (b && ++count > 1) {
+				return false;
+			}
+		}
+		return count == 1;
+	}
+
 	/**
 	 * 对Boolean数组取异或
 	 *
diff --git a/hutool-core/src/test/java/cn/hutool/core/util/BooleanUtilTest.java b/hutool-core/src/test/java/cn/hutool/core/util/BooleanUtilTest.java
index 9310a9a48b..6a260de618 100644
--- a/hutool-core/src/test/java/cn/hutool/core/util/BooleanUtilTest.java
+++ b/hutool-core/src/test/java/cn/hutool/core/util/BooleanUtilTest.java
@@ -106,4 +106,24 @@ public class BooleanUtilTest {
 		Boolean result = BooleanUtil.andOfWrap(boolean1, boolean2);
 		assertFalse(result);
 	}
+	@Test
+	public void testXorSemantics() {
+		// xor 的实际语义：true 的数量为奇数
+		assertTrue(BooleanUtil.xor(true, true, true));
+		assertFalse(BooleanUtil.xor(true, true));
+	}
+
+	@Test
+	public void testExactlyOneTrue() {
+		// 恰好只有一个 true
+		assertTrue(BooleanUtil.exactlyOneTrue(true, false, false));
+
+		// 多个 true，不符合互斥语义
+		assertFalse(BooleanUtil.exactlyOneTrue(true, true, false));
+		assertFalse(BooleanUtil.exactlyOneTrue(true, true, true));
+
+		// 没有 true
+		assertFalse(BooleanUtil.exactlyOneTrue(false, false, false));
+	}
+
 }