Spring Sleuth 在 SOAP 客户端调用中传播自定义追踪字段的策略

1. Spring Sleuth 的自动传播机制

spring cloud sleuth 旨在为 spring 应用程序提供分布式追踪能力，通过集成 openzipkin brave 实现。它能够自动将追踪上下文（trace id、span id、sampled 状态）以及配置的自定义行李字段（baggage fields）传播到下游服务，从而构建完整的调用链。

Sleuth 提供了对多种主流 HTTP 客户端的开箱即用支持，包括：

• RestTemplate: Spring 提供的同步 HTTP 客户端。
• WebClient: Spring WebFlux 提供的响应式 HTTP 客户端。
• Feign: 声明式 REST 客户端，广泛用于微服务间调用。

当应用程序使用这些客户端发起外部调用时，Sleuth 会自动拦截请求，并将 X-B3-TraceId、X-B3-SpanId、X-B3-Sampled 等标准追踪头以及在 sleuth.baggage.remote-fields 中配置的自定义字段（例如 Caller-Id）注入到 HTTP 请求头中。

示例 Sleuth 配置：

spring:
  sleuth:
    async:
      enabled: true # 启用异步操作的追踪上下文传播
    baggage:
      remote-fields: # 定义需要远程传播的自定义字段
        - Caller-Id

对于 RESTful 调用，如使用 Feign 客户端，上述配置能够确保 Caller-Id 等自定义字段被正确传播：

Request headers: {Accept=[application/json], X-B3-TraceId=[...], X-B3-SpanId=[...], X-B3-Sampled=[1], caller-id=[value]}

2. SOAP 客户端面临的挑战

尽管 Sleuth 对 REST 客户端提供了强大的支持，但对于非标准或非主流的 HTTP 客户端，其自动传播机制可能不会生效。具体到 JAX-WS SOAP 客户端，特别是结合 jaxws-spring 库使用时，我们发现 Sleuth 无法自动将追踪上下文和自定义行李字段注入到 SOAP 调用的 HTTP 请求头中。

例如，一个典型的 SOAP 客户端调用，其 HTTP 头可能仅包含 Authorization 等基本信息，而缺少 Sleuth 相关的追踪头和自定义行李字段：

VWO

一个A/B测试工具

下载

SOAP Headers - {Authorization=[Bearer...]}

这是因为 jaxws-spring 及其底层使用的 HTTP 客户端（通常是 JDK 提供的 HttpURLConnection 或其他自定义实现）并未被 Sleuth 默认的自动配置所覆盖。因此，需要我们手动介入，在 SOAP 消息发送前，将 Sleuth 的追踪信息和行李字段注入到请求中。

3. 解决方案：通过 JAX-WS SOAP 处理器手动注入

为了解决 SOAP 客户端无法自动传播 Sleuth 追踪信息的问题，我们可以利用 JAX-WS 提供的 SOAPHandler 扩展点。SOAPHandler 允许我们在 SOAP 消息发送和接收的各个阶段进行拦截和修改。

3.1 实现自定义 SOAPHandler

我们需要创建一个实现了 javax.xml.ws.handler.soap.SOAPHandler 接口的类。在这个处理器中，我们将：

1. 获取当前的 Sleuth Tracer 实例。
2. 从 Tracer 中获取当前的追踪上下文（Trace ID 和 Span ID）。
3. 从 Baggage.current() 中获取所有活跃的自定义行李字段。
4. 将这些信息作为 HTTP 请求头注入到传出的 SOAP 消息中。

import org.springframework.cloud.sleuth.Tracer;
import org.springframework.cloud.sleuth.CurrentTraceContext;
import org.springframework.cloud.sleuth.Baggage; // 用于获取当前行李字段

import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;

import java.util.HashMap;
import java.util.List;
import java.util.Map;
import java.util.Collections;
import java.util.Set;
import javax.xml.namespace.QName;

/**
 * SleuthSoapClientHandler 是一个 JAX-WS SOAP 处理器，用于在出站 SOAP 消息中注入 Sleuth 追踪信息和自定义行李字段。
 */
public class SleuthSoapClientHandler implements SOAPHandler {

    private final Tracer tracer;

    /**
     * 构造函数，通过 Spring 注入 Tracer 实例。
     * @param tracer Spring Cloud Sleuth 的 Tracer 实例。
     */
    public SleuthSoapClientHandler(Tracer tracer) {
        this.tracer = tracer;
    }

    @Override
    public boolean handleMessage(SOAPMessageContext context) {
        // 判断消息是否是出站消息（即客户端发往服务端的请求）
        Boolean outboundProperty = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);

        if (outboundProperty != null && outboundProperty) { // 如果是出站消息
            // 获取或创建 HTTP 请求头 Map
            Map> httpHeaders = (Map>) context.get(MessageContext.HTTP_REQUEST_HEADERS);
            if (httpHeaders == null) {
                httpHeaders = new HashMap<>();
                context.put(MessageContext.HTTP_REQUEST_HEADERS, httpHeaders);
            }

            // 1. 注入 Sleuth 追踪 ID (X-B3-TraceId, X-B3-SpanId, X-B3-Sampled)
            CurrentTraceContext currentTraceContext = tracer.currentTraceContext();
            if (currentTraceContext != null && currentTraceContext.context() != null) {
                String traceId = currentTraceContext.context().traceId();
                String spanId = currentTraceContext.context().spanId();
                httpHeaders.put("X-B3-TraceId", Collections.singletonList(traceId));
                httpHeaders.put("X-B3-SpanId", Collections.singletonList(spanId));
                httpHeaders.put("X-B3-Sampled", Collections.singletonList("1")); // 假设已采样
            }

            // 2. 注入自定义行李字段 (Baggage Fields)
            // 遍历所有当前活跃的行李字段，并将其值作为 HTTP 头注入
            Baggage.current().getAllFields().forEach(baggageField -> {
                if (baggageField.value() != null) {
                    // Sleuth 行李字段通常以其名称作为 HTTP 头名称进行传播
                    httpHeaders.put(baggageField.name(), Collections.singletonList(baggageField.value()));
                }
            });
            // 如果只需要注入特定的行李字段，可以这样获取：
            // BaggageField callerIdField = Baggage.current().getBaggage("Caller-Id");
            // if (callerIdField != null && callerIdField.value() != null) {
            //     httpHeaders.put("Caller-Id", Collections.singletonList(callerIdField.value()));
            // }
        }
        return true; // 继续处理消息
    }

    @Override
    public boolean handleFault(SOAPMessageContext context) {
        // 处理故障消息（如果需要），这里简单返回 true
        return true;
    }

    @Override
    public void close(MessageContext context) {
        // 资源清理（如果需要）
    }

    @Override
    public Set getHeaders() {
        // 此处理器不处理特定的 SOAP 头，只处理 HTTP 头，因此返回 null
        return null;
    }
}

3.2 配置 SOAPHandler 到 JAX-WS 客户端

在使用 jaxws-spring 配置 SOAP 客户端时，可以通过 JaxWsPortProxyFactoryBean 的 handlers 属性来注册自定义的 SOAPHandler。

Java 配置示例：

import com.example.MyWebService; // 替换为你的 WebService 接口
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ClassPathResource;
import org.springframework.remoting.jaxws.JaxWsPortProxyFactoryBean;
import org.springframework.cloud.sleuth.Tracer;

import javax.xml.ws.handler.Handler;
import java.util.ArrayList;
import java.util.List;

@Configuration
public class SoapClientConfig {

    @Autowired
    private Tracer tracer; // Spring Boot 会自动注入 Sleuth 的 Tracer 实例

    @Bean
    public MyWebService myWebService() {
        JaxWsPortProxyFactoryBean factory = new JaxWsPortProxyFactoryBean();