Spring Cloud Sleuth配置：自定义关联ID复用TraceID及生成规则

1. 自定义TraceID提取规则（兼容自定义头与Sleuth默认头） #

Spring Cloud Sleuth 3.x底层依赖Brave框架，我们可以通过配置指定优先从自定义请求头my-correlation-id提取TraceID，同时保留Sleuth默认的链路头（如X-B3-TraceId）作为备选，无需编写大量业务代码。

配置文件实现（application.yml） #

在所有微服务的配置文件中添加以下配置：

spring:
  sleuth:
    propagation:
      type: B3
      extra-keys: my-correlation-id
    brave:
      propagation:
        trace-id-128: false # 不需要128位TraceID可设为false，默认是true
        keys:
          - my-correlation-id
          - X-B3-TraceId
          - X-B3-SpanId

配置说明：

• extra-keys：让Sleuth识别自定义链路头my-correlation-id，允许其在微服务间传播
• brave.propagation.keys：定义TraceID提取优先级，优先读取my-correlation-id，不存在则读取Sleuth默认的X-B3-TraceId
• 当请求头存在my-correlation-id时，Sleuth会直接将其作为TraceID使用，不会生成新ID

2. 自动返回新生成的TraceID到响应头 #

当请求未携带任何有效链路头时，Sleuth会自动生成新的TraceID，此时需要将该ID返回给前端，方便后续请求携带。我们可以通过自定义拦截器实现这一逻辑：

自定义拦截器代码 #

创建TraceIdResponseInterceptor类：

import org.springframework.cloud.sleuth.Tracer;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@Component
public class TraceIdResponseInterceptor implements HandlerInterceptor {

    private final Tracer tracer;

    public TraceIdResponseInterceptor(Tracer tracer) {
        this.tracer = tracer;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        // 检查请求是否携带有效链路头
        boolean hasValidCorrelationHeader = request.getHeader("my-correlation-id") != null 
                || request.getHeader("X-B3-TraceId") != null;
        
        if (!hasValidCorrelationHeader) {
            // 将生成的TraceID写入响应头，可选择自定义头或Sleuth默认头
            response.setHeader("my-correlation-id", tracer.currentSpan().context().traceIdString());
            // 若用默认头可替换为：response.setHeader("X-B3-TraceId", tracer.currentSpan().context().traceIdString());
        }
    }
}

注册拦截器 #

创建配置类完成拦截器注册：

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebMvcConfig implements WebMvcConfigurer {

    private final TraceIdResponseInterceptor traceIdResponseInterceptor;

    public WebMvcConfig(TraceIdResponseInterceptor traceIdResponseInterceptor) {
        this.traceIdResponseInterceptor = traceIdResponseInterceptor;
    }

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(traceIdResponseInterceptor).addPathPatterns("/**");
    }
}

逻辑说明：

• 拦截器在请求处理完成后检查请求头，若未携带有效链路ID，则将Sleuth自动生成的TraceID写入响应头
• 可根据前端需求选择返回自定义头my-correlation-id或Sleuth默认的X-B3-TraceId

3. 关于现成配置的说明 #

Sleuth本身没有直接实现“无链路头时返回TraceID到响应”的现成配置，但通过上述配置文件+自定义拦截器的组合，即可快速实现需求，且无需修改大量业务代码。

如果完全使用Sleuth自带的X-B3-TraceId和X-B3-SpanId头，可简化配置：仅保留spring.sleuth.propagation.type: B3即可，拦截器中只需检查X-B3-TraceId是否存在，不存在则返回该头。

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