Spring Boot微服务间API与事件中自定义关联ID自动传递方案

核心选型：Spring Cloud Sleuth / Micrometer Tracing #

这是Spring生态下解决分布式链路追踪的原生方案，能自动完成关联ID（Trace ID）的全链路传递，不用手写大量重复的拦截器代码。如果是Spring Boot 3.x版本，优先用Micrometer Tracing（官方主推的Sleuth替代方案，兼容OpenTelemetry、Zipkin等生态）；2.x版本直接用Spring Cloud Sleuth即可。

基础配置步骤 #

1. 引入依赖 #

• Spring Boot 2.x + Sleuth：

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>

• Spring Boot 3.x + Micrometer Tracing：

<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-tracing-bridge-brave</artifactId>
</dependency>
<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-zipkin</artifactId> <!-- 可选，用于链路可视化 -->
</dependency>

2. 自动传递逻辑 #

Sleuth/Micrometer Tracing会自动处理以下场景：

• 微服务X生成Trace ID后，调用微服务Y的API时，RestTemplate/FeignClient会自动把当前线程的Trace ID塞进请求头（默认头名X-B3-TraceId，可自定义）。
• 微服务Y接收到请求后，会自动从请求头提取Trace ID并绑定到当前线程上下文，后续Y调用Z或发送事件时，会自动把这个ID传递下去。
• 要是用RabbitMQ、Kafka这类消息队列发事件，组件也会自动把Trace ID注入消息头，消费端自动提取绑定，实现异步链路的ID传递。

自定义关联ID扩展 #

如果不想用默认的Trace ID格式（比如要加业务前缀），可以自定义生成器：

@Configuration
public class CustomTraceIdConfig {
    @Bean
    public TraceIdGenerator customTraceIdGenerator() {
        return () -> "BUS-" + UUID.randomUUID().toString().replace("-", "");
    }
}

同时可以在配置文件里修改请求头名称：

spring:
  sleuth:
    propagation:
      header:
        name: X-CUSTOM-CORRELATION-ID # 换成你的自定义头名

非HTTP场景补充（自定义事件总线） #

如果用的是自己实现的事件发送逻辑，不是Spring Cloud Stream这类原生支持的组件，需要手动从上下文取ID再塞到消息头：

// 发送端：获取当前关联ID
String correlationId = Tracing.currentTracer().currentSpan().context().traceId();
// 把ID放进消息头（以Kafka为例）
ProducerRecord<String, String> record = new ProducerRecord<>("event-topic", "message-content");
record.headers().add("X-CUSTOM-CORRELATION-ID", correlationId.getBytes(StandardCharsets.UTF_8));

// 消费端：提取ID并绑定到上下文
String correlationId = new String(record.headers().lastHeader("X-CUSTOM-CORRELATION-ID").value(), StandardCharsets.UTF_8);
Span span = Tracing.currentTracer().nextSpan().name("event-consumer").start();
try (Tracer.SpanInScope scope = Tracing.currentTracer().withSpanInScope(span)) {
    // 处理消息逻辑，此时上下文已绑定关联ID
} finally {
    span.end();
}

为什么这是最优方案？ #

• 原生集成省代码：不用自己写全局请求拦截器处理ID的提取和传递，减少重复代码和潜在bug。
• 全场景覆盖：支持HTTP、消息队列、异步线程等所有流程节点，保证ID不丢失。
• 可观测性升级：配合Zipkin就能实现全链路追踪，排查问题更高效。
• 灵活定制：支持自定义ID格式和请求头，满足业务个性化需求。

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