Springboot国际化消息和源码解读
写在前面
在REST接口的实现方案中，后端可以仅仅返回一个code，让前端根据code的内容做自定义的消息提醒。当然，也有直接显示后端返回消息的方案。在后端直接返回消息的方案中，如果要提供多个不同语种国家使用，则需要做国际化消息的实现。
400 BAD_REQUEST
{
"code": "user.email.token",
"message": "The email is token."
}实现的目标：
- validation的error code可以按照不同语言响应；
- 自定义error code可以按照不同语言响应；
- 指定默认的语言；
spring-boot: 2.1.6.RELEASE
sping: 5.1.8.RELEASE
java: openjdk 11.0.13初始化项目
org.springframework.boot
spring-boot-starter-web
java添加如下的Controller类和User实体类，其中的
ServiceException是一个自定义的异常类，该异常会带上业务处理过程中的异常码。@Validated
@RestController
@RequestMapping("/user")
public class UserController {private static final String TOKEN_EMAIL = "token@example.com";
@PostMapping
public User createUser(@RequestBody @Valid User user) {
if (TOKEN_EMAIL.equalsIgnoreCase(user.getEmail())) {
String message = String.format("The email %s is token.", user.getEmail());
throw new ServiceException("user.email.token", message);
}
return user;
}
}@Data
public class User {
@NotNull
@Length(min = 5, max = 12)
@Pattern(regexp = "^r.*", message = "{validation.user.username}")
private String username;
@NotNull
@Email
private String email;
@Range(min = 12, message = "{validation.user.age}")
private int age;
}Validation中实现国际化信息 基本实现
在默认的SpringBoot配置中，只要在请求中增加
Accept-Language的Header即可实现Validation错误信息的国际化。如下的请求会使用返回中文的错误信息。curl --location --request POST 'http://localhost:8080/user' \
--header 'Accept-Language: zh-CN' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "xx",
"email": "token@example.com",
"age": 24
}对于自定义的message，如
validation.user.username，则只需要在resource目录下创建一个basename为ValidationMessages的国际化信息文件即可实现。└── resources
├── ValidationMessages.properties
├── ValidationMessages_zh_CN.properties
└── application.ymlvalidation.user.age=用户的年龄应该大于{min}.
validation.user.username=用户名应该以r字母开始国家化信息文件文件名定义规则：
basename__.properties
ValidationMessages_en.properties
ValidationMessages_zh_CN.properties 更多的文件，可以到hibernate-validator的github仓库查看（文末会给出链接）。
LocaleResolver解析locale信息
在spring-framework的
spring-webmvc/.../i18n中，可以找到如下三种不同的LocaleResolver的实现：FixedLocaleResolver:
- 固定local，不做国际化更改。
- 不可动态更改local，否则抛出
UnsupportedOperationException。
AcceptHeaderLocaleResolver:
- 读取request的header中的
Accept-Language来确定local的值。 - 不可动态更改local，否则抛出
UnsupportedOperationException。
- 读取request的header中的
CookieLocaleResolver:
- 将local信息保存到cookie中，可配合
LocaleChangeInterceptor使用
- 将local信息保存到cookie中，可配合
SessionLocaleResolver:
- 将local信息保存到session中，可配合
LocaleChangeInterceptor使用
- 将local信息保存到session中，可配合
AcceptHeaderLocaleResolver。设置指定固定的locale
通过指定
spring.mvc.locale-resolver=fixed可以使用固定的locale。如果项目只有一种语言可以做该指定，以免客户端没有配置Accept-Language的header而出现多种不同的语言。spring:
mvc:
locale-resolver: fixed
locale: en在spring-boot的
spring-boot-autoconfig/.../web/serlet中可以找到如下的配置，该配置指定了localeResolver的配置方式。// spring-boot: spring-boot-autoconfig/.../web/serlet
package org.springframework.boot.autoconfigure.web.servlet;
public class WebMvcAutoConfiguration {
@Bean
@ConditionalOnMissingBean
@ConditionalOnProperty(prefix = "spring.mvc", name = "locale")
public LocaleResolver localeResolver() {
if (this.mvcProperties.getLocaleResolver() == WebMvcProperties.LocaleResolver.FIXED) {
return new FixedLocaleResolver(this.mvcProperties.getLocale());
}
AcceptHeaderLocaleResolver localeResolver = new AcceptHeaderLocaleResolver();
localeResolver.setDefaultLocale(this.mvcProperties.getLocale());
return localeResolver;
}
}package org.springframework.boot.autoconfigure.web.servlet;
@ConfigurationProperties(prefix = "spring.mvc")
public class WebMvcProperties {
...
/**
* Locale to use. By default, this locale is overridden by the "Accept-Language"
* header.
*/
private Locale locale;
/**
* Define how the locale should be resolved.
*/
private LocaleResolver localeResolver = LocaleResolver.ACCEPT_HEADER;
...
}通过Url指定Locale
通过
LocaleChangeInterceptor获取请求中的lang参数来设定语言，并将locale保存到Cookie中，请求了一次之后，相同的请求就无需再带上该lang参数，即可使用原本已经设定的locale。@Configuration
@ConditionalOnProperty(prefix = "spring.mvc", name = "customer-locale-resolver", havingValue = "https://www.it610.com/article/cookie")
public class MvcConfigurer implements WebMvcConfigurer {@Bean
public LocaleResolver localeResolver(@Value("${spring.mvc.locale:null}") Locale locale) {
CookieLocaleResolver resolver = new CookieLocaleResolver();
if (locale != null) {
resolver.setDefaultLocale(locale);
}
return resolver;
}@Bean
public LocaleChangeInterceptor localeInterceptor() {
LocaleChangeInterceptor localeInterceptor = new LocaleChangeInterceptor();
localeInterceptor.setParamName("lang");
return localeInterceptor;
}@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeInterceptor());
}
}curl --location --request POST 'http://localhost:8080/user?lang=en' \
--header 'Content-Type: application/json' \
--data-raw '{
"username": "rxdxxxx",
"email": "token@example.com",
"age": 24
}'之后的请求只要带上含有设置的cookie即可。
curl --location --request POST 'http://localhost:8080/user' \
--header 'Content-Type: application/json' \
--header 'Cookie: org.springframework.web.servlet.i18n.CookieLocaleResolver.LOCALE=zh-CN' \
--data-raw '{
"username": "rxdxxxx",
"email": "token@example.com",
"age": 24
}'自定义Error Code实现国际化信息 在前文给出的代码中，当email为
token@example.com时，抛出邮箱已被占用的异常。自定义异常中的code不是通过validator校验，所以不能通过validator自动处理。需要通过MessageSource来将定义的code转化为message，可以将MessageSource理解为一个key-value结构的类。在
resources目录下创建目录i18n，然后创建以messages为basename的国际化信息文件。如下面的目录结构。└── resources
├── ValidationMessages.properties
├── ValidationMessages_zh_CN.properties
├── application.yml
└── i18n
├── messages.properties
├── messages_en.properties
└── messages_zh_CN.propertiesmessage_zh_CN.properties
user.email.token=邮箱已存在在
application.yml中添加如下配置，即可让springboot生成含有i18n/messages中的properties的配置了。默认情况下，spring.messages.basename=messages，也就是可以直接在resources目录下创建需要的messages国际化信息文件。这里为了把i18n配置都放到一个目录下才做了修改，也可以不修改。spring:
messages:
basename: i18n/messages定义
ApiExceptionHandler捕获指定的异常，并在其中的code转化为message。package io.github.donespeak.springbootsamples.i18n.support;
import io.github.donespeak.springbootsamples.i18n.core.ServiceException;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.MessageSource;
import org.springframework.http.HttpHeaders;
import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;
import org.springframework.web.context.request.WebRequest;
import org.springframework.web.servlet.LocaleResolver;
import javax.servlet.http.HttpServletRequest;
import java.util.Locale;
@Slf4j
@RestControllerAdvice
public class ApiExceptionHandler {
// 用于获取当前的locale
private LocaleResolver localeResolver;
// 含有配置的code-message对
private MessageSource messageSource;
public ApiExceptionHandler(LocaleResolver localeResolver, MessageSource messageSource) {
this.localeResolver = localeResolver;
this.messageSource = messageSource;
}@ExceptionHandler(ServiceException.class)
public ResponseEntitycode转化为国际化信息的message也就配置完成了。如果对于其他的在
ResponseEntityExceptionHandler中定义的Exception也需要做国际化信息转化的话，也可以按照上面处理ServiceException的方法进行定义即可。源码探究 按照上面的代码操作，已经可以解决需要实现的功能了。这部分将会讲解国际化信息的功能涉及到的源码部分。
Springboot如何获取messages文件生成MessageSource
在Springboot的
spring-boot-autoconfig中配置MessageSource的Properties类为MessageSourceProperties，该类默认指定了basename为messages。package org.springframework.boot.autoconfigure.context;
public class MessageSourceProperties {
...
// 默认值
private String basename = "messages";
...
}下面的
MessageSourceAutoConfiguration为配置MessageSource的实现。package org.springframework.boot.autoconfigure.context;
public class MessageSourceAutoConfiguration {
...
@Bean
public MessageSource messageSource(MessageSourceProperties properties) {
ResourceBundleMessageSource messageSource = new ResourceBundleMessageSource();
if (StringUtils.hasText(properties.getBasename())) {
// 设置 MessageSource的basename
messageSource.setBasenames(StringUtils
.commaDelimitedListToStringArray(StringUtils.trimAllWhitespace(properties.getBasename())));
}
if (properties.getEncoding() != null) {
messageSource.setDefaultEncoding(properties.getEncoding().name());
}
messageSource.setFallbackToSystemLocale(properties.isFallbackToSystemLocale());
Duration cacheDuration = properties.getCacheDuration();
if (cacheDuration != null) {
messageSource.setCacheMillis(cacheDuration.toMillis());
}
messageSource.setAlwaysUseMessageFormat(properties.isAlwaysUseMessageFormat());
messageSource.setUseCodeAsDefaultMessage(properties.isUseCodeAsDefaultMessage());
return messageSource;
}
...
}Validation如何使用到ValidationMessages
springboot的
spring-boot-autoconfigure/.../validation/ValidationAutoConfiguration为Validator的配置类。package org.springframework.boot.autoconfigure.validation;
/**
* @since 1.5.0
*/
@Configuration
@ConditionalOnClass(ExecutableValidator.class)
@ConditionalOnResource(resources = "classpath:META-INF/services/javax.validation.spi.ValidationProvider")
@Import(PrimaryDefaultValidatorPostProcessor.class)
public class ValidationAutoConfiguration {
// 创建Validator
@Bean
@Role(BeanDefinition.ROLE_INFRASTRUCTURE)
@ConditionalOnMissingBean(Validator.class)
public static LocalValidatorFactoryBean defaultValidator() {
LocalValidatorFactoryBean factoryBean = new LocalValidatorFactoryBean();
// 提供message和LocaleResolver
MessageInterpolatorFactory interpolatorFactory = new MessageInterpolatorFactory();
factoryBean.setMessageInterpolator(interpolatorFactory.getObject());
return factoryBean;
}@Bean
@ConditionalOnMissingBean
public static MethodValidationPostProcessor methodValidationPostProcessor(Environment environment,
@Lazy Validator validator) {
MethodValidationPostProcessor processor = new MethodValidationPostProcessor();
// proxy-target-class="true" 则使用cglib2
boolean proxyTargetClass = environment.getProperty("spring.aop.proxy-target-class", Boolean.class, true);
processor.setProxyTargetClass(proxyTargetClass);
processor.setValidator(validator);
return processor;
}
}这里重点关注一下
MessageInterpolatorFactory类，该类最后会创建一个org.hibernate.validator.messageinterpolatio.ResourceBundleMessageInterpolator。package org.springframework.boot.validation;
public class MessageInterpolatorFactory implements ObjectFactory {private static final Set FALLBACKS;
static {
Set fallbacks = new LinkedHashSet<>();
fallbacks.add("org.hibernate.validator.messageinterpolation" + ".ParameterMessageInterpolator");
FALLBACKS = Collections.unmodifiableSet(fallbacks);
}@Override
public MessageInterpolator getObject() throws BeansException {
try {
// 这里提供默认的MessageInterpolator，获取到ConfigurationImpl
// 最终得到 org.hibernate.validator.messageinterpolation.ResourceBundleMessageInterpolator
return Validation.byDefaultProvider().configure().getDefaultMessageInterpolator();
}
catch (ValidationException ex) {
MessageInterpolator fallback = getFallback();
if (fallback != null) {
return fallback;
}
throw ex;
}
}
...
} ResourceBundleMessageInterpolator是AbstractMessageInterpolator的一个子类，该类定义了validation messages文件的路径，其中org.hibernate.validator.ValidationMessages为hibernate提供的，而用户自定义的为ValidationMessages。package org.hibernate.validator.messageinterpolation;
public abstract class AbstractMessageInterpolator implements MessageInterpolator {
/**
* The name of the default message bundle.
*/
public static final String DEFAULT_VALIDATION_MESSAGES = "org.hibernate.validator.ValidationMessages";
/**
* The name of the user-provided message bundle as defined in the specification.
*/
public static final String USER_VALIDATION_MESSAGES = "ValidationMessages";
/**
* Default name of the message bundle defined by a constraint definition contributor.
*
* @since 5.2
*/
public static final String CONTRIBUTOR_VALIDATION_MESSAGES = "ContributorValidationMessages";
...}在Springboot 2.6.0及之后，对validation进行了修改。如果需要使用，则需要按照如下的方式引入：
org.springframework.boot
spring-boot-starter-web
2.6.2
org.springframework.boot
spring-boot-starter-validation
2.6.2
此外，还对
MessageInterpolatorFactory进行了修改，允许设置外部的MessageSource。还增加了一个MessageSourceMessageInterpolator来整合messageSource和MessageInterpolator。
public class MessageInterpolatorFactory implements ObjectFactory {
...
private final MessageSource messageSource;
public MessageInterpolatorFactory() {
this(null);
}/**
* Creates a new {@link MessageInterpolatorFactory} that will produce a
* {@link MessageInterpolator} that uses the given {@code messageSource} to resolve
* any message parameters before final interpolation.
* @param messageSource message source to be used by the interpolator
* @since 2.6.0
*/
public MessageInterpolatorFactory(MessageSource messageSource) {
// 允许使用外部的messageSource
this.messageSource = messageSource;
}@Override
public MessageInterpolator getObject() throws BeansException {
MessageInterpolator messageInterpolator = getMessageInterpolator();
if (this.messageSource != null) {
return new MessageSourceMessageInterpolator(this.messageSource, messageInterpolator);
}
return messageInterpolator;
}private MessageInterpolator getMessageInterpolator() {
try {
return Validation.byDefaultProvider().configure().getDefaultMessageInterpolator();
}
catch (ValidationException ex) {
MessageInterpolator fallback = getFallback();
if (fallback != null) {
return fallback;
}
throw ex;
}
}
...
} MessageSourceMessageInterpolator会优先使用messageSource处理，再通过messageInterpolator处理。package org.springframework.boot.validation;
class MessageSourceMessageInterpolator implements MessageInterpolator {
...
@Override
public String interpolate(String messageTemplate, Context context) {
return interpolate(messageTemplate, context, LocaleContextHolder.getLocale());
}@Override
public String interpolate(String messageTemplate, Context context, Locale locale) {
// 优先通过messageSource替换占位符，在通过messageInterpolator做处理
String message = replaceParameters(messageTemplate, locale);
return this.messageInterpolator.interpolate(message, context, locale);
}
...
}【Springboot国际化消息和源码解读】如需了解更多的信息，可以去查看
org.springframework.validation.beanvalidation。LocalValidatorFactoryBean的源码。参考
- 本文项目源码
- source code of Spring Boot’s Auto-configuration class for MessageSource - Github
- Spring Boot internationalization: Step-by-step - Lokalise Blog
- ValidationMessages files in hibernate-validator repository
- Internationalization - springboot docs
推荐阅读
- Activiti（一）SpringBoot2集成Activiti6
- 危险也是机会
- python学习之|python学习之 实现QQ自动发送消息
- SpringBoot调用公共模块的自定义注解失效的解决
- 解决SpringBoot引用别的模块无法注入的问题
- 深入浅出谈一下有关分布式消息技术（Kafka）
- springboot使用redis缓存
- springboot整合数据库连接池-->druid
- 夏夜|夏夜 我们
- Vue组件之事件总线和消息发布订阅详解