接口返回信息国际化并不是简单地把所有文字替换成英文，而是需要建立一套可扩展的本地化资源管理机制。Spring Boot基于Spring Framework的MessageSource抽象，为应用提供了统一的文本解析入口。当用户的请求携带不同的语言标识时，程序根据Locale对象从对应的资源文件中取出文案，从而实现在不修改控制器逻辑的情况下返回不同语言的提示信息。整个过程涉及资源文件定义、Locale解析和消息获取三个核心环节，下面分别展开。
在实际项目中，国际化的难点往往不在于如何加载资源文件，而在于如何让接口返回结构、异常信息和业务提示统一接入多语言体系。如果只是零散地在Controller里手动调用MessageSource，代码很快就会变得臃肿且难以维护。更好的做法是把消息获取逻辑封装成工具类，结合全局异常处理器和统一响应类，让业务代码几乎感知不到国际化的存在。下面先从基础配置开始，逐步构建完整方案。
一、核心组件与基础配置
Spring Boot对国际化提供了自动配置，项目只要引入了spring-boot-starter-web依赖，容器中就会自动注册一个MessageSource实例。默认情况下它会扫描classpath根目录下的messages资源文件，但实际开发中通常会自定义扫描路径和编码方式。通过application.yml中的spring.messages前缀可以轻松完成这些配置。
spring:
messages:
basename: i18n/messages
encoding: UTF-8
cache-duration: 3600
fallback-to-system-locale: false
use-code-as-default-message: true
basename指定了资源文件的路径和基础名称，这里设置为i18n/messages意味着Spring会在classpath下的i18n目录中查找messages.properties、messages_en_US.properties等文件。encoding设为UTF-8可以保证中文文案不会乱码。cache-duration用来控制资源文件内容的缓存时间，开发阶段可以调小甚至设为0，方便修改后立即生效。use-code-as-default-message为true时，如果某个消息code在资源文件中不存在，MessageSource会直接返回code本身而不是抛出异常，这对接口调试十分友好。
接下来创建资源文件。在src/main/resources/i18n目录下新增默认资源文件和英文资源文件，内容示例如下：
user.notfound=用户不存在 user.save.success=用户保存成功
user.notfound=User not found user.save.success=User saved successfully
默认的messages.properties会作为兜底资源，当请求的语言没有对应资源文件时，Spring会回退到这个文件。例如用户请求语言为日语，但项目中没有messages_ja_JP.properties，最终就会使用messages.properties中的中文或默认文案。这种机制能避免因缺少某语言资源而导致整个接口报错。
光有资源文件还不够，应用必须知道当前请求应该使用哪个Locale。Spring提供了LocaleResolver接口来完成这一任务。Spring Boot默认使用AcceptHeaderLocaleResolver，它会读取请求头Accept-Language来决定Locale。但这种方式的缺点是客户端无法灵活地通过参数切换语言，而且服务端也不能保存用户偏好。更常用的做法是使用SessionLocaleResolver配合LocaleChangeInterceptor，让前端通过一个简单的请求参数切换语言。
@Configuration
public class I18nConfig implements WebMvcConfigurer {
@Bean
public LocaleResolver localeResolver() {
SessionLocaleResolver resolver = new SessionLocaleResolver();
resolver.setDefaultLocale(Locale.SIMPLIFIED_CHINESE);
return resolver;
}
@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
LocaleChangeInterceptor interceptor = new LocaleChangeInterceptor();
interceptor.setParamName("lang");
return interceptor;
}
@Override
public void addInterceptors(InterceptorRegistry registry) {
registry.addInterceptor(localeChangeInterceptor());
}
}
上面的配置中，SessionLocaleResolver将语言信息保存在HTTP Session里，默认语言设为简体中文。LocaleChangeInterceptor会拦截所有请求，并检查参数中是否包含名为lang的值。如果存在，就调用LocaleResolver的setLocale方法更新当前会话的语言。这样前端只需要在请求URL上追加?lang=en即可切换到英文。拦截器必须通过WebMvcConfigurer注册到Spring MVC的拦截器链中，否则不会生效。
二、统一响应结构与全局异常国际化
真实项目里接口返回通常不会只是简单字符串，而是包含code、message和data的统一结构。如果每次都手动在Controller中获取消息，代码会非常重复。我们可以将MessageSource封装成静态工具类，并借助LocaleContextHolder自动获取当前请求的Locale。
@Component
public class MessageUtils {
private static MessageSource messageSource;
public MessageUtils(MessageSource messageSource) {
MessageUtils.messageSource = messageSource;
}
public static String get(String code, Object... args) {
Locale locale = LocaleContextHolder.getLocale();
return messageSource.getMessage(code, args, locale);
}
}
LocaleContextHolder是Spring提供的一个基于ThreadLocal的容器，它保存了当前请求对应的Locale。只要在同一个线程内，无论方法层级多深，都可以通过它拿到正确的语言信息。因此我们不必在方法参数中层层传递Locale，工具类会自动适配当前请求。静态注入MessageSource的方式虽然方便，但要注意Spring的Bean初始化顺序，确保在使用前容器已经完成注入。
有了工具类，统一响应类就可以这样设计：
public class ApiResponse<T> {
private int code;
private String message;
private T data;
public static <T> ApiResponse<T> success(T data) {
ApiResponse<T> response = new ApiResponse<>();
response.code = 200;
response.message = MessageUtils.get("common.success");
response.data = data;
return response;
}
public static ApiResponse<Void> error(int code, String message) {
ApiResponse<Void> response = new ApiResponse<>();
response.code = code;
response.message = message;
return response;
}
}
业务异常同样可以接入国际化。定义统一的BusinessException，它携带消息code和可选参数。全局异常处理器捕获异常后，通过MessageUtils将code解析成对应语言的文案，再封装成ApiResponse返回给前端。
@RestControllerAdvice
public class GlobalExceptionHandler {
@ExceptionHandler(BusinessException.class)
public ApiResponse<Void> handleBusinessException(BusinessException e) {
String message = MessageUtils.get(e.getCode(), e.getArgs());
return ApiResponse.error(e.getHttpStatus(), message);
}
}
这样所有业务异常、校验异常、系统异常都可以通过统一的出口输出国际化消息。开发人员只需要在抛出异常时指定消息code，无需关心当前语言是什么。例如一个用户不存在异常可以这样抛出：throw new BusinessException("user.notfound", userId)。如果资源文件内容为user.notfound=用户ID {0} 不存在，那么最终返回给中文用户的消息就是“用户ID 123 不存在”，英文用户则会看到“User ID 123 not found”。
三、Locale解析策略与关键细节
LocaleResolver的选择直接影响用户体验和接口行为。Spring内置了多种实现，各有适用场景。AcceptHeaderLocaleResolver完全依赖浏览器的语言设置，对移动端或非浏览器客户端不够友好，而且切换参数无法改变解析结果。SessionLocaleResolver将语言保存在服务端Session中，适合传统Web应用，但会占用服务器内存。CookieLocaleResolver把语言信息写入客户端Cookie，即使服务端重启也能保持用户偏好，很适合需要长期记住语言选择的场景。选择哪种方案需要根据实际业务来确定，必要时也可以自定义LocaleResolver。
资源文件编码是一个容易被忽略的坑。properties文件在Java标准库中默认按ISO-8859-1读取，如果直接用UTF-8保存中文内容，在老旧环境下可能读到乱码。Spring Boot提供了spring.messages.encoding配置项，但前提是文件本身必须确实是UTF-8编码。IDE中如果设置不当，保存时可能以GBK或其他编码写入文件，最终导致乱码。建议团队统一IDE和构建工具的编码为UTF-8，并在CI流程中加入资源文件的编码检查。
消息模板使用java.text.MessageFormat格式，支持{0}、{1}等占位符。需要注意单引号在MessageFormat中是转义字符，如果文案本身需要显示单引号，必须写成两个单引号。例如消息内容为请不要删除用户{0}的数据，这里没有单引号所以无需处理。但如果想表达“用户{0}的‘默认’地址”，就要写成“用户{0}的‘’默认‘’地址”，否则格式解析会出错。为了避免维护困难，建议消息文案中尽量少用或不用单引号，或者对特殊符号做统一约定。
fallback-to-system-locale和use-code-as-default-message这两个配置也值得关注。前者控制当找不到当前Locale对应的资源时是否回退到系统默认Locale，如果设为false，Spring会直接回退到默认资源文件而不是系统Locale。后者允许在消息code缺失时返回code本身，这样前端至少能获得有意义的标识，比直接抛出NoSuchMessageException要友好得多。在微服务或多语言资源未补齐的情况下，这两个配置能显著降低故障率。
四、接口验证与最佳实践
完成配置后可以通过简单的HTTP请求验证国际化效果。假设有一个查询用户详情的接口，路径为/api/users/{id}，启动应用后分别使用不同的lang参数请求：
curl "http://localhost:8080/api/users/123?lang=en"
如果返回的message字段是英文，说明LocaleChangeInterceptor已经生效。去掉lang参数或使用?lang=zh_CN，应该返回默认中文。如果发现切换参数无效，首先检查自定义的LocaleResolver是否覆盖了默认的AcceptHeaderLocaleResolver，其次确认拦截器是否被正确注册，以及拦截路径是否匹配。
最后给出几条实践建议。第一，消息code尽量使用模块前缀加业务含义，例如user.notfound、order.status.invalid，避免过短的code导致冲突。第二，资源文件按照语言和地区拆分，但不要拆分得过细，通常messages.properties、messages_en.properties、messages_zh_CN.properties已经足够。第三，在测试环境中关闭资源文件缓存或设置较短的cache-duration，方便修改后立即验证。第四，将国际化消息的单元测试纳入持续集成，确保每种语言至少覆盖核心错误码。第五，如果项目需要支持多语言数据库内容，应另行设计字段级别或表级别的多语言存储方案，本文的i18n机制只适用于系统提示、错误信息和枚举标签等静态或半静态文案。
Spring Booti18n接口国际化修改时间：2026-08-29 22:20:29