Skip to content

Commit c7afa65

Browse files
Yager-42Yager-42
committed
完善注释
1 parent dfec108 commit c7afa65

8 files changed

Lines changed: 141 additions & 42 deletions

File tree

‎framework/fit/java/fit-builtin/plugins/fit-i18n-registry/src/main/java/modelengine/fitframework/i18n/LocaleResolveFilter.java‎

Lines changed: 10 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/*---------------------------------------------------------------------------------------------
2+
* Copyright (c) 2025 Huawei Technologies Co., Ltd. All rights reserved.
3+
* This file is a part of the ModelEngine Project.
4+
* Licensed under the MIT License. See License.txt in the project root for license information.
5+
*--------------------------------------------------------------------------------------------*/
6+
17
package modelengine.fitframework.i18n;
28

39
import modelengine.fit.http.server.DoHttpServerFilterException;
@@ -51,12 +57,12 @@ public int priority() {
5157

5258
@Override
5359
public List<String> matchPatterns() {
54-
return matchPatterns;
60+
return this.matchPatterns;
5561
}
5662

5763
@Override
5864
public List<String> mismatchPatterns() {
59-
return mismatchPatterns;
65+
return this.mismatchPatterns;
6066
}
6167

6268
@Override
@@ -67,7 +73,7 @@ public void doFilter(HttpClassicServerRequest request, HttpClassicServerResponse
6773
String paramLocale = request.queries().first("locale").orElse(null);
6874
Locale responseLocale = null;
6975
// 使用责任链解析 locale
70-
LocaleResolver localeResolver = localeResolverRegistry.dispatch(request);
76+
LocaleResolver localeResolver = this.localeResolverRegistry.dispatch(request);
7177
if (paramLocale != null && !paramLocale.trim().isEmpty()) {
7278
responseLocale = Locale.forLanguageTag(paramLocale);
7379
LocaleContextHolder.setLocaleContext(new LocaleContext(responseLocale));
@@ -91,6 +97,6 @@ public void doFilter(HttpClassicServerRequest request, HttpClassicServerResponse
9197

9298
@Override
9399
public Scope scope() {
94-
return scope;
100+
return this.scope;
95101
}
96102
}

‎framework/fit/java/fit-builtin/plugins/fit-i18n-registry/src/main/java/modelengine/fitframework/i18n/LocaleResolverRegistry.java‎

Lines changed: 75 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/*---------------------------------------------------------------------------------------------
2+
* Copyright (c) 2025 Huawei Technologies Co., Ltd. All rights reserved.
3+
* This file is a part of the ModelEngine Project.
4+
* Licensed under the MIT License. See License.txt in the project root for license information.
5+
*--------------------------------------------------------------------------------------------*/
6+
17
package modelengine.fitframework.i18n;
28

39
import static modelengine.fitframework.inspection.Validation.notBlank;
@@ -15,86 +21,131 @@
1521
import modelengine.fitframework.plugin.Plugin;
1622
import modelengine.fitframework.plugin.PluginStartedObserver;
1723
import modelengine.fitframework.plugin.PluginStoppingObserver;
24+
1825
import java.util.List;
1926
import java.util.Map;
2027
import java.util.Optional;
2128
import java.util.concurrent.ConcurrentHashMap;
2229
import java.util.stream.Collectors;
30+
2331
import modelengine.fitframework.resource.UrlUtils;
2432
import modelengine.fitframework.util.OptionalUtils;
2533
import modelengine.fitframework.util.StringUtils;
2634
import modelengine.fitframework.util.wildcard.PathPattern;
2735
import modelengine.fitframework.util.wildcard.Pattern;
2836

37+
/**
38+
* 地区解析器注册中心
39+
*
40+
* @author 阮睿
41+
* @since 2025-09-07
42+
*/
2943
@Component
3044
public class LocaleResolverRegistry implements PluginStartedObserver, PluginStoppingObserver {
3145
private static final char PATH_SEPARATOR = '/';
3246

33-
// 参考DefaultHttpDispatcher的三层结构
47+
// 参考 DefaultHttpDispatcher 的三层结构
3448
private final Map<String, LocaleResolver> noPathVariableResolvers = new ConcurrentHashMap<>();
3549
private final Map<String, MappingTree<LocaleResolver>> pathVariableResolvers = new ConcurrentHashMap<>();
3650
private final Map<String, LocaleResolver> wildcardResolvers = new ConcurrentHashMap<>();
3751

3852
private final LocaleResolver defaultLocaleResolver = new DefualtLocaleResolver();
3953

54+
/**
55+
* 构造函数。
56+
*/
4057
public LocaleResolverRegistry() {
4158
// 与 DefaultHttpDispatcher 保持一致，使用 ConcurrentHashMap 提供线程安全。
4259
this.pathVariableResolvers.put(DefaultMappingTree.PATH_SEPARATOR, new DefaultMappingTree<>());
4360
}
4461

62+
/**
63+
* 注册地区解析器。
64+
*
65+
* @param resolver 表示将要被注册地区解析器的 {@link LocaleResolver}。
66+
*/
4567
public void register(LocaleResolver resolver) {
4668
notNull(resolver, "The locale resolver cannot be null.");
4769
String pathPattern = MappingTree.convertToMatchedPathPattern(resolver.getUrlPattern());
4870
notBlank(pathPattern, "The path pattern cannot be blank.");
4971
LocaleResolver preResolver;
5072
if (pathPattern.contains("**")) {
51-
preResolver = wildcardResolvers.put(pathPattern, resolver);
73+
preResolver = this.wildcardResolvers.put(pathPattern, resolver);
5274
} else if (pathPattern.contains("*")) {
53-
preResolver = pathVariableResolvers.get(DefaultMappingTree.PATH_SEPARATOR)
75+
preResolver = this.pathVariableResolvers.get(DefaultMappingTree.PATH_SEPARATOR)
5476
.register(pathPattern, resolver)
5577
.orElse(null);
56-
;
5778
} else {
58-
preResolver = noPathVariableResolvers.put(pathPattern, resolver);
79+
preResolver = this.noPathVariableResolvers.put(pathPattern, resolver);
5980
}
6081
if (preResolver != null) {
6182
String message = StringUtils.format("Locale resolver has been registered. [pattern={0}]", pathPattern);
6283
throw new RegisterLocaleResolverException(message);
6384
}
6485
}
6586

87+
/**
88+
* 取消注册地区解析器。
89+
*
90+
* @param resolver 表示待取消注册地区解析器的 {@link LocaleResolver}。
91+
*/
6692
public void unregister(LocaleResolver resolver) {
6793
notNull(resolver, "The locale resolver cannot be null.");
6894
String pathPattern = MappingTree.convertToMatchedPathPattern(resolver.getUrlPattern());
6995
notBlank(pathPattern, "The path pattern cannot be blank.");
7096
if (pathPattern.contains("**")) {
71-
wildcardResolvers.remove(pathPattern);
97+
this.wildcardResolvers.remove(pathPattern);
7298
} else if (pathPattern.contains("*")) {
73-
pathVariableResolvers.get(DefaultMappingTree.PATH_SEPARATOR).unregister(pathPattern);
99+
this.pathVariableResolvers.get(DefaultMappingTree.PATH_SEPARATOR).unregister(pathPattern);
74100
;
75101
} else {
76-
noPathVariableResolvers.remove(pathPattern);
102+
this.noPathVariableResolvers.remove(pathPattern);
77103
}
78104
}
79105

106+
/**
107+
* 分派地区解析器。
108+
*
109+
* @param request 表示用于查找对应 {@link LocaleResolver} 请求的 {@link HttpClassicServerRequest}。
110+
* @return 返回匹配的 {@link LocaleResolver}。
111+
*/
80112
public LocaleResolver dispatch(HttpClassicServerRequest request) {
81113
String path = UrlUtils.decodePath(request.path());
82114
return (LocaleResolver) OptionalUtils.get(() -> selectFromNoPathVariableResolvers(path))
83115
.orElse(() -> selectFromPathVariableResolvers(path))
84-
.orElse(() -> selectFromWildcardResolvers(path)).orDefault(this.defaultLocaleResolver);
116+
.orElse(() -> selectFromWildcardResolvers(path))
117+
.orDefault(this.defaultLocaleResolver);
85118
}
86119

120+
/**
121+
* 从无路径参数的解析器中查找匹配的解析器。
122+
*
123+
* @param path 表示待匹配路径的 {@link String}。
124+
* @return 表示匹配对应路径解析器的 {@link Optional}{@code <}{@link LocaleResolver}{@code >}。。
125+
*/
87126
private Optional<LocaleResolver> selectFromNoPathVariableResolvers(String path) {
88-
LocaleResolver resolver = noPathVariableResolvers.get(path);
127+
LocaleResolver resolver = this.noPathVariableResolvers.get(path);
89128
return Optional.ofNullable(resolver);
90129
}
91130

131+
/**
132+
* 从路径参数的解析器中查找匹配的解析器。
133+
*
134+
* @param path 待匹配路径的 {@link String}。
135+
* @return 匹配对应路径解析器的 {@link Optional}{@code <}{@link LocaleResolver}{@code >}。
136+
*/
92137
private Optional<LocaleResolver> selectFromPathVariableResolvers(String path) {
93-
return pathVariableResolvers.get(DefaultMappingTree.PATH_SEPARATOR).search(path);
138+
return this.pathVariableResolvers.get(DefaultMappingTree.PATH_SEPARATOR).search(path);
94139
}
95140

141+
/**
142+
* 从通配符的解析器中查找匹配的解析器。
143+
*
144+
* @param path 待匹配路径的 {@link String}。
145+
* @return 匹配对应路径解析器的 {@link Optional}{@code <}{@link LocaleResolver}{@code >}。
146+
*/
96147
private Optional<LocaleResolver> selectFromWildcardResolvers(String path) {
97-
for (Map.Entry<String, LocaleResolver> entry : wildcardResolvers.entrySet()) {
148+
for (Map.Entry<String, LocaleResolver> entry : this.wildcardResolvers.entrySet()) {
98149
PathPattern pattern = Pattern.forPath(entry.getKey(), PATH_SEPARATOR);
99150
if (pattern.matches(path)) {
100151
return Optional.of(entry.getValue());
@@ -103,26 +154,36 @@ private Optional<LocaleResolver> selectFromWildcardResolvers(String path) {
103154
return Optional.empty();
104155
}
105156

157+
/**
158+
* 当插件启动时，注册插件中的地区解析器。
159+
*
160+
* @param plugin 待注册插件的 {@link Plugin}。
161+
*/
106162
@Override
107163
public void onPluginStarted(Plugin plugin) {
108164
BeanContainer container = plugin.container();
109165
List<LocaleResolver> localeResolvers = container.all(LocaleResolver.class)
110166
.stream()
111167
.map(BeanFactory::<LocaleResolver>get)
112168
.collect(Collectors.toList());
113-
for(LocaleResolver localeResolver : localeResolvers) {
169+
for (LocaleResolver localeResolver : localeResolvers) {
114170
this.register(localeResolver);
115171
}
116172
}
117173

174+
/**
175+
* 当插件停止时，取消注册插件中的地区解析器。
176+
*
177+
* @param plugin 待取消注册插件的 {@link Plugin}。
178+
*/
118179
@Override
119180
public void onPluginStopping(Plugin plugin) {
120181
BeanContainer container = plugin.container();
121182
List<LocaleResolver> localeResolvers = container.all(LocaleResolver.class)
122183
.stream()
123184
.map(BeanFactory::<LocaleResolver>get)
124185
.collect(Collectors.toList());
125-
for(LocaleResolver localeResolver : localeResolvers) {
186+
for (LocaleResolver localeResolver : localeResolvers) {
126187
this.unregister(localeResolver);
127188
}
128189
}

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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -51,14 +51,14 @@ public void setLocale(HttpClassicServerResponse response, Locale locale) {
5151
if (locale != null) {
5252
response.cookies()
5353
.add(Cookie.builder()
54-
.name(cookieName)
54+
.name(this.cookieName)
5555
.value(locale.toLanguageTag())
56-
.maxAge(cookieMaxAge)
57-
.domain(cookieDomain)
58-
.path(cookiePath)
56+
.maxAge(this.cookieMaxAge)
57+
.domain(this.cookieDomain)
58+
.path(this.cookiePath)
5959
.build());
6060
} else {
61-
response.cookies().add(Cookie.builder().name(cookieName).maxAge(0).build());
61+
response.cookies().add(Cookie.builder().name(this.cookieName).maxAge(0).build());
6262
}
6363
}
6464

@@ -75,7 +75,7 @@ public void setUrlPattern(String urlPattern) {
7575
/**
7676
* 设置存储地区信息的 Cookie 名称。
7777
*
78-
* @param cookieName 表示将要设置的 Cookie 名称 {@link String}。
78+
* @param cookieName 表示将要设置 Cookie 名称的 {@link String}。
7979
*/
8080
public void setCookieName(String cookieName) {
8181
this.cookieName = cookieName;

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

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@
1212
import java.util.Locale;
1313

1414
/**
15-
* 地区解析器接口，用于从HTTP请求中解析用户的地区设置。
15+
* 地区解析器接口，用于从 HTTP 请求中解析用户的地区设置。
1616
*
1717
* @author 阮睿
1818
* @since 2025-08-01
@@ -26,20 +26,30 @@ public interface LocaleResolver {
2626
/**
2727
* 解析用户的地区设置。
2828
*
29-
* @param request 表示待解析的HTTP请求 {@link HttpClassicServerRequest}。
30-
* @return 表示解析出来的地区信息 {@link Locale}。
29+
* @param request 表示待解析 HTTP 请求的 {@link HttpClassicServerRequest}。
30+
* @return 表示解析出来地区信息的 {@link Locale}。
3131
*/
3232
Locale resolveLocale(HttpClassicServerRequest request);
3333

3434
/**
3535
* 设置地区到返回响应中。
3636
*
37-
* @param response 表示将要设置地区的HTTP响应 {@link HttpClassicServerResponse}。
38-
* @param locale 表示要设置的地区 {@link Locale}。
37+
* @param response 表示将要设置地区 HTTP 响应的 {@link HttpClassicServerResponse}。
38+
* @param locale 表示要设置地区的 {@link Locale}。
3939
*/
4040
void setLocale(HttpClassicServerResponse response, Locale locale);
4141

42+
/**
43+
* 获取地区解析器的 URL 模式。
44+
*
45+
* @return 获取地区解析器 URL 模式的 {@link String}。
46+
*/
4247
String getUrlPattern();
4348

49+
/**
50+
* 设置地区解析器的 URL 模式。
51+
*
52+
* @param urlPattern 表示待设置 URL 模式的 {@link String}。
53+
*/
4454
void setUrlPattern(String urlPattern);
4555
}

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

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,35 @@
1+
/*---------------------------------------------------------------------------------------------
2+
* Copyright (c) 2025 Huawei Technologies Co., Ltd. All rights reserved.
3+
* This file is a part of the ModelEngine Project.
4+
* Licensed under the MIT License. See License.txt in the project root for license information.
5+
*--------------------------------------------------------------------------------------------*/
6+
17
package modelengine.fit.http.util.i18n;
28

39
import modelengine.fit.http.server.HttpServerException;
410

11+
/**
12+
* 表示注册 {@link LocaleResolver} 时出现的异常。
13+
*
14+
* @author 阮睿
15+
* @since 2025-09-07
16+
*/
517
public class RegisterLocaleResolverException extends HttpServerException {
18+
/**
19+
* 通过异常消息来实例化 {@link RegisterLocaleResolverException}。
20+
*
21+
* @param message 表示异常消息的 {@link String}。
22+
*/
623
public RegisterLocaleResolverException(String message) {
724
super(message);
825
}
926

27+
/**
28+
* 通过异常消息和异常原因来实例化 {@link RegisterLocaleResolverException}。
29+
*
30+
* @param message 表示异常消息的 {@link String}。
31+
* @param cause 表示异常原因的 {@link Throwable}。
32+
*/
1033
public RegisterLocaleResolverException(String message, Throwable cause) {
1134
super(message, cause);
1235
}

0 commit comments

Comments
 (0)