微服务异步场景链路断裂完整解决方案

前置说明

在微服务链路追踪中同步 HTTP、OpenFeign、RestTemplate 调用，仅引入链路依赖就能自动透传 traceId/spanId；

但 @Async 异步方法、自定义线程池、定时任务、MQ跨进程通信会发生线程切换，ThreadLocal 上下文丢失，链路直接断裂。本文将详细讲解对应的解决方案。

一、Spring Boot2 + Sleuth 方案

场景1：使用Spring默认全局@Async线程池（未自定义Executor Bean）

Sleuth内置后置处理器 ExecutorBeanPostProcessor，会自动拦截容器内 ThreadPoolTaskExecutor 并包装链路上下文，无需手动编码、无需新增依赖，直接使用即可自动传递traceId。

场景2：自定义ThreadPoolTaskExecutor（@Bean声明）

不能依靠自动代理，必须手动包装线程池任务，两种写法任选其一：

写法1：包装线程池（推荐全局统一配置）

import brave.Tracer;
import brave.spring.beans.TraceableExecutorService;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import javax.annotation.Resource;
import java.util.concurrent.Executor;
import java.util.concurrent.ThreadPoolExecutor;

@Configuration
public class AsyncPoolConfig {

    @Resource
    private Tracer tracer;

    @Bean
    public Executor asyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(200);
        executor.setThreadNamePrefix("async-task-");
        executor.initialize();
        // Sleuth专属包装类，绑定链路上下文
        return new TraceableExecutorService(tracer, executor.getThreadPoolExecutor());
    }
}

写法2：单个Runnable手动包装（零散临时线程）

// 原始异步任务
Runnable task = () -> {
    // 业务逻辑
};
// 手动绑定当前链路上下文
Runnable traceTask = TraceableExecutorService.wrap(tracer, task);
executor.submit(traceTask);

场景3：new ThreadPoolExecutor 原生线程池（不归Spring容器管理）

Spring无法感知该线程池，自动代理失效，必须逐个包装提交的任务。

场景4：@Scheduled 定时任务

定时任务使用独立调度线程，默认丢失上下文，解决方案：

1. 少量定时任务：方法内手动捕获上下文再执行；
2. 全局定时任务池：参照场景2，给 ScheduledExecutor 用 TraceableExecutorService 包装。

场景5：RocketMQ/Kafka 消息队列跨进程

生产者、消费者分属两个独立应用，线程上下文天然隔离，任何线程池包装都无效：

1. 生产者拦截器：发送消息时，把 traceId、spanId 写入消息自定义Header；
2. 消费者拦截器：消费消息时，从Header取出链路ID，重建Trace上下文；
   该场景无法靠依赖自动处理，必须自定义拦截器。

二、Spring Boot3 + Micrometer Tracing

该版本无自动代理线程池的内置逻辑，所有异步场景都需要手动处理上下文快照。

核心API：ContextSnapshot 上下文快照，实现主线程上下文拷贝到子线程

场景1：全局统一@Async线程池配置（一次配置全局生效，最常用）

import io.micrometer.context.ContextSnapshot;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.scheduling.concurrent.ThreadPoolTaskExecutor;
import org.springframework.core.task.TaskDecorator;
import java.util.concurrent.Executor;

@EnableAsync
@Configuration
public class AsyncTraceConfig {

    @Bean("traceAsyncExecutor")
    public Executor traceAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(4);
        executor.setMaxPoolSize(8);

        // 任务装饰器：每次提交任务自动拷贝链路上下文
        TaskDecorator decorator = runnable -> () -> {
            // 捕获当前主线程全部上下文
            ContextSnapshot snapshot = ContextSnapshot.captureAll();
            try (ContextSnapshot.Scope scope = snapshot.setThreadLocals()) {
                runnable.run();
            }
        };
        executor.setTaskDecorator(decorator);
        executor.initialize();
        return executor;
    }
}

使用时指定线程池：@Async("traceAsyncExecutor")，所有异步方法自动续上链路。

场景2：零散临时Runnable、手动提交任务

@Autowired
private io.micrometer.tracing.Tracer tracer;

public void submitTask() {
    Runnable bizTask = () -> {
        // 异步业务代码
    };
    // 手动包装上下文
    ContextSnapshot snapshot = ContextSnapshot.captureAll();
    Runnable wrappedTask = () -> {
        try (ContextSnapshot.Scope scope = snapshot.setThreadLocals()) {
            bizTask.run();
        }
    };
    executor.submit(wrappedTask);
}

场景3：@Scheduled 定时任务

改造定时任务调度线程池，同样配置上面的 TaskDecorator 装饰器，快照传递上下文。

场景4：MQ跨进程收发

1. Spring官方MQ客户端（KafkaTemplate、RabbitTemplate）已原生适配W3C标准 traceparent 请求头，发送时自动写入Header，消费端自动解析恢复上下文，无需手写拦截器；
2. 自定义原生MQ生产者工具类，依旧需要手动读写消息Header传递traceId。