Java虚拟线程中Logging MDC的使用及请求ID串扰问题解决

问题根源 #

传统日志MDC基于ThreadLocal存储上下文，但Java 21的虚拟线程（Virtual Thread）在IO等待时会被挂起，对应的平台线程会被JVM分配给其他虚拟线程复用。此时旧的MDC上下文会留在平台线程中，导致新虚拟线程的日志错误携带上一个请求的ID，出现日志串号问题。

解决方案 #

1. 升级日志框架到支持虚拟线程的版本 #

主流日志框架已针对虚拟线程做了适配，MDC上下文会自动绑定到虚拟线程而非平台线程，无需修改业务代码：

• Logback：升级到**1.4.0+**版本
• Log4j2：升级到**2.20.0+**版本

升级后原有的过滤器代码和日志配置可以完全复用，日志框架会自动处理虚拟线程的上下文传递。

2. 使用Java 21 ScopedValue传递请求上下文 #

如果无法升级日志框架，可利用Java 21新增的ScopedValue（专为虚拟线程设计的上下文传递机制）来替代ThreadLocal存储请求ID，确保上下文跟随虚拟线程：

步骤1：定义全局ScopedValue

public class RequestContext {
    // 定义用于存储请求ID的ScopedValue
    public static final ScopedValue<String> REQUEST_ID = ScopedValue.newInstance();
}

步骤2：修改过滤器代码

在过滤器中用ScopedValue.runWhere()绑定请求ID，同时兼容原有MDC设置：

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
    String requestId = UUID.randomUUID().toString();
    HttpServletResponse httpServletResponse = (HttpServletResponse) response;
    httpServletResponse.setHeader("requestId", requestId);

    // 绑定ScopedValue，确保虚拟线程切换时上下文跟随
    ScopedValue.runWhere(RequestContext.REQUEST_ID, requestId, () -> {
        try {
            // 兼容原有MDC使用方式
            MDC.put("requestId", requestId);
            chain.doFilter(request, response);
        } finally {
            MDC.remove("requestId");
        }
    });
}

步骤3：自定义MDC适配器（以Logback为例）

让日志框架从ScopedValue中读取请求ID，替代原有的ThreadLocal读取逻辑：

import ch.qos.logback.classic.spi.MDCAdapter;
import java.util.Map;

public class ScopedValueMdcAdapter implements MDCAdapter {
    private final MDCAdapter delegate = new ch.qos.logback.classic.util.LogbackMDCAdapter();

    @Override
    public void put(String key, String value) {
        delegate.put(key, value);
    }

    @Override
    public String get(String key) {
        // 优先从ScopedValue读取请求ID
        if ("requestId".equals(key) && RequestContext.REQUEST_ID.isBound()) {
            return RequestContext.REQUEST_ID.get();
        }
        return delegate.get(key);
    }

    @Override
    public void remove(String key) {
        delegate.remove(key);
    }

    @Override
    public void clear() {
        delegate.clear();
    }

    @Override
    public Map<String, String> getCopyOfContextMap() {
        return delegate.getCopyOfContextMap();
    }

    @Override
    public void setContextMap(Map<String, String> contextMap) {
        delegate.setContextMap(contextMap);
    }
}

步骤4：配置Logback使用自定义适配器

在logback.xml中指定自定义MDC适配器：

<configuration>
    <!-- 配置自定义MDC适配器 -->
    <mdcAdapter class="com.yourpackage.ScopedValueMdcAdapter"/>

    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <Pattern>%d %-5level %X{requestId} [%t] %C{10}:%L %m%n</Pattern>
        </encoder>
    </appender>

    <root level="info">
        <appender-ref ref="CONSOLE"/>
    </root>
</configuration>

3. 手动清理恢复MDC上下文（临时兼容方案） #

此方案需在虚拟线程执行前后手动保存、恢复平台线程的MDC上下文，适合临时应急，但代码侵入性强，易出错：

// 示例：在虚拟线程任务中手动处理MDC
ExecutorService virtualThreadPool = Executors.newVirtualThreadPerTaskExecutor();
virtualThreadPool.submit(() -> {
    // 保存平台线程原有MDC快照
    Map<String, String> originalMdc = MDC.getCopyOfContextMap();
    try {
        // 设置当前请求的MDC上下文
        MDC.put("requestId", currentRequestId);
        // 执行业务逻辑
        businessService.handleRequest();
    } finally {
        // 恢复平台线程原有MDC上下文
        if (originalMdc != null) {
            MDC.setContextMap(originalMdc);
        } else {
            MDC.clear();
        }
    }
});

总结 #

优先选择升级日志框架的方案，这是最简洁可靠的解决方式；若无法升级，推荐使用ScopedValue实现上下文传递；手动清理恢复方案仅作为临时兼容手段，不建议长期使用。

内容的提问来源于stack exchange，提问作者ReactionTime