Springboot国际化消息和源码解读

写在前面

在REST接口的实现方案中，后端可以仅仅返回一个code，让前端根据code的内容做自定义的消息提醒。当然，也有直接显示后端返回消息的方案。在后端直接返回消息的方案中，如果要提供多个不同语种国家使用，则需要做国际化消息的实现。

400 BAD_REQUEST
{
    "code": "user.email.token",
    "message": "The email is token."
}

实现的目标：

1. validation的error code可以按照不同语言响应；
2. 自定义error code可以按照不同语言响应；
3. 指定默认的语言；

版本说明

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 = "[email protected]";
    
    @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": "[email protected]",
    "age": 24
}

对于自定义的message，如validation.user.username，则只需要在resource目录下创建一个basename为ValidationMessages的国际化信息文件即可实现。

└── resources
    ├── ValidationMessages.properties
    ├── ValidationMessages_zh_CN.properties
    └── application.yml

validation.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。

• CookieLocaleResolver:

  • 将local信息保存到cookie中，可配合LocaleChangeInterceptor使用

• SessionLocaleResolver:

  • 将local信息保存到session中，可配合LocaleChangeInterceptor使用

默认使用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 = "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": "[email protected]",
    "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": "[email protected]",
    "age": 24
}'

自定义Error Code实现国际化信息

在前文给出的代码中，当email为[email protected]时，抛出邮箱已被占用的异常。自定义异常中的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.properties

message_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 ResponseEntity