多线程环境下微信会话上下文隔离的 ThreadLocal 陷阱与替代方案

ThreadLocal 在微信上下文中的典型用法

在对接企业微信或公众号时，常需在请求链路中传递租户标识（corpId）、用户身份（userId）等上下文信息。开发者常使用 ThreadLocal 存储：

package wlkankan.cn.context;

public class WeComContext {
    private static final ThreadLocal<ContextData> CONTEXT_HOLDER = new ThreadLocal<>();

    public static void set(String corpId, String userId) {
        CONTEXT_HOLDER.set(new ContextData(corpId, userId));
    }

    public static ContextData get() {
        return CONTEXT_HOLDER.get();
    }

    public static void clear() {
        CONTEXT_HOLDER.remove();
    }

    public static class ContextData {
        private final String corpId;
        private final String userId;
        public ContextData(String corpId, String userId) {
            this.corpId = corpId;
            this.userId = userId;
        }
        // getters
    }
}

在 Spring Web 请求中，通过拦截器设置并清理：

@Component
public class WeComContextInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        String corpId = request.getHeader("X-Corp-ID");
        String userId = request.getHeader("X-User-ID");
        WeComContext.set(corpId, userId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        WeComContext.clear(); // 防止内存泄漏
    }
}

ThreadLocal 在异步/线程池中的失效问题

当业务逻辑使用 @Async、CompletableFuture 或线程池时，子线程无法继承父线程的 ThreadLocal 值：

@Service
public class MessageService {

    @Async
    public void sendAsyncMessage(String content) {
        // 此处 WeComContext.get() 返回 null！
        ContextData ctx = WeComContext.get();
        if (ctx == null) {
            throw new IllegalStateException("Context lost in async thread");
        }
        wlkankan.cn.wecom.WecomClient.sendMessage(ctx.corpId(), ctx.userId(), content);
    }
}

根本原因：ThreadLocal 是线程私有存储，新线程的 ThreadLocalMap 为空。

方案一：显式传递上下文参数（推荐）

最安全的方式是将上下文作为方法参数显式传递：

@Async
public void sendAsyncMessage(String corpId, String userId, String content) {
    wlkankan.cn.wecom.WecomClient.sendMessage(corpId, userId, content);
}

// 调用处
ContextData ctx = WeComContext.get();
messageService.sendAsyncMessage(ctx.corpId(), ctx.userId(), "Hello");

优点：无隐式依赖，线程安全，可测试性强。

方案二：使用 InheritableThreadLocal（有限适用）

InheritableThreadLocal 允许子线程在创建时继承父线程的值，但仅对 new Thread() 有效，对线程池无效：

private static final InheritableThreadLocal<ContextData> CONTEXT_HOLDER = new InheritableThreadLocal<>();

线程池复用线程，后续任务不会重新继承。若强行使用，会导致上下文污染（前一个租户的 corpId 被后一个请求误用）。

方案三：封装支持上下文传递的线程池（TransmittableThreadLocal）

阿里开源的 TransmittableThreadLocal（TTL） 可解决线程池场景：

<!-- Maven -->
<dependency>
    <groupId>com.alibaba</groupId>
    <artifactId>transmittable-thread-local</artifactId>
    <version>2.14.3</version>
</dependency>

改造上下文类：

import com.alibaba.ttl.TransmittableThreadLocal;

public class WeComContext {
    private static final TransmittableThreadLocal<ContextData> CONTEXT_HOLDER = new TransmittableThreadLocal<>();

    // set/get/clear 方法不变
}

关键：必须使用 TTL 提供的线程池装饰器：

@Configuration
public class AsyncConfig {

    @Bean("contextAwareTaskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(4);
        executor.initialize();

        // 使用 TTL 包装
        return com.alibaba.ttl.TtlExecutors.getTtlExecutor(executor);
    }
}

或手动包装 Runnable：

CompletableFuture<Void> future = CompletableFuture.runAsync(
    () -> {
        // 此时 WeComContext.get() 可正确获取
        ContextData ctx = WeComContext.get();
        wlkankan.cn.wecom.WecomClient.sendMessage(ctx.corpId(), ctx.userId(), "Hi");
    },
    TtlExecutors.getTtlExecutor(Executors.newFixedThreadPool(2))
);

方案四：Reactor/WebFlux 中的 Context（响应式编程）

若使用 Project Reactor，应使用 Context 而非 ThreadLocal：

return Mono.deferContextual(ctxView -> {
    String corpId = ctxView.get("corpId");
    String userId = ctxView.get("userId");
    return wlkankan.cn.wecom.WecomClient.sendReactiveMessage(corpId, userId, content);
}).contextWrite(Context.of("corpId", corpId).put("userId", userId));

内存泄漏防护

即使使用 ThreadLocal，也必须在请求结束时调用 clear()。在 Web 场景中，可通过 try-finally 或 Spring 的 afterCompletion 保证。在线程池中，TTL 自动在任务执行前后做 copy 和 restore，避免跨任务污染。

// TTL 内部机制示意（无需手动实现）
Runnable wrapped = () -> {
    Object backup = copy();
    try {
        original.run();
    } finally {
        restore(backup);
    }
};

综上，在多线程微信服务开发中，优先显式传参；若需隐式上下文，必须使用 TransmittableThreadLocal 并正确包装线程池，严禁直接使用普通 ThreadLocal 或 InheritableThreadLocal。