Skip to content

Commit 9c64f7b

Browse files
Yager-42Yager-42
committed
[fit] 完善注释
1 parent df84b28 commit 9c64f7b

File tree

12 files changed

+177
-51
lines changed

12 files changed

+177
-51
lines changed

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

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,24 +26,43 @@ public class LocaleMessageInterpolator implements MessageInterpolator {
2626

2727
private Locale locale;
2828

29+
/**
30+
* 构造函数，使用指定的目标消息插值器初始化实例。
31+
*
32+
* @param target 目标消息插值器 {@link MessageInterpolator}。
33+
*/
2934
public LocaleMessageInterpolator(MessageInterpolator target) {
3035
this.target = target;
3136
this.locale = Locale.getDefault();
3237
}
3338

39+
/**
40+
* 构造函数，使用指定的地区初始化实例。
41+
*
42+
* @param locale 指定的地区 {@link Locale}。
43+
*/
3444
public LocaleMessageInterpolator(Locale locale) {
3545
this.locale = locale;
3646
this.target = new ParameterMessageInterpolator();
3747
}
3848

49+
/**
50+
* 构造函数，使用指定的目标消息插值器和地区初始化实例。
51+
*
52+
* @param target 被代理的目标消息插值器 {@link MessageInterpolator}。
53+
* @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
54+
*/
3955
public LocaleMessageInterpolator(MessageInterpolator target, Locale locale) {
4056
this.target = target;
4157
this.locale = locale;
4258
}
4359

60+
/**
61+
* 构造函数，使用默认地区初始化实例。
62+
*/
4463
public LocaleMessageInterpolator() {
45-
locale = Locale.getDefault();
46-
target = new ParameterMessageInterpolator();
64+
this.locale = Locale.getDefault();
65+
this.target = new ParameterMessageInterpolator();
4766
}
4867

4968
@Override
@@ -56,6 +75,11 @@ public String interpolate(String messageTemplate, Context context, Locale locale
5675
return target.interpolate(messageTemplate, context, this.locale);
5776
}
5877

78+
/**
79+
* 设置地区。
80+
*
81+
* @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
82+
*/
5983
public void setLocale(Locale locale) {
6084
this.locale = locale;
6185
}

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

Lines changed: 15 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -94,7 +94,7 @@ public void close() {
9494
/**
9595
* 检查方法参数是否包含 {@code jakarta.validation} 校验注解。
9696
*
97-
* @param parameters 方法参数数组 {@link Parameter}{@code []}。
97+
* @param parameters 表示可能携带校验注解的方法参数数组 {@link Parameter}{@code []}。
9898
* @return 如果包含 {@code jakarta.validation} 标注的校验注解则返回 {@code true}，否则返回 {@code false}。
9999
*/
100100
private boolean hasJakartaConstraintAnnotations(Parameter[] parameters) {
@@ -104,17 +104,17 @@ private boolean hasJakartaConstraintAnnotations(Parameter[] parameters) {
104104
/**
105105
* 检查参数及其泛型类型参数是否包含校验注解。
106106
*
107-
* @param parameter 方法参数 {@link Parameter}。
107+
* @param parameter 表示可能携带校验注解的方法参数 {@link Parameter}。
108108
* @return 如果包含 {@code jakarta.validation} 标注的校验注解则返回 {@code true}，否则返回 {@code false}。
109109
*/
110110
private boolean hasConstraintAnnotationsInParameter(Parameter parameter) {
111111
return hasConstraintAnnotationsInType(parameter.getAnnotatedType());
112112
}
113113

114114
/**
115-
* 判断参数注解类型，解析参数本身注解及其泛型类型参数注解。
115+
* 判断参数类型，解析参数本身注解或其泛型类型参数注解。
116116
*
117-
* @param annotatedType 参数注解类型 {@link AnnotatedType}。
117+
* @param annotatedType 表示待检查的参数类型 {@link AnnotatedType}。
118118
* @return 如果包含 {@code jakarta.validation} 标注的校验注解则返回 {@code true}，否则返回 {@code false}。
119119
*/
120120
private boolean hasConstraintAnnotationsInType(AnnotatedType annotatedType) {
@@ -135,13 +135,19 @@ private boolean hasConstraintAnnotationsInType(AnnotatedType annotatedType) {
135135

136136
/**
137137
* <p>
138-
* 检查注解是否属于 {@code jakarta.validation} 注解。
138+
* 检查注解是否属于 {@code jakarta.validation} 注解。
139+
* </p>
139140
* <p>
140-
* 由于存在嵌套校验的情况， {@code @Valid} 与其他校验注解都可以标注参数需要进行校验，但两者的实现与语义上存在差异，处理逻辑不能合并，因此分情况讨论：
141+
* 由于存在嵌套校验的情况，{@code @Valid} 与其他校验注解都可以标注参数需要进行校验，但两者的实现与语义上存在差异，处理逻辑不能合并，因此分情况讨论：
142+
* </p>
141143
* <ol>
142-
* <li>{@code @Valid} 注解检查。用于标记需要级联校验的对象，例如： {@code void validateCompany(@Valid Company company)}。</li>
143-
* <li>其他携带 {@code @Constraint} 元注解的校验注解检查。例如： {@code void validateEmployee(@NotBlank String name, @Positive int
144-
* age)}。</li>
144+
* <li>
145+
* {@code @Valid} 注解检查。用于标记需要级联校验的对象，例如：{@code void validateCompany(@Valid Company company)}。
146+
* </li>
147+
* <li>
148+
* 其他携带 {@code @Constraint} 元注解的校验注解检查。例如：{@code void validateEmployee(@NotBlank String name, @Positive
149+
* int)}。
150+
* </li>
145151
* </ol>
146152
*
147153
* @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‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,16 @@ public class Company {
2323
@Valid
2424
private List<Employee> employees;
2525

26+
/**
27+
* 默认构造函数。
28+
*/
2629
public Company() {}
2730

31+
/**
32+
* 构造函数。
33+
*
34+
* @param employees 表示雇员列表的 {@link List}{@code <}{@link Employee}{@code >}。
35+
*/
2836
public Company(List<Employee> employees) {
2937
this.employees = employees;
3038
}

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

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,17 @@ public class Employee {
2323
@Min(value = 18, message = "年龄必须大于等于18")
2424
private int age;
2525

26+
/**
27+
* 默认构造函数。
28+
*/
2629
public Employee() {}
2730

31+
/**
32+
* 构造函数。
33+
*
34+
* @param name 姓名 {@link String}。
35+
* @param age 年龄 {@code int}
36+
*/
2837
public Employee(String name, int age) {
2938
this.name = name;
3039
this.age = age;

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

Lines changed: 16 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,14 @@
2323
public class GroupValidateService {
2424
private static final Logger LOG = Logger.get(GroupValidateService.class);
2525

26-
// 学生年龄验证服务。
2726
@Component
2827
@Validated(ValidationTestData.StudentGroup.class)
2928
public static class StudentValidateService {
29+
/**
30+
* 验证学生年龄。
31+
*
32+
* @param age 年龄 {@code int}
33+
*/
3034
public void validateStudentAge(
3135
@Min(value = 7, message = "范围要在7~20之内", groups = ValidationTestData.StudentGroup.class) @Max(
3236
value = 20, message = "范围要在7~20之内",
@@ -35,10 +39,14 @@ public void validateStudentAge(
3539
}
3640
}
3741

38-
// 教师年龄验证服务。
3942
@Component
4043
@Validated(ValidationTestData.TeacherGroup.class)
4144
public static class TeacherValidateService {
45+
/**
46+
* 验证教师年龄。
47+
*
48+
* @param age 年龄 {@code int}
49+
*/
4250
public void validateTeacherAge(
4351
@Min(value = 22, message = "范围要在22~65之内", groups = ValidationTestData.TeacherGroup.class) @Max(
4452
value = 65, message = "范围要在22~65之内",
@@ -51,8 +59,13 @@ public void validateTeacherAge(
5159
@Component
5260
@Validated(ValidationTestData.AdvancedGroup.class)
5361
public static class AdvancedValidateService {
62+
/**
63+
* 验证高级分组数据。
64+
*
65+
* @param data 用于测试复杂对象验证的数据 {@link ValidationTestData}
66+
*/
5467
public void validateAdvancedGroup(@Valid ValidationTestData data) {
5568
LOG.debug("Validating advanced group data: {}", data);
5669
}
5770
}
58-
}
71+
}

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

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -126,7 +126,7 @@ public void testSize(@Size(min = 2, max = 10) String value) {}
126126
/**
127127
* 测试 List 的 Size 约束注解。
128128
*
129-
* @param value 表示输入的 {@code List<String>}。
129+
* @param value 表示输入的 {@link List}{@code <}{@link String}{@code >}。
130130
*/
131131
public void testSizeList(@Size(min = 1, max = 3) List<String> value) {}
132132

@@ -343,7 +343,7 @@ public void validateCompany(@Valid Company company) {
343343
/**
344344
* 验证员工列表。
345345
*
346-
* @param employees 表示输入的 {@link List<Employee>}。
346+
* @param employees 表示输入的 {@link List}{@code <}{@link Employee}{@code >}。
347347
*/
348348
public void validateEmployeeList(List<@Valid Employee> employees) {
349349
LOG.debug("Validating employee list: {}", employees);
@@ -352,7 +352,7 @@ public void validateEmployeeList(List<@Valid Employee> employees) {
352352
/**
353353
* 验证嵌套员工列表。
354354
*
355-
* @param nestedList 表示输入的 {@link List<List<Employee>>}。
355+
* @param nestedList 表示输入的 {@link List}{@code <}{@link List}{@code <}{@link Employee}{@code >}{@code >}}。
356356
*/
357357
public void validateNestedEmployeeList(List<List<@Valid Employee>> nestedList) {
358358
LOG.debug("Validating nested employee list: {}", nestedList);
@@ -361,7 +361,7 @@ public void validateNestedEmployeeList(List<List<@Valid Employee>> nestedList) {
361361
/**
362362
* 验证员工映射。
363363
*
364-
* @param employeeMap 表示输入的 {@code Map<String, Employee>}。
364+
* @param employeeMap 表示输入的 {@link Map}{@code <}{@link String}{@code , }{@link Employee}{@code >}。
365365
*/
366366
public void validateEmployeeMap(@Valid Map<String, Employee> employeeMap) {
367367
LOG.debug("Validating employee map: {}", employeeMap);
@@ -370,7 +370,7 @@ public void validateEmployeeMap(@Valid Map<String, Employee> employeeMap) {
370370
/**
371371
* 验证员工数据映射。
372372
*
373-
* @param map 表示输入的 {@code Map<Employee, ValidationTestData>}。
373+
* @param map 表示输入的 {@link Map}{@code <}{@link Employee}{@code , }{@link ValidationTestData}>。
374374
*/
375375
public void validateEmployeeDataMap(@Valid Map<Employee, ValidationTestData> map) {
376376
LOG.debug("Validating employee data map: {}", map);
@@ -379,7 +379,9 @@ public void validateEmployeeDataMap(@Valid Map<Employee, ValidationTestData> map
379379
/**
380380
* 验证嵌套员工数据映射。
381381
*
382-
* @param nestedMap 表示输入的 {@code Map<Employee, Map<String, ValidationTestData>>}。
382+
* @param nestedMap 表示输入的
383+
* {@link Map}{@code <}{@link Employee}{@code , }{@link Map}{@code <}{@link String}{@code , }{@link
384+
* ValidationTestData}{@code >}{@code >}。
383385
*/
384386
public void validateNestedEmployeeDataMap(Map<@Valid Employee, Map<String, @Valid ValidationTestData>> nestedMap) {
385387
LOG.debug("Validating nested employee data map: {}", nestedMap);
@@ -388,7 +390,8 @@ public void validateNestedEmployeeDataMap(Map<@Valid Employee, Map<String, @Vali
388390
/**
389391
* 验证员工映射列表。
390392
*
391-
* @param listOfMaps 表示输入的 {@code List<Map<String, Employee>>}。
393+
* @param listOfMaps 表示输入的 {@link List}{@code <}{@link Map}{@code <}{@link String}{@code ,
394+
* }{@link Employee}{@code >}{@code >}。
392395
*/
393396
public void validateEmployeeMapList(List<Map<String, @Valid Employee>> listOfMaps) {
394397
LOG.debug("Validating employee map list: {}", listOfMaps);
@@ -397,7 +400,7 @@ public void validateEmployeeMapList(List<Map<String, @Valid Employee>> listOfMap
397400
/**
398401
* 验证员工数据列表映射。
399402
*
400-
* @param map 表示输入的 {@code Map<Employee, List<ValidationTestData>>}。
403+
* @param map 表示输入的 {@link Map}{@code <}{@link Employee}{@code , }{@link List}{@code <}{@link ValidationTestData}{@code >}{}。
401404
*/
402405
public void validateEmployeeDataListMap(Map<@Valid Employee, List<@Valid ValidationTestData>> map) {
403406
LOG.debug("Validating employee data list map: {}", map);
@@ -406,7 +409,7 @@ public void validateEmployeeDataListMap(Map<@Valid Employee, List<@Valid Validat
406409
/**
407410
* 验证公司列表。
408411
*
409-
* @param companies 表示输入的 {@code List<Company>}。
412+
* @param companies 表示输入的 {@link List}{@code <}{@link Company}{@code >}。
410413
*/
411414
public void validateCompanyList(@Valid List<Company> companies) {
412415
LOG.debug("Validating company list: {}", companies);
@@ -425,8 +428,8 @@ public void validateMixed(@Positive int value, @Valid Employee employee) {
425428
/**
426429
* 验证混合集合数据。
427430
*
428-
* @param list1 表示输入的 {@code List<String>}。
429-
* @param list2 表示输入的 {@code List<String>}。
431+
* @param list1 表示输入的 {@link List}{@code <}{@link String}{@code >}。
432+
* @param list2 表示输入的 {@link List}{@code <}{@link String}{@code >}。
430433
*/
431434
public void validateMixedCollections(@NotNull List<String> list1, @NotEmpty List<String> list2) {
432435
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‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,24 +26,43 @@ public class LocaleMessageInterpolator implements MessageInterpolator {
2626

2727
private Locale locale;
2828

29+
/**
30+
* 构造函数，使用指定的目标消息插值器初始化实例。
31+
*
32+
* @param target 目标消息插值器 {@link MessageInterpolator}。
33+
*/
2934
public LocaleMessageInterpolator(MessageInterpolator target) {
3035
this.target = target;
3136
this.locale = Locale.getDefault();
3237
}
3338

39+
/**
40+
* 构造函数，使用指定的地区初始化实例。
41+
*
42+
* @param locale 指定的地区 {@link Locale}。
43+
*/
3444
public LocaleMessageInterpolator(Locale locale) {
3545
this.locale = locale;
3646
this.target = new ParameterMessageInterpolator();
3747
}
3848

49+
/**
50+
* 构造函数，使用指定的目标消息插值器和地区初始化实例。
51+
*
52+
* @param target 被代理的目标消息插值器 {@link MessageInterpolator}。
53+
* @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
54+
*/
3955
public LocaleMessageInterpolator(MessageInterpolator target, Locale locale) {
4056
this.target = target;
4157
this.locale = locale;
4258
}
4359

60+
/**
61+
* 构造函数，使用默认地区初始化实例。
62+
*/
4463
public LocaleMessageInterpolator() {
45-
locale = Locale.getDefault();
46-
target = new ParameterMessageInterpolator();
64+
this.locale = Locale.getDefault();
65+
this.target = new ParameterMessageInterpolator();
4766
}
4867

4968
@Override
@@ -56,6 +75,11 @@ public String interpolate(String messageTemplate, Context context, Locale locale
5675
return target.interpolate(messageTemplate, context, this.locale);
5776
}
5877

78+
/**
79+
* 设置地区。
80+
*
81+
* @param locale 指示当前消息插值器要使用语言的相关地区 {@link Locale}。
82+
*/
5983
public void setLocale(Locale locale) {
6084
this.locale = locale;
6185
}

0 commit comments

Comments
 (0)