[fit] 完善注释

Author: Yager-42

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

@@ -15,7 +15,7 @@
 import java.util.Locale;
 
 /**
- * 检验消息处理包装类。
+ * 检验消息处理的代理类。
  * <p>
  * 从 {@link LocaleContextHolder} 中获取当前线程设置的 {@link Locale} 并委托 {@link MessageInterpolator} 去处理消息。
  * </p>
@@ -24,13 +24,20 @@
  * @since 2025-07-31
  */
 public class LocaleContextMessageInterpolator implements MessageInterpolator {
-
     private final MessageInterpolator targetInterpolator;
 
+    /**
+     * 构造函数。
+     *
+     * @param targetInterpolator 表示目标检验消息处理对象的 {@link MessageInterpolator}。
+     */
     public LocaleContextMessageInterpolator(MessageInterpolator targetInterpolator) {
         this.targetInterpolator = targetInterpolator;
     }
 
+    /**
+     * 构造函数，默认使用 {@link ParameterMessageInterpolator} 作为目标检验消息处理对象。
+     */
     public LocaleContextMessageInterpolator() {
         this.targetInterpolator = new ParameterMessageInterpolator();
     }

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

@@ -15,7 +15,7 @@
 import jakarta.validation.Valid;
 
 /**
- * 地区验证控制器 - 测试ValidationHandler与LocaleContextMessageInterpolator的集成
+ * 用于测试 {@link ValidationHandler} 与 {@link LocaleContextMessageInterpolator} 的集成地区验证控制器。
  *
  * @author 阮睿
  * @since 2025-08-01
@@ -24,13 +24,11 @@
 @RequestMapping(path = "/validation/locale", group = "地区验证测试接口")
 @Validated
 public class LocaleValidationController {
-
     /**
-     * 测试验证消息的地区化 - 使用简单参数
+     * 使用简单参数测试验证消息的地区化。
      *
-     * @param company 表示注解验证类 {@link Company}。
+     * @param company 表示注解验证的测试实体类 {@link Company}。
      */
     @PostMapping(path = "/simple", description = "测试简单参数的地区化验证消息")
     public void validateSimpleParam(@RequestBody @Valid Company company) {}
-
 }

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

@@ -26,15 +26,14 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
- * {@link LocaleValidationController} 的测试集。
+ * 表示评估国际化校验的测试类。
  *
  * @author 阮睿
  * @since 2025-08-01
  */
 @MvcTest(classes = {LocaleValidationController.class})
 @DisplayName("测试地区化验证消息功能")
 public class LocaleValidationControllerTest {
-
     @Fit
     private MockMvc mockMvc;
 

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

@@ -11,13 +11,18 @@
 import modelengine.fitframework.annotation.Component;
 
 /**
- * {@link LocaleResolveFilter} 配置类
+ * 表示 {@link LocaleResolveFilter} 的配置类。
  *
  * @author 阮睿
  * @since 2025-08-01
  */
 @Component
 public class localeResolveConfig {
+    /**
+     * 注册一个 {@link LocaleResolveFilter} 的 bean。
+     *
+     * @return 返回一个 {@link LocaleResolveFilter} 的实例。
+     */
     @Bean
     public LocaleResolveFilter localeResolveFilter() {
         return new LocaleResolveFilter();

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

@@ -15,7 +15,7 @@
 import java.util.Locale;
 
 /**
- * 检验消息处理包装类。
+ * 检验消息处理的代理类。
  * <p>
  * 从 {@link LocaleContextHolder} 中获取当前线程设置的 {@link Locale} 并委托 {@link MessageInterpolator} 去处理消息。
  * </p>
@@ -24,13 +24,20 @@
  * @since 2025-07-31
  */
 public class LocaleContextMessageInterpolator implements MessageInterpolator {
-
     private final MessageInterpolator targetInterpolator;
 
+    /**
+     * 构造函数。
+     *
+     * @param targetInterpolator 表示目标检验消息处理对象的 {@link MessageInterpolator}。
+     */
     public LocaleContextMessageInterpolator(MessageInterpolator targetInterpolator) {
         this.targetInterpolator = targetInterpolator;
     }
 
+    /**
+     * 构造函数，默认使用 {@link ParameterMessageInterpolator} 作为目标检验消息处理对象。
+     */
     public LocaleContextMessageInterpolator() {
         this.targetInterpolator = new ParameterMessageInterpolator();
     }

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-javax/src/test/java/modelengine/fitframework/validation/LocaleValidationController.java

@@ -15,7 +15,7 @@
 import modelengine.fit.http.annotation.RequestMapping;
 
 /**
- * 地区验证控制器 - 测试ValidationHandler与LocaleContextMessageInterpolator的集成
+ * 用于测试 {@link ValidationHandler} 与 {@link LocaleContextMessageInterpolator} 的集成地区验证控制器。
  *
  * @author 阮睿
  * @since 2025-08-01
@@ -24,13 +24,11 @@
 @RequestMapping(path = "/validation/locale", group = "地区验证测试接口")
 @Validated
 public class LocaleValidationController {
-
     /**
-     * 测试验证消息的地区化 - 使用简单参数
+     * 使用简单参数测试验证消息的地区化。
      *
-     * @param company 表示注解验证类 {@link Company}。
+     * @param company 表示注解验证的测试实体类 {@link Company}。
      */
     @PostMapping(path = "/simple", description = "测试简单参数的地区化验证消息")
     public void validateSimpleParam(@RequestBody @Valid Company company) {}
-
 }

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-javax/src/test/java/modelengine/fitframework/validation/LocaleValidationControllerTest.java

@@ -26,15 +26,14 @@
 import static org.assertj.core.api.Assertions.assertThat;
 
 /**
- * {@link LocaleValidationController} 的测试集。
+ * 表示评估国际化校验的测试类。
  *
  * @author 阮睿
  * @since 2025-08-01
  */
 @MvcTest(classes = {LocaleValidationController.class})
 @DisplayName("测试地区化验证消息功能")
 public class LocaleValidationControllerTest {
-
     @Fit
     private MockMvc mockMvc;
 

framework/fit/java/fit-builtin/plugins/fit-validation-hibernate-javax/src/test/java/modelengine/fitframework/validation/data/localeResolveConfig.java

@@ -11,13 +11,18 @@
 import modelengine.fitframework.annotation.Component;
 
 /**
- * {@link LocaleResolveFilter} 配置类
+ * 表示 {@link LocaleResolveFilter} 的配置类。
  *
  * @author 阮睿
  * @since 2025-08-01
  */
 @Component
 public class localeResolveConfig {
+    /**
+     * 注册一个 {@link LocaleResolveFilter} 的 bean。
+     *
+     * @return 返回一个 {@link LocaleResolveFilter} 的实例。
+     */
     @Bean
     public LocaleResolveFilter localeResolveFilter() {
         return new LocaleResolveFilter();

framework/fit/java/fit-builtin/services/fit-http-classic/definition/src/main/java/modelengine/fit/http/util/i18n/DefualtLocaleResolver.java

@@ -18,8 +18,7 @@
  * @author 阮睿
  * @since 2025-08-01
  */
-public class DefualtLocaleResolver implements LocaleResolver{
-
+public class DefualtLocaleResolver implements LocaleResolver {
     public static final String DEFAULT_COOKIE_NAME = "locale";
     public static final int DEFAULT_COOKIE_MAX_AGE = 60 * 60 * 24 * 365;
     public static final String DEFAULT_COOKIE_DOMAIN = "/";
@@ -32,7 +31,7 @@ public class DefualtLocaleResolver implements LocaleResolver{
 
     @Override
     public Locale resolveLocale(HttpClassicServerRequest request) {
-        // 先解析 Cookie，如果没有则使用 Accept-Language 头
+        // 先解析 Cookie，如果没有则解析 Accept-Language 头
         String newLocale = request.cookies().get(this.cookieName).map(Cookie::value).orElse(null);
         if (newLocale != null) {
             return Locale.forLanguageTag(newLocale);
@@ -52,39 +51,61 @@ public Locale resolveLocale(HttpClassicServerRequest request) {
 
     @Override
     public void setLocale(HttpClassicServerResponse response, Locale locale) {
-
-        if(locale != null){
-            response.cookies().add(Cookie.builder()
-                    .name(cookieName)
-                    .value(locale.toLanguageTag())
-                    .maxAge(cookieMaxAge)
-                    .domain(cookieDomain)
-                    .path(cookiePath)
-                    .build());
-        }else{
-            response.cookies().add(Cookie.builder()
-                    .name(cookieName)
-                    .maxAge(0)
-                    .build());
+        if (locale != null) {
+            response.cookies()
+                    .add(Cookie.builder()
+                            .name(cookieName)
+                            .value(locale.toLanguageTag())
+                            .maxAge(cookieMaxAge)
+                            .domain(cookieDomain)
+                            .path(cookiePath)
+                            .build());
+        } else {
+            response.cookies().add(Cookie.builder().name(cookieName).maxAge(0).build());
         }
     }
 
+    /**
+     * 设置存储地区信息的 Cookie 名称。
+     *
+     * @param cookieName 表示将要设置的 Cookie 名称 {@link String}。
+     */
     public void setCookieName(String cookieName) {
         this.cookieName = cookieName;
     }
 
+    /**
+     * 设置存储地区信息的 Cookie 的最大有效期。
+     *
+     * @param cookieMaxAge 表示将要设置的 Cookie 最大有效期的 {@code int}。
+     */
     public void setCookieMaxAge(int cookieMaxAge) {
         this.cookieMaxAge = cookieMaxAge;
     }
 
+    /**
+     * 设置存储地区信息的 Cookie 的作用域。
+     *
+     * @param cookieDomain 存储地区信息的 Cookie 作用域的 {@link String}。
+     */
     public void setCookieDomain(String cookieDomain) {
         this.cookieDomain = cookieDomain;
     }
 
+    /**
+     * 设置存储地区信息的 Cookie 的可见 URL 路径。
+     *
+     * @param cookiePath 存储地区信息的 Cookie 作用域的 {@link String}。
+     */
     public void setCookiePath(String cookiePath) {
         this.cookiePath = cookiePath;
     }
 
+    /**
+     * 设置默认地区。
+     *
+     * @param defaultLocale 表示默认地区的 {@link Locale}。
+     */
     public void setDefaultLocale(Locale defaultLocale) {
         this.defaultLocale = defaultLocale;
     }

framework/fit/java/fit-builtin/services/fit-http-classic/definition/src/main/java/modelengine/fit/http/util/i18n/LocaleResolveFilter.java

@@ -30,11 +30,19 @@ public class LocaleResolveFilter implements HttpServerFilter {
 
     private Scope scope = Scope.GLOBAL;
 
+    /**
+     * 构造函数。
+     *
+     * @param localeResolver 表示地区解析器的 {@link LocaleResolver}。
+     */
     public LocaleResolveFilter(LocaleResolver localeResolver) {
         localeResolver = localeResolver;
     }
 
-    public LocaleResolveFilter(){
+    /**
+     * 默认构造函数。
+     */
+    public LocaleResolveFilter() {
         this.localeResolver = new DefualtLocaleResolver();
     }
 
@@ -58,35 +66,29 @@ public List<String> mismatchPatterns() {
         return mismatchPatterns;
     }
 
-    /**
-     * 过滤请求，从请求中解析地区值并放入线程上下文和cookie。
-     *
-     * @param request 表示服务器请求 {@link HttpClassicServerRequest}。
-     * @param response 表示服务器响应 {@link HttpClassicServerResponse}。
-     * @param chain 过滤链 {@link HttpServerFilterChain}。
-     */
     @Override
     public void doFilter(HttpClassicServerRequest request, HttpClassicServerResponse response,
             HttpServerFilterChain chain) throws DoHttpServerFilterException {
         try {
-            // 如果参数中带有地区，则直接设置地区
+            // 如果参数中带有地区，说明用户想使用新地区执行后续的操作，直接设置地区。
             String paramLocale = request.queries().first("locale").orElse(null);
             Locale responseLocale = null;
             if (paramLocale != null && !paramLocale.trim().isEmpty()) {
                 responseLocale = Locale.forLanguageTag(paramLocale);
                 LocaleContextHolder.setLocaleContext(new LocaleContext(responseLocale));
             }
-            // 如果参数中不包含地区，则解析
-            else{
-                Locale locale =localeResolver.resolveLocale(request);
+            // 如果参数中不包含地区，则解析请求所带的地区参数。
+            else {
+                Locale locale = localeResolver.resolveLocale(request);
                 LocaleContextHolder.setLocaleContext(new LocaleContext(locale));
             }
 
+            // 继续执行后续过滤器。
             chain.doFilter(request, response);
 
-            // responseLocale是用户期望设置的地区，不受 server 端处理的影响
+            // responseLocale 是用户期望设置的地区，不受 server 端处理的影响。
             localeResolver.setLocale(response, responseLocale);
-        }finally {
+        } finally {
             LocaleContextHolder.clear();
         }