快捷導(dǎo)航

Spring Boot開(kāi)啟虛擬線程ScopedValue上下文傳遞的使用方式

更新時(shí)間：2026年02月04日 15:59:07 作者：Demon_Hao

本文給大家介紹了ScopedValue在Java虛擬線程中的應(yīng)用,解決了傳統(tǒng)ThreadLocal在大量短生命周期線程場(chǎng)景下的問(wèn)題,本文結(jié)合實(shí)例代碼給大家介紹的非常詳細(xì),感興趣的朋友跟隨小編一起看看吧

1. 背景

在傳統(tǒng)的 Java 應(yīng)用中，ThreadLocal 常用于在同一線程中傳遞上下文信息（如請(qǐng)求ID、用戶(hù)信息等）。
然而，隨著 Java 虛擬線程（Virtual Thread） 的引入，線程數(shù)量可以非常大（成千上萬(wàn)），ThreadLocal 在這種場(chǎng)景下存在幾個(gè)問(wèn)題：

內(nèi)存泄漏風(fēng)險(xiǎn)：線程長(zhǎng)期存在時(shí)，ThreadLocal 變量容易被殘留引用占用。
上下文傳遞復(fù)雜：虛擬線程切換可能導(dǎo)致 ThreadLocal 值不一致，尤其在使用異步或掛起操作時(shí)。

為了解決這個(gè)問(wèn)題，Java 提供了 ScopedValue，用于在虛擬線程中安全、輕量地傳遞上下文。

2. ScopedValue 特點(diǎn)

輕量級(jí)：與 ThreadLocal 不同，它不會(huì)在每個(gè)線程上創(chuàng)建額外的存儲(chǔ)空間。
線程安全：值是不可變的，只能在創(chuàng)建的作用域內(nèi)訪問(wèn)。
自動(dòng)傳遞：在虛擬線程中創(chuàng)建作用域時(shí)，內(nèi)部邏輯可以自動(dòng)將上下文傳遞給掛起和恢復(fù)操作。
適合虛擬線程：與 ThreadLocal 相比，ScopedValue 更適合大量短生命周期線程的場(chǎng)景。

3. 使用方式

1、全局開(kāi)啟使用虛擬線程（yaml配置）

spring:
  main:
    # 保證 JVM 在全是虛擬線程情況下不會(huì)提前退出
    keep-alive: true
  # 全局虛擬線程開(kāi)關(guān)（推薦方式）
  threads:
    virtual:
      # 啟用虛擬線程，覆蓋 TaskExecutor、@Async、@Scheduled、Web Server
      enabled: true

2、虛擬線程上下文傳遞參數(shù)

import lombok.Builder;
/**
 * 虛擬線程上下文傳遞參數(shù)
 *
 * @param traceId  鏈路ID（分布式微服務(wù)傳遞追蹤）
 * @param userId   用戶(hù)ID
 * @param tenantId 租戶(hù)ID
 */
@Builder
public record RequestContext(
    String traceId,
    String userId,
    String tenantId) {
}

3、ScopedValue工具類(lèi)

import lombok.NoArgsConstructor;
/**
 * ScopedValue工具類(lèi)
 */
@NoArgsConstructor
public final class ContextKeys {
    // 鏈路ID
    public static final String TRACE_ID = "traceId";
    /**
     * WEB請(qǐng)求上下文傳遞
     */
    public static final ScopedValue<RequestContext> REQUEST_CONTEXT = ScopedValue.newInstance();
}

4、獲取上下文業(yè)務(wù)參數(shù)

import lombok.NoArgsConstructor;
import org.slf4j.MDC;
import java.util.Optional;
import java.util.concurrent.Callable;
/**
 * 獲取上下文業(yè)務(wù)參數(shù)
 */
@NoArgsConstructor
public final class RequestContextHolder {
    /**
     * 獲取完整上下文
     */
    public static Optional<RequestContext> getOptional() {
        return ContextKeys.REQUEST_CONTEXT.isBound() ? Optional.of(ContextKeys.REQUEST_CONTEXT.get()) : Optional.empty();
    }
    /**
     * 獲取 traceId
     */
    public static String getTraceId() {
        return getOptional().map(RequestContext::traceId).orElse(null);
    }
    /**
     * 獲取 userId
     */
    public static String getUserId() {
        return getOptional().map(RequestContext::userId).orElse(null);
    }
    /**
     * 獲取 tenantId
     */
    public static String getTenantId() {
        return getOptional().map(RequestContext::tenantId).orElse(null);
    }
    /**
     * 綁定上下文并運(yùn)行 Runnable
     */
    public static void with(RequestContext ctx, Runnable task) {
        ScopedValue.where(ContextKeys.REQUEST_CONTEXT, ctx).run(() -> {
            try {
                // MDC橋接
                MDC.put(ContextKeys.TRACE_ID, ctx.traceId());
                task.run();
            } finally {
                MDC.clear();
            }
        });
    }
    /**
     * 綁定上下文并運(yùn)行 Callable
     */
    public static <T> T with(RequestContext ctx, Callable<T> task) throws Exception {
        return ScopedValue.where(ContextKeys.REQUEST_CONTEXT, ctx).call(() -> {
            try {
                // MDC橋接
                MDC.put(ContextKeys.TRACE_ID, ctx.traceId());
                return task.call();
            } finally {
                MDC.clear();
            }
        });
    }
}

5、HTTP請(qǐng)求上下文初始化

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.jetbrains.annotations.NotNull;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;
import java.io.IOException;
import java.util.Optional;
import java.util.UUID;
/**
 * HTTP請(qǐng)求上下文初始化
 */
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)
public class ContextInitFilter extends OncePerRequestFilter {
    @Override
    protected void doFilterInternal(@NotNull HttpServletRequest request, @NotNull HttpServletResponse response, @NotNull FilterChain filterChain) throws ServletException, IOException {
        RequestContext ctx = buildContext(request);
        // ScopedValue 綁定上下文
        try {
            ScopedValue.where(ContextKeys.REQUEST_CONTEXT, ctx).run(() -> {
                try {
                    // MDC橋接
                    MDC.put(ContextKeys.TRACE_ID, ctx.traceId());
                    filterChain.doFilter(request, response);
                } catch (IOException | ServletException e) {
                    throw new RuntimeException(e);
                } finally {
                    MDC.clear();
                }
            });
        } catch (RuntimeException e) {
            // 拆包，保持Servlet語(yǔ)義
            if (e.getCause() instanceof IOException io) throw io;
            if (e.getCause() instanceof ServletException se) throw se;
            throw e;
        }
    }
    /**
     * 構(gòu)建請(qǐng)求上下文
     */
    private RequestContext buildContext(HttpServletRequest request) {
        // 鏈路ID
        String traceId = Optional.ofNullable(request.getHeader("X-Trace-Id")).orElse(UUID.randomUUID().toString());
        // 用戶(hù)ID
        String userId = request.getHeader("X-User-Id");
        // 租戶(hù)ID
        String tenantId = request.getHeader("X-Tenant-Id");
        return RequestContext.builder().traceId(traceId).userId(userId).tenantId(tenantId).build();
    }
}

6、ScopedValue和StructuredTaskScope使用方式

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
@RestController
public class DemoController {
    @GetMapping("/test")
    public String test() {
        // 獲取參數(shù)
        String tenantId = RequestContextHolder.getTenantId();
        String userId = RequestContextHolder.getUserId();
        // 新虛擬線程執(zhí)行
        RequestContext ctx = RequestContextHolder.getOptional().orElseThrow();
        ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
        executor.submit(() -> {
            RequestContextHolder.with(ctx, () -> {
                // 異步任務(wù)中依然可以獲取 traceId / userId
                System.out.println("traceId=" + RequestContextHolder.getTraceId());
            });
        });
        return "tenantId=" + tenantId + ", userId=" + userId;
    }
    /**
     * StructuredTaskScope實(shí)現(xiàn)：同步寫(xiě)法 + 并發(fā)執(zhí)行 + 自動(dòng)失敗傳播
     * 非常類(lèi)似WebFlux/Reactor的：Mono.zip(callA(), callB()).map(tuple -> combine(tuple.getT1(), tuple.getT2()));
     */
    @Transactional
    public void service() {
        try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
            var a = scope.fork(this::taskA);
            var b = scope.fork(this::taskB);
            // 等待所有
            scope.join();
            // 有失敗就拋
            scope.throwIfFailed();
            return combine(a.get(), b.get());
        }
    }
}

到此這篇關(guān)于Spring Boot開(kāi)啟虛擬線程ScopedValue上下文傳遞的文章就介紹到這了,更多相關(guān)Spring Boot開(kāi)啟虛擬線程內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章希望大家以后多多支持腳本之家！

您可能感興趣的文章: