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 + 自定义线程池并行构建设备数据，其中涉及国际化调用：
java
MessageUtils.message("eco.enums.status.online")
该方法会根据请求头中的语言标识（中/英文）进行国际化转换。
**现象：**
- 中文环境：国际化正常 ✅
- 英文环境：国际化失效，始终返回中文 ❌
将多线程调用改为同步顺序调用后，中英文国际化均正常。
## 二、问题代码
### 异常代码（多线程版本）
``private List<SiteDeviceTypeDTO> buildDeviceTypeListInParallel(SiteDeviceMonitorSearch searchDTO, 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(new CompletableFuture[0])).join();
return futures.stream()
.map(CompletableFuture::join)
.filter(dto -> dto != null && CollectionUtil.isNotEmpty(dto.getDeviceList()))
.collect(Collectors.toList());
}
### 正常代码（同步版本）
```java
private List<SiteDeviceTypeDTO> buildDeviceTypeListInParallel(SiteDeviceMonitorSearch searchDTO, Map<String, String> typeNameMap) { return typeNameMap.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 来获取当前请求的语言环境：
java
// MessageUtils.message() 内部简化逻辑 public static String message(String code) { Locale locale = LocaleContextHolder.getLocale(); // 从 ThreadLocal 获取 return messageSource.getMessage(code, null, locale); }
`LocaleContextHolder` 的底层实现是 `ThreadLocal`：
```java
public abstract class LocaleContextHolder { private static final ThreadLocal<LocaleContext> localeContextHolder = new NamedThreadLocal<>("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，回退到默认值时恰好就是中文，造成了"中文正常"的假象。
四、解决方案
方案一：改为同步调用（最简单）
如果并发量不大、设备类型数量有限，直接使用同步方式：
java
private List<SiteDeviceTypeDTO> buildDeviceTypeList(SiteDeviceMonitorSearch searchDTO, Map<String, String> typeNameMap) { return typeNameMap.entrySet().stream() .map(entry -> buildSingleDeviceType(searchDTO, entry.getKey(), entry.getValue())) .filter(dto -> dto != null && CollectionUtil.isNotEmpty(dto.getDeviceList())) .collect(Collectors.toList()); }适用场景： 设备类型通常不超过 10 种，同步调用性能影响可接受。
方案二：手动传递 Locale 上下文到子线程
在提交异步任务前捕获当前 Locale，在子线程中手动设置：
java
private List<SiteDeviceTypeDTO> buildDeviceTypeListInParallel(SiteDeviceMonitorSearch searchDTO, Map<String, String> typeNameMap) { // 在主线程中捕获当前 Locale Locale currentLocale = LocaleContextHolder.getLocale();
List<CompletableFuture<SiteDeviceTypeDTO>> futures = typeNameMap.entrySet().stream()
.map(entry -> CompletableFuture.supplyAsync(() -> {
// 在子线程中设置 Locale
LocaleContextHolder.setLocale(currentLocale);
try {
return buildSingleDeviceType(searchDTO, entry.getKey(), entry.getValue());
} finally {
// 清理，避免线程复用时 Locale 污染
LocaleContextHolder.resetLocaleContext();
}
}, deviceMonitorExecutor))
.collect(Collectors.toList());
CompletableFuture.allOf(futures.toArray(new CompletableFuture[0])).join();
return futures.stream()
.map(CompletableFuture::join)
.filter(dto -> dto != null && CollectionUtil.isNotEmpty(dto.getDeviceList()))
.collect(Collectors.toList());
}方案三：使用 TaskDecorator 装饰线程池（推荐用于 Spring 环境）
自定义一个上下文传递的装饰器：
java
public class ContextCopyingDecorator implements TaskDecorator { @Override public Runnable decorate(Runnable runnable) { // 捕获提交任务时的上下文 Locale locale = LocaleContextHolder.getLocale(); RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();
return () -> {
try {
LocaleContextHolder.setLocale(locale);
RequestContextHolder.setRequestAttributes(requestAttributes);
runnable.run();
} finally {
LocaleContextHolder.resetLocaleContext();
RequestContextHolder.resetRequestAttributes();
}
};
}
}配合 ThreadPoolTaskExecutor 使用：
java
@Bean public ThreadPoolTaskExecutor deviceMonitorExecutor() { ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor(); executor.setCorePoolSize(5); executor.setMaxPoolSize(10); executor.setQueueCapacity(100); executor.setThreadNamePrefix("site-device-monitor-"); executor.setTaskDecorator(new ContextCopyingDecorator()); // 关键！ executor.initialize(); return executor; }五、方案对比
| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 同步调用 | 简单可靠，无上下文问题 | 串行执行，性能稍差 | 任务量少、对延迟不敏感 |
| 手动传递 Locale | 改动小，精准控制 | 每处异步调用都需处理 | 少量异步调用点 |
| TaskDecorator | 统一管理，对业务无侵入 | 需改造线程池配置 | 大量异步调用场景 |
六、总结
| 维度 | 说明 |
|---|---|
| 根因 | CompletableFuture + 线程池导致 ThreadLocal 上下文（Locale）无法传递到子线程 |
| 表现 | 英文国际化失效，中文"正常"（实为默认回退值） |
| 本质 | Spring i18n 依赖 LocaleContextHolder（ThreadLocal），跨线程天然失效 |
| 类似问题 | RequestContextHolder、SecurityContextHolder、MDC 日志追踪等同类 ThreadLocal 场景 |
核心教训： 在 Spring 应用中使用多线程时，凡是依赖 ThreadLocal 存储的上下文信息（Locale、Request、Security、MDC 等），都需要显式传递到子线程，否则必然丢失。