[fit] Implement parameter validation plugins that supports both javax and Jakarta standards

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-jakarta/src/main/java/modelengine/fitframework/validation/LocaleMessageInterpolator.java

@@ -26,24 +26,43 @@ public class LocaleMessageInterpolator implements MessageInterpolator {
 
     private Locale locale;
 
+    /**
+     * 构造函数，使用指定的目标消息插值器初始化实例。
+     *
+     * @param target 目标消息插值器 {@link MessageInterpolator}。
+     */
     public LocaleMessageInterpolator(MessageInterpolator target) {
         this.target = target;
         this.locale = Locale.getDefault();
     }
 
+    /**
+     * 构造函数，使用指定的地区初始化实例。
+     *
+     * @param locale 指定的地区 {@link Locale}。
+     */
     public LocaleMessageInterpolator(Locale locale) {
         this.locale = locale;
         this.target = new ParameterMessageInterpolator();
     }
 
+    /**
+     * 构造函数，使用指定的目标消息插值器和地区初始化实例。
+     *
+     * @param target 被代理的目标消息插值器 {@link MessageInterpolator}。
+     * @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
+     */
     public LocaleMessageInterpolator(MessageInterpolator target, Locale locale) {
         this.target = target;
         this.locale = locale;
     }
 
+    /**
+     * 构造函数，使用默认地区初始化实例。
+     */
     public LocaleMessageInterpolator() {
-        locale = Locale.getDefault();
-        target = new ParameterMessageInterpolator();
+        this.locale = Locale.getDefault();
+        this.target = new ParameterMessageInterpolator();
     }
 
     @Override
@@ -56,6 +75,11 @@ public String interpolate(String messageTemplate, Context context, Locale locale
         return target.interpolate(messageTemplate, context, this.locale);
     }
 
+    /**
+     * 设置地区。
+     *
+     * @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
+     */
     public void setLocale(Locale locale) {
         this.locale = locale;
     }

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-jakarta/src/main/java/modelengine/fitframework/validation/ValidationHandler.java

@@ -94,7 +94,7 @@ public void close() {
     /**
      * 检查方法参数是否包含 {@code jakarta.validation} 校验注解。
      *
-     * @param parameters 方法参数数组 {@link Parameter}{@code []}。
+     * @param parameters 表示可能携带校验注解的方法参数数组 {@link Parameter}{@code []}。
      * @return 如果包含 {@code jakarta.validation} 标注的校验注解则返回 {@code true}，否则返回 {@code false}。
      */
     private boolean hasJakartaConstraintAnnotations(Parameter[] parameters) {
@@ -104,17 +104,17 @@ private boolean hasJakartaConstraintAnnotations(Parameter[] parameters) {
     /**
      * 检查参数及其泛型类型参数是否包含校验注解。
      *
-     * @param parameter 方法参数 {@link Parameter}。
+     * @param parameter 表示可能携带校验注解的方法参数 {@link Parameter}。
      * @return 如果包含 {@code jakarta.validation} 标注的校验注解则返回 {@code true}，否则返回 {@code false}。
      */
     private boolean hasConstraintAnnotationsInParameter(Parameter parameter) {
         return hasConstraintAnnotationsInType(parameter.getAnnotatedType());
     }
 
     /**
-     * 判断参数注解类型，解析参数本身注解及其泛型类型参数注解。
+     * 判断参数类型，解析参数本身注解或其泛型类型参数注解。
      *
-     * @param annotatedType 参数注解类型 {@link AnnotatedType}。
+     * @param annotatedType 表示待检查的参数类型 {@link AnnotatedType}。
      * @return 如果包含 {@code jakarta.validation} 标注的校验注解则返回 {@code true}，否则返回 {@code false}。
      */
     private boolean hasConstraintAnnotationsInType(AnnotatedType annotatedType) {
@@ -135,13 +135,19 @@ private boolean hasConstraintAnnotationsInType(AnnotatedType annotatedType) {
 
     /**
      * <p>
-     * 检查注解是否属于 {@code jakarta.validation} 注解。
+     *     检查注解是否属于 {@code jakarta.validation} 注解。
+     * </p>
      * <p>
-     * 由于存在嵌套校验的情况， {@code @Valid} 与其他校验注解都可以标注参数需要进行校验，但两者的实现与语义上存在差异，处理逻辑不能合并，因此分情况讨论：
+     *     由于存在嵌套校验的情况，{@code @Valid} 与其他校验注解都可以标注参数需要进行校验，但两者的实现与语义上存在差异，处理逻辑不能合并，因此分情况讨论：
+     * </p>
      * <ol>
-     * <li>{@code @Valid} 注解检查。用于标记需要级联校验的对象，例如： {@code void validateCompany(@Valid Company company)}。</li>
-     * <li>其他携带 {@code @Constraint} 元注解的校验注解检查。例如： {@code void validateEmployee(@NotBlank String name, @Positive int
-     * age)}。</li>
+     *     <li>
+     *         {@code @Valid} 注解检查。用于标记需要级联校验的对象，例如：{@code void validateCompany(@Valid Company company)}。
+     *     </li>
+     *     <li>
+     *         其他携带 {@code @Constraint} 元注解的校验注解检查。例如：{@code void validateEmployee(@NotBlank String name, @Positive
+     *         int)}。
+     *     </li>
      * </ol>
      *
      * @param annotation 要检查的注解 {@link java.lang.annotation.Annotation}

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-jakarta/src/test/java/modelengine/fitframework/validation/data/Company.java

@@ -23,8 +23,16 @@ public class Company {
     @Valid
     private List<Employee> employees;
 
+    /**
+     * 默认构造函数。
+     */
     public Company() {}
 
+    /**
+     * 构造函数。
+     *
+     * @param employees 表示雇员列表的 {@link List}{@code <}{@link Employee}{@code >}。
+     */
     public Company(List<Employee> employees) {
         this.employees = employees;
     }

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-jakarta/src/test/java/modelengine/fitframework/validation/data/Employee.java

@@ -23,8 +23,17 @@ public class Employee {
     @Min(value = 18, message = "年龄必须大于等于18")
     private int age;
 
+    /**
+     * 默认构造函数。
+     */
     public Employee() {}
 
+    /**
+     * 构造函数。
+     *
+     * @param name 姓名 {@link String}。
+     * @param age 年龄 {@code int}
+     */
     public Employee(String name, int age) {
         this.name = name;
         this.age = age;

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-jakarta/src/test/java/modelengine/fitframework/validation/data/GroupValidateService.java

@@ -23,10 +23,14 @@
 public class GroupValidateService {
     private static final Logger LOG = Logger.get(GroupValidateService.class);
 
-    // 学生年龄验证服务。
     @Component
     @Validated(ValidationTestData.StudentGroup.class)
     public static class StudentValidateService {
+        /**
+         * 验证学生年龄。
+         *
+         * @param age 年龄 {@code int}
+         */
         public void validateStudentAge(
                 @Min(value = 7, message = "范围要在7~20之内", groups = ValidationTestData.StudentGroup.class) @Max(
                         value = 20, message = "范围要在7~20之内",
@@ -35,10 +39,14 @@ public void validateStudentAge(
         }
     }
 
-    // 教师年龄验证服务。
     @Component
     @Validated(ValidationTestData.TeacherGroup.class)
     public static class TeacherValidateService {
+        /**
+         * 验证教师年龄。
+         *
+         * @param age 年龄 {@code int}
+         */
         public void validateTeacherAge(
                 @Min(value = 22, message = "范围要在22~65之内", groups = ValidationTestData.TeacherGroup.class) @Max(
                         value = 65, message = "范围要在22~65之内",
@@ -51,8 +59,13 @@ public void validateTeacherAge(
     @Component
     @Validated(ValidationTestData.AdvancedGroup.class)
     public static class AdvancedValidateService {
+        /**
+         * 验证高级分组数据。
+         *
+         * @param data 用于测试复杂对象验证的数据 {@link ValidationTestData}
+         */
         public void validateAdvancedGroup(@Valid ValidationTestData data) {
             LOG.debug("Validating advanced group data: {}", data);
         }
     }
-}
+}

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-jakarta/src/test/java/modelengine/fitframework/validation/data/ValidateService.java

@@ -126,7 +126,7 @@ public void testSize(@Size(min = 2, max = 10) String value) {}
     /**
      * 测试 List 的 Size 约束注解。
      *
-     * @param value 表示输入的 {@code List<String>}。
+     * @param value 表示输入的 {@link List}{@code <}{@link String}{@code >}。
      */
     public void testSizeList(@Size(min = 1, max = 3) List<String> value) {}
 
@@ -343,7 +343,7 @@ public void validateCompany(@Valid Company company) {
     /**
      * 验证员工列表。
      *
-     * @param employees 表示输入的 {@link List<Employee>}。
+     * @param employees 表示输入的 {@link List}{@code <}{@link Employee}{@code >}。
      */
     public void validateEmployeeList(List<@Valid Employee> employees) {
         LOG.debug("Validating employee list: {}", employees);
@@ -352,7 +352,7 @@ public void validateEmployeeList(List<@Valid Employee> employees) {
     /**
      * 验证嵌套员工列表。
      *
-     * @param nestedList 表示输入的 {@link List<List<Employee>>}。
+     * @param nestedList 表示输入的 {@link List}{@code <}{@link List}{@code <}{@link Employee}{@code >}{@code >}}。
      */
     public void validateNestedEmployeeList(List<List<@Valid Employee>> nestedList) {
         LOG.debug("Validating nested employee list: {}", nestedList);
@@ -361,7 +361,7 @@ public void validateNestedEmployeeList(List<List<@Valid Employee>> nestedList) {
     /**
      * 验证员工映射。
      *
-     * @param employeeMap 表示输入的 {@code Map<String, Employee>}。
+     * @param employeeMap 表示输入的 {@link  Map}{@code <}{@link String}{@code , }{@link Employee}{@code >}。
      */
     public void validateEmployeeMap(@Valid Map<String, Employee> employeeMap) {
         LOG.debug("Validating employee map: {}", employeeMap);
@@ -370,7 +370,7 @@ public void validateEmployeeMap(@Valid Map<String, Employee> employeeMap) {
     /**
      * 验证员工数据映射。
      *
-     * @param map 表示输入的 {@code Map<Employee, ValidationTestData>}。
+     * @param map 表示输入的 {@link Map}{@code <}{@link Employee}{@code , }{@link ValidationTestData}>。
      */
     public void validateEmployeeDataMap(@Valid Map<Employee, ValidationTestData> map) {
         LOG.debug("Validating employee data map: {}", map);
@@ -379,7 +379,9 @@ public void validateEmployeeDataMap(@Valid Map<Employee, ValidationTestData> map
     /**
      * 验证嵌套员工数据映射。
      *
-     * @param nestedMap 表示输入的 {@code Map<Employee, Map<String, ValidationTestData>>}。
+     * @param nestedMap 表示输入的
+     * {@link Map}{@code <}{@link Employee}{@code , }{@link Map}{@code <}{@link String}{@code , }{@link
+     * ValidationTestData}{@code >}{@code >}。
      */
     public void validateNestedEmployeeDataMap(Map<@Valid Employee, Map<String, @Valid ValidationTestData>> nestedMap) {
         LOG.debug("Validating nested employee data map: {}", nestedMap);
@@ -388,7 +390,8 @@ public void validateNestedEmployeeDataMap(Map<@Valid Employee, Map<String, @Vali
     /**
      * 验证员工映射列表。
      *
-     * @param listOfMaps 表示输入的 {@code List<Map<String, Employee>>}。
+     * @param listOfMaps 表示输入的 {@link List}{@code <}{@link Map}{@code <}{@link String}{@code ,
+     * }{@link Employee}{@code >}{@code >}。
      */
     public void validateEmployeeMapList(List<Map<String, @Valid Employee>> listOfMaps) {
         LOG.debug("Validating employee map list: {}", listOfMaps);
@@ -397,7 +400,7 @@ public void validateEmployeeMapList(List<Map<String, @Valid Employee>> listOfMap
     /**
      * 验证员工数据列表映射。
      *
-     * @param map 表示输入的 {@code Map<Employee, List<ValidationTestData>>}。
+     * @param map 表示输入的 {@link Map}{@code <}{@link Employee}{@code , }{@link List}{@code <}{@link ValidationTestData}{@code >}{}。
      */
     public void validateEmployeeDataListMap(Map<@Valid Employee, List<@Valid ValidationTestData>> map) {
         LOG.debug("Validating employee data list map: {}", map);
@@ -406,7 +409,7 @@ public void validateEmployeeDataListMap(Map<@Valid Employee, List<@Valid Validat
     /**
      * 验证公司列表。
      *
-     * @param companies 表示输入的 {@code List<Company>}。
+     * @param companies 表示输入的 {@link List}{@code <}{@link Company}{@code >}。
      */
     public void validateCompanyList(@Valid List<Company> companies) {
         LOG.debug("Validating company list: {}", companies);
@@ -425,8 +428,8 @@ public void validateMixed(@Positive int value, @Valid Employee employee) {
     /**
      * 验证混合集合数据。
      *
-     * @param list1 表示输入的 {@code List<String>}。
-     * @param list2 表示输入的 {@code List<String>}。
+     * @param list1 表示输入的 {@link List}{@code <}{@link String}{@code >}。
+     * @param list2 表示输入的 {@link List}{@code <}{@link String}{@code >}。
      */
     public void validateMixedCollections(@NotNull List<String> list1, @NotEmpty List<String> list2) {
         LOG.debug("Validating mixed collections: {} and {}", list1, list2);

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-javax/src/main/java/modelengine/fitframework/validation/LocaleMessageInterpolator.java

@@ -26,24 +26,43 @@ public class LocaleMessageInterpolator implements MessageInterpolator {
 
     private Locale locale;
 
+    /**
+     * 构造函数，使用指定的目标消息插值器初始化实例。
+     *
+     * @param target 目标消息插值器 {@link MessageInterpolator}。
+     */
     public LocaleMessageInterpolator(MessageInterpolator target) {
         this.target = target;
         this.locale = Locale.getDefault();
     }
 
+    /**
+     * 构造函数，使用指定的地区初始化实例。
+     *
+     * @param locale 指定的地区 {@link Locale}。
+     */
     public LocaleMessageInterpolator(Locale locale) {
         this.locale = locale;
         this.target = new ParameterMessageInterpolator();
     }
 
+    /**
+     * 构造函数，使用指定的目标消息插值器和地区初始化实例。
+     *
+     * @param target 被代理的目标消息插值器 {@link MessageInterpolator}。
+     * @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
+     */
     public LocaleMessageInterpolator(MessageInterpolator target, Locale locale) {
         this.target = target;
         this.locale = locale;
     }
 
+    /**
+     * 构造函数，使用默认地区初始化实例。
+     */
     public LocaleMessageInterpolator() {
-        locale = Locale.getDefault();
-        target = new ParameterMessageInterpolator();
+        this.locale = Locale.getDefault();
+        this.target = new ParameterMessageInterpolator();
     }
 
     @Override
@@ -56,6 +75,11 @@ public String interpolate(String messageTemplate, Context context, Locale locale
         return target.interpolate(messageTemplate, context, this.locale);
     }
 
+    /**
+     * 设置地区。
+     *
+     * @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
+     */
     public void setLocale(Locale locale) {
         this.locale = locale;
     }