Spring Boot 多线程场景下 i18n 国际化失效问题排查与解决

App 请求头带语言标识（如 Accept-Language: en）
Spring 拦截器将语言信息存入 LocaleContextHolder（底层是 ThreadLocal）
MessageUtils.message() 内部调用 LocaleContextHolder.getLocale() 获取当前语言环境
当使用 CompletableFuture.supplyAsync(…, deviceMonitorExecutor) 时，任务提交到线程池的工作线程执行
线程池工作线程不会继承请求线程的 ThreadLocal，因此 LocaleContextHolder.getLocale() 拿到的是系统默认 Locale（中文）
所以中文总能"正常"显示（因为是默认值），英文永远失效
改成同步调用后，代码在原始请求线程中执行，LocaleContextHolder 中有正确的 Locale，所以国际化正常。

Spring Boot 多线程场景下 i18n 国际化失效问题排查与解决

一、问题背景

在一个 Spring Boot 项目中，有一个提供给 App 的设备监控接口，调用方式为：

• 前端定时任务每分钟调用一次
• 用户操作时主动触发

接口内部使用CompletableFuture+ 自定义线程池并行构建设备数据，其中涉及国际化调用：

MessageUtils.message("eco.enums.status.online")该方法会根据请求头中的语言标识（中/英文）进行国际化转换。**现象：**-中文环境：国际化正常 ✅-英文环境：国际化失效，始终返回中文 ❌ 将多线程调用改为同步顺序调用后，中英文国际化均正常。 ## 二、问题代码 ### 异常代码（多线程版本） ``privateList<SiteDeviceTypeDTO>buildDeviceTypeListInParallel(SiteDeviceMonitorSearchsearchDTO,Map<String,String>typeNameMap){List<CompletableFuture<SiteDeviceTypeDTO>>futures=typeNameMap.entrySet().stream().map(entry->CompletableFuture.supplyAsync(()->buildSingleDeviceType(searchDTO,entry.getKey(),entry.getValue()),deviceMonitorExecutor))// 提交到自定义线程池 .collect(Collectors.toList());CompletableFuture.allOf(futures.toArray(newCompletableFuture[0])).join();returnfutures.stream().map(CompletableFuture::join).filter(dto->dto!=null&&CollectionUtil.isNotEmpty(dto.getDeviceList())).collect(Collectors.toList());}### 正常代码（同步版本） ```javaprivateList<SiteDeviceTypeDTO>buildDeviceTypeListInParallel(SiteDeviceMonitorSearchsearchDTO,Map<String,String>typeNameMap){returntypeNameMap.entrySet().stream().map(entry->buildSingleDeviceType(searchDTO,entry.getKey(),entry.getValue())).filter(dto->dto!=null&&CollectionUtil.isNotEmpty(dto.getDeviceList())).collect(Collectors.toList());}

三、根因分析

3.1 Spring 国际化的工作原理

Spring 的MessageSource国际化机制依赖LocaleContextHolder来获取当前请求的语言环境：

// MessageUtils.message() 内部简化逻辑 public static String message(String code) { Locale locale = LocaleContextHolder.getLocale(); // 从 ThreadLocal 获取 return messageSource.getMessage(code, null, locale); }`LocaleContextHolder` 的底层实现是 `ThreadLocal`： ```javapublicabstractclassLocaleContextHolder{privatestaticfinalThreadLocal<LocaleContext>localeContextHolder=newNamedThreadLocal<>("LocaleContext");// ... }

3.2 请求处理链路

App请求(Header: Accept-Language: en) ↓ DispatcherServlet / 拦截器 ↓ LocaleContextHolder.setLocale(Locale.ENGLISH) ← 设置到当前请求线程的 ThreadLocal ↓ Controller → Service → MessageUtils.message() ↓ LocaleContextHolder.getLocale() ← 从 ThreadLocal 读取

3.3 多线程场景下的断链

请求线程 (ThreadLocal: locale=en) ↓ CompletableFuture.supplyAsync(…, threadPoolExecutor) ↓ 线程池工作线程 (ThreadLocal: locale=null → 回退为系统默认 zh_CN) ↓ MessageUtils.message(“eco.enums.status.online”) ↓ LocaleContextHolder.getLocale() → Locale.CHINESE (默认值!) ↓ 返回中文 “在线” 而非英文 “Online”

关键点：ThreadLocal变量是线程隔离的，线程池中的工作线程不会自动继承提交任务的父线程的ThreadLocal值。

3.4 为什么中文"看似正常"

中文是系统默认语言（Locale.getDefault()或 Spring 配置的默认 Locale），即使LocaleContextHolder中没有设置正确的 Locale，回退到默认值时恰好就是中文，造成了"中文正常"的假象。

四、解决方案

方案一：改为同步调用（最简单）

如果并发量不大、设备类型数量有限，直接使用同步方式：

privateList<SiteDeviceTypeDTO>buildDeviceTypeList(SiteDeviceMonitorSearchsearchDTO,Map<String,String>typeNameMap){returntypeNameMap.entrySet().stream().map(entry->buildSingleDeviceType(searchDTO,entry.getKey(),entry.getValue())).filter(dto->dto!=null&&CollectionUtil.isNotEmpty(dto.getDeviceList())).collect(Collectors.toList());}

适用场景：设备类型通常不超过 10 种，同步调用性能影响可接受。

方案二：手动传递 Locale 上下文到子线程

在提交异步任务前捕获当前 Locale，在子线程中手动设置：

privateList<SiteDeviceTypeDTO>buildDeviceTypeListInParallel(SiteDeviceMonitorSearchsearchDTO,Map<String,String>typeNameMap){// 在主线程中捕获当前 Locale Locale currentLocale = LocaleContextHolder.getLocale();List<CompletableFuture<SiteDeviceTypeDTO>>futures=typeNameMap.entrySet().stream().map(entry->CompletableFuture.supplyAsync(()->{// 在子线程中设置 LocaleLocaleContextHolder.setLocale(currentLocale);try{returnbuildSingleDeviceType(searchDTO,entry.getKey(),entry.getValue());}finally{// 清理，避免线程复用时 Locale 污染LocaleContextHolder.resetLocaleContext();}},deviceMonitorExecutor)).collect(Collectors.toList());CompletableFuture.allOf(futures.toArray(newCompletableFuture[0])).join();returnfutures.stream().map(CompletableFuture::join).filter(dto->dto!=null&&CollectionUtil.isNotEmpty(dto.getDeviceList())).collect(Collectors.toList());}

方案三：使用 TaskDecorator 装饰线程池（推荐用于 Spring 环境）

自定义一个上下文传递的装饰器：

publicclassContextCopyingDecoratorimplementsTaskDecorator{@OverridepublicRunnabledecorate(Runnablerunnable){// 捕获提交任务时的上下文 Locale locale = LocaleContextHolder.getLocale(); RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();return()->{try{LocaleContextHolder.setLocale(locale);RequestContextHolder.setRequestAttributes(requestAttributes);runnable.run();}finally{LocaleContextHolder.resetLocaleContext();RequestContextHolder.resetRequestAttributes();}};}}

配合ThreadPoolTaskExecutor使用：

@BeanpublicThreadPoolTaskExecutordeviceMonitorExecutor(){ThreadPoolTaskExecutorexecutor=newThreadPoolTaskExecutor();executor.setCorePoolSize(5);executor.setMaxPoolSize(10);executor.setQueueCapacity(100);executor.setThreadNamePrefix("site-device-monitor-");executor.setTaskDecorator(newContextCopyingDecorator());// 关键！ executor.initialize(); return executor; }

五、方案对比

六、总结

核心教训：在 Spring 应用中使用多线程时，凡是依赖ThreadLocal存储的上下文信息（Locale、Request、Security、MDC 等），都需要显式传递到子线程，否则必然丢失。