refactor!: 优化二元组校验的 API 设计

- 重载 BaseValidator#ruleForPair，允许传入两个 Function，用于分别从目标对象中获取两个属性
- 升级项目版本至 1.0.0-RC2

plusone-validator/pom.xml

@@ -8,7 +8,7 @@
   <parent>
     <groupId>xyz.zhouxy.plusone</groupId>
     <artifactId>plusone-validator-parent</artifactId>
-    <version>1.0.0-SNAPSHOT</version>
+    <version>1.0.0-RC2</version>
   </parent>
 
   <artifactId>plusone-validator</artifactId>
@@ -16,7 +16,7 @@
   <url>http://zhouxy.xyz</url>
 
   <description>
-    Plusone Validator 是一个校验库，用于构建校验规则对对象（尤其是入参）进行校验。API 参考自 .NET 的 FluentValidation。
+    Plusone Validator 是一个校验库，使用 lambda 表达式（包括方法引用）和流式 API 构建校验规则，对对象进行校验。
   </description>
 
   <properties>
@@ -29,7 +29,7 @@
     <dependency>
       <groupId>xyz.zhouxy.plusone</groupId>
       <artifactId>plusone-commons</artifactId>
-      <version>1.1.0-SNAPSHOT</version>
+      <version>1.1.0-RC1</version>
     </dependency>
     <dependency>
       <groupId>org.junit.jupiter</groupId>

plusone-validator/src/main/java/xyz/zhouxy/plusone/validator/BaseComparablePropertyValidator.java

@@ -82,7 +82,7 @@ public abstract class BaseComparablePropertyValidator<
      *
      * @param <X> 自定义异常类型
      * @param range 区间
-     * @param exceptionFunction 根据属性值生成异常的函数
+     * @param exceptionFunction 自定义异常
      * @return 当前校验器实例，用于链式调用
      */
     public final <X extends RuntimeException> TPropertyValidator inRange(

plusone-validator/src/main/java/xyz/zhouxy/plusone/validator/BasePropertyValidator.java

@@ -108,7 +108,7 @@ public abstract class BasePropertyValidator<
      *
      * @param <X> 自定义异常类型
      * @param condition 校验条件
-     * @param exceptionFunction 自定义异常（以当前属性值为参数）
+     * @param exceptionFunction 自定义异常
      * @return 当前校验器实例，用于链式调用
      */
     protected final <X extends RuntimeException> TPropertyValidator withRule(

plusone-validator/src/main/java/xyz/zhouxy/plusone/validator/BaseValidator.java

@@ -19,6 +19,7 @@ package xyz.zhouxy.plusone.validator;
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.List;
+import java.util.AbstractMap.SimpleImmutableEntry;
 import java.util.Map.Entry;
 import java.util.function.Consumer;
 import java.util.function.Function;
@@ -280,13 +281,34 @@ public abstract class BaseValidator<T> implements IValidator<T> {
      * @param <V2> 第二个元素的类型
      * @param getter 根据对象构造一个二元组，通常是两个属性的值。
      * @return {@code PairPropertyValidator}。用于添加针对该二元组的校验规则。
+     *
+     * @deprecated 请使用 {@link #ruleFor(Function, Function)} 代替。
      */
-    protected final <V1, V2> PairPropertyValidator<T, V1, V2> ruleForPair(Function<T, Entry<V1, V2>> getter) {
+    @Deprecated
+    protected final <V1, V2> PairPropertyValidator<T, V1, V2> ruleForPair( // NOSONAR
+            Function<T, Entry<V1, V2>> getter) {
         PairPropertyValidator<T, V1, V2> validator = new PairPropertyValidator<>(getter);
         this.rules.add(validator::validate);
         return validator;
     }
 
+    /**
+     * 添加一个针对二元组的校验器
+     *
+     * @param <V1> 第1个元素的类型
+     * @param <V2> 第2个元素的类型
+     * @param v1Getter 用于从目标对象获取第1个元素的函数式接口。示例：{@code Person::getName1}。
+     * @param v2Getter 用于从目标对象获取第2个元素的函数式接口。示例：{@code Person::getName2}。
+     * @return {@code PairPropertyValidator}。用于添加针对该二元组的校验规则。
+     */
+    protected final <V1, V2> PairPropertyValidator<T, V1, V2> ruleFor(
+            Function<T, V1> v1Getter, Function<T, V2> v2Getter) {
+        PairPropertyValidator<T, V1, V2> validator = new PairPropertyValidator<>(
+                t -> new SimpleImmutableEntry<>(v1Getter.apply(t), v2Getter.apply(t)));
+        this.rules.add(validator::validate);
+        return validator;
+    }
+
     /** {@inheritDoc} */
     @Override
     public void validate(T obj) {

plusone-validator/src/main/java/xyz/zhouxy/plusone/validator/ComparablePropertyValidator.java

@@ -23,7 +23,6 @@ import java.util.function.Function;
  *
  * @param <T> 待校验对象的类型
  * @param <TProperty> 待校验属性的类型，必须实现 {@code Comparable} 接口
- * @param <TPropertyValidator> 具体校验器类型，用于支持链式调用
  * @see com.google.common.collect.Range
  * @author ZhouXY
  */

plusone-validator/src/main/java/xyz/zhouxy/plusone/validator/MapValidator.java

@@ -16,11 +16,9 @@
 
 package xyz.zhouxy.plusone.validator;
 
-import java.util.AbstractMap.SimpleImmutableEntry;
 import java.util.Arrays;
 import java.util.Collection;
 import java.util.Map;
-import java.util.Map.Entry;
 import java.util.Set;
 import java.util.function.Function;
 import java.util.stream.Collectors;
@@ -196,18 +194,19 @@ public abstract class MapValidator<K, V> extends BaseValidator<Map<K, V>> {
 
     /**
      * 添加一个属性校验器，对指定的两个 key 对应的 value 进行校验
-     * @param <V1> 第一个属性的类型
-     * @param <V2> 第二个属性的类型
-     * @param k1 第一个 key
-     * @param k2 第二个 key
+     * @param <V1> 第1个属性的类型
+     * @param <V2> 第2个属性的类型
+     * @param k1 第1个 key
+     * @param k2 第2个 key
      * @return 属性校验器
      */
     protected final <V1 extends V, V2 extends V>
     PairPropertyValidator<Map<K, V>, V1, V2> ruleForPair(K k1, K k2) {
         @SuppressWarnings("unchecked")
-        Function<Map<K, V>, Entry<V1, V2>> getter = m ->
-                new SimpleImmutableEntry<>((V1) m.get(k1), (V2) m.get(k2));
-        return ruleForPair(getter);
+        final Function<Map<K, V>, V1> v1Getter = m -> (V1) m.get(k1);
+        @SuppressWarnings("unchecked")
+        final Function<Map<K, V>, V2> v2Getter = m -> (V2) m.get(k2);
+        return ruleFor(v1Getter, v2Getter);
     }
 
     // ================================

plusone-validator/src/test/java/xyz/zhouxy/plusone/example/validator/PairPropertyValidatorTests.java

@@ -31,6 +31,7 @@ import xyz.zhouxy.plusone.validator.BaseValidator;
 import xyz.zhouxy.plusone.validator.IValidator;
 import xyz.zhouxy.plusone.validator.ValidationException;
 
+@SuppressWarnings("deprecation")
 public class PairPropertyValidatorTests {
 
     static final String MESSAGE = "Validation failed.";
@@ -41,7 +42,9 @@ public class PairPropertyValidatorTests {
 
     @Test
     void must_validInput() {
-        IValidator<ExampleCommand> validator = new BaseValidator<ExampleCommand>() {
+        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "100");
+
+        IValidator<ExampleCommand> validator1 = new BaseValidator<ExampleCommand>() {
             {
                 ruleForPair((ExampleCommand command) -> new SimpleImmutableEntry<String,Integer>(command.getStringProperty(), command.getIntProperty()))
                         .must((str, intValue) -> Objects.equals(str, intValue.toString()))
@@ -51,69 +54,113 @@ public class PairPropertyValidatorTests {
                                 (str, intValue) -> ExampleException.withMessage("Validation failed: ('%s', %d).", str, intValue));
             }
         };
+        assertDoesNotThrow(() -> validator1.validate(command));
 
-        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "100");
-        assertDoesNotThrow(() -> validator.validate(command));
+        IValidator<ExampleCommand> validator2 = new BaseValidator<ExampleCommand>() {
+            {
+                ruleFor(ExampleCommand::getStringProperty, ExampleCommand::getIntProperty)
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()))
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()), MESSAGE)
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()), () -> ExampleException.withMessage(MESSAGE))
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()),
+                                (str, intValue) -> ExampleException.withMessage("Validation failed: ('%s', %d).", str, intValue));
+            }
+        };
+        assertDoesNotThrow(() -> validator2.validate(command));
     }
 
     @Test
     void must_default_invalidInput() {
-        IValidator<ExampleCommand> validator = new BaseValidator<ExampleCommand>() {
+        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
+
+        IValidator<ExampleCommand> validator1 = new BaseValidator<ExampleCommand>() {
             {
                 ruleForPair((ExampleCommand command) -> new SimpleImmutableEntry<String,Integer>(command.getStringProperty(), command.getIntProperty()))
                         .must((str, intValue) -> Objects.equals(str, intValue.toString()));
             }
         };
+        ValidationException e1 = assertThrows(ValidationException.class, () -> validator1.validate(command));
+        assertEquals("The specified condition was not met for the input.", e1.getMessage());
 
-        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
-
-        ValidationException e = assertThrows(ValidationException.class, () -> validator.validate(command));
-        assertEquals("The specified condition was not met for the input.", e.getMessage());
+        IValidator<ExampleCommand> validator2 = new BaseValidator<ExampleCommand>() {
+            {
+                ruleFor(ExampleCommand::getStringProperty, ExampleCommand::getIntProperty)
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()));
+            }
+        };
+        ValidationException e2 = assertThrows(ValidationException.class, () -> validator2.validate(command));
+        assertEquals("The specified condition was not met for the input.", e2.getMessage());
     }
 
     @Test
     void must_message_invalidInput() {
-        IValidator<ExampleCommand> validator = new BaseValidator<ExampleCommand>() {
+        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
+
+        IValidator<ExampleCommand> validator1 = new BaseValidator<ExampleCommand>() {
             {
                 ruleForPair((ExampleCommand command) -> new SimpleImmutableEntry<String,Integer>(command.getStringProperty(), command.getIntProperty()))
                         .must((str, intValue) -> Objects.equals(str, intValue.toString()), MESSAGE);
             }
         };
+        ValidationException e1 = assertThrows(ValidationException.class, () -> validator1.validate(command));
+        assertEquals(MESSAGE, e1.getMessage());
 
-        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
-        ValidationException e = assertThrows(ValidationException.class, () -> validator.validate(command));
-        assertEquals(MESSAGE, e.getMessage());
+        IValidator<ExampleCommand> validator2 = new BaseValidator<ExampleCommand>() {
+            {
+                ruleFor(ExampleCommand::getStringProperty, ExampleCommand::getIntProperty)
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()), MESSAGE);
+            }
+        };
+        ValidationException e2 = assertThrows(ValidationException.class, () -> validator2.validate(command));
+        assertEquals(MESSAGE, e2.getMessage());
     }
 
     @Test
     void must_exceptionSupplier_invalidInput() {
-        IValidator<ExampleCommand> validator = new BaseValidator<ExampleCommand>() {
+        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
+
+        IValidator<ExampleCommand> validator1 = new BaseValidator<ExampleCommand>() {
             {
                 ruleForPair((ExampleCommand command) -> new SimpleImmutableEntry<String,Integer>(command.getStringProperty(), command.getIntProperty()))
                         .must((str, intValue) -> Objects.equals(str, intValue.toString()), () -> ExampleException.withMessage(MESSAGE));
             }
         };
+        ExampleException e1 = assertThrows(ExampleException.class, () -> validator1.validate(command));
+        assertEquals(MESSAGE, e1.getMessage());
 
-        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
-
-        ExampleException e = assertThrows(ExampleException.class, () -> validator.validate(command));
-        assertEquals(MESSAGE, e.getMessage());
+        IValidator<ExampleCommand> validator2 = new BaseValidator<ExampleCommand>() {
+            {
+                ruleFor(ExampleCommand::getStringProperty, ExampleCommand::getIntProperty)
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()), () -> ExampleException.withMessage(MESSAGE));
+            }
+        };
+        ExampleException e2 = assertThrows(ExampleException.class, () -> validator2.validate(command));
+        assertEquals(MESSAGE, e2.getMessage());
     }
 
     @Test
     void must_exceptionFunction_invalidInput() {
-        IValidator<ExampleCommand> validator = new BaseValidator<ExampleCommand>() {
+        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
+
+        IValidator<ExampleCommand> validator1 = new BaseValidator<ExampleCommand>() {
             {
                 ruleForPair((ExampleCommand command) -> new SimpleImmutableEntry<String,Integer>(command.getStringProperty(), command.getIntProperty()))
                         .must((str, intValue) -> Objects.equals(str, intValue.toString()),
                                 (str, intValue) -> ExampleException.withMessage("Validation failed: ('%s', %d).", str, intValue));
             }
         };
+        ExampleException e1 = assertThrows(ExampleException.class, () -> validator1.validate(command));
+        assertEquals("Validation failed: ('', 100).", e1.getMessage());
 
-        ExampleCommand command = exampleCommandWithIntAndStringListProperty(100, "");
-
-        ExampleException e = assertThrows(ExampleException.class, () -> validator.validate(command));
-        assertEquals("Validation failed: ('', 100).", e.getMessage());
+        IValidator<ExampleCommand> validator2 = new BaseValidator<ExampleCommand>() {
+            {
+                ruleFor(ExampleCommand::getStringProperty, ExampleCommand::getIntProperty)
+                        .must((str, intValue) -> Objects.equals(str, intValue.toString()),
+                                (str, intValue) -> ExampleException.withMessage("Validation failed: ('%s', %d).", str, intValue));
+            }
+        };
+        ExampleException e2 = assertThrows(ExampleException.class, () -> validator2.validate(command));
+        assertEquals("Validation failed: ('', 100).", e2.getMessage());
     }
 
     // ================================

plusone-validator/src/test/java/xyz/zhouxy/plusone/map/validator/MapValidatorTests.java

@@ -19,6 +19,7 @@ package xyz.zhouxy.plusone.map.validator;
 import static org.junit.jupiter.api.Assertions.*;
 
 import java.time.LocalDateTime;
+import java.util.Arrays;
 import java.util.Collections;
 import java.util.HashMap;
 import java.util.Map;
@@ -58,7 +59,7 @@ class MapValidatorTests {
         params.put(ParamsValidator.STRING_PROPERTY2, "Foo");
         assertAll(() -> {
             Map<String, Object> validatedParams = validator.validateAndCopy(params);
-            assertEquals(ParamsValidator.keySet(), validatedParams.keySet());
+            assertEquals(ImmutableSet.copyOf(ParamsValidator.reservedProperties()), validatedParams.keySet());
 
             assertEquals(true, validatedParams.get(ParamsValidator.BOOL_PROPERTY));
             assertEquals(Integer.MAX_VALUE, validatedParams.get(ParamsValidator.INT_PROPERTY));
@@ -103,11 +104,14 @@ class ParamsValidator extends MapValidator<String, Object> {
     public static final String OBJECT_PROPERTY = "objectProperty";
     public static final String STRING_LIST_PROPERTY = "stringListProperty";
 
+    private static final String[] RESERVED_PROPERTIES = {
+            BOOL_PROPERTY, INT_PROPERTY, LONG_PROPERTY, DOUBLE_PROPERTY, STRING_PROPERTY,
+            DATE_TIME_PROPERTY, OBJECT_PROPERTY, STRING_LIST_PROPERTY };
+
     public static final ParamsValidator INSTANCE = new ParamsValidator();
 
     private ParamsValidator() {
-        super(new String[] { BOOL_PROPERTY, INT_PROPERTY, LONG_PROPERTY, DOUBLE_PROPERTY, STRING_PROPERTY,
-                DATE_TIME_PROPERTY, OBJECT_PROPERTY, STRING_LIST_PROPERTY });
+        super(RESERVED_PROPERTIES);
         ruleForBool(BOOL_PROPERTY)
                 .notNull();
         ruleForInt(INT_PROPERTY)
@@ -130,8 +134,7 @@ class ParamsValidator extends MapValidator<String, Object> {
                         "'stringProperty' must be equal to 'stringProperty2'.");
     }
 
-    public static Set<String> keySet() {
-        return ImmutableSet.of(BOOL_PROPERTY, INT_PROPERTY, LONG_PROPERTY, DOUBLE_PROPERTY, STRING_PROPERTY,
-                DATE_TIME_PROPERTY, OBJECT_PROPERTY, STRING_LIST_PROPERTY);
+    public static String[] reservedProperties() {
+        return Arrays.copyOf(RESERVED_PROPERTIES, RESERVED_PROPERTIES.length);
     }
 }

pom.xml

@@ -6,7 +6,7 @@
 
   <groupId>xyz.zhouxy.plusone</groupId>
   <artifactId>plusone-validator-parent</artifactId>
-  <version>1.0.0-SNAPSHOT</version>
+  <version>1.0.0-RC2</version>
 
   <name>plusone-validator-parent</name>
   <url>http://zhouxy.xyz</url>
@@ -18,7 +18,7 @@
   </modules>
 
   <description>
-    Plusone Validator 是一个校验库，用于构建校验规则对对象（尤其是入参）进行校验。API 参考自 .NET 的 FluentValidation。
+    Plusone Validator 是一个校验库，使用 lambda 表达式（包括方法引用）和流式 API 构建校验规则，对对象进行校验。
   </description>
 
   <properties>
@@ -30,7 +30,7 @@
       <dependency>
         <groupId>xyz.zhouxy.plusone</groupId>
         <artifactId>plusone-dependencies</artifactId>
-        <version>1.1.0-SNAPSHOT</version>
+        <version>1.1.0-RC1</version>
         <type>pom</type>
         <scope>import</scope>
       </dependency>