SpringSleuth追踪SOAP服务：原理与集成教程

Spring Sleuth作为Spring Cloud生态的关键组件，为分布式系统提供强大的链路追踪能力，助力开发者诊断性能瓶颈与定位错误。Sleuth能够自动支持RestTemplate、WebClient和Feign等常用HTTP客户端，实现追踪ID的自动传播。然而，对于SOAP服务，由于其底层HTTP客户端的差异，Sleuth无法直接开箱即用。本文深入剖析Spring Sleuth的工作原理及其在SOAP服务追踪上的局限性，并提供一份详尽的指南，指导开发者如何通过JAX-WS客户端拦截器手动集成Sleuth，从而实现对SOAP调用的完整追踪。通过本文，您将掌握为SOAP服务添加分布式追踪能力的关键技术，确保整个分布式系统的可观测性。

本教程深入探讨Spring Sleuth在分布式追踪中的应用，特别指出其对RestTemplate、WebClient和Feign的自动支持。针对SOAP服务，由于底层HTTP客户端差异，Sleuth无法开箱即用传播追踪上下文。文章将详细阐述其工作原理、限制，并提供通过JAX-WS客户端拦截器手动集成Sleuth以实现SOAP调用追踪的专业指导。

理解Spring Sleuth的追踪机制

Spring Sleuth是Spring Cloud生态系统中的一个组件，旨在为分布式系统提供链路追踪能力。它通过在服务间传递追踪ID（Trace ID）和跨度ID（Span ID）来关联请求，从而帮助开发者理解请求流、诊断性能问题和定位错误。Sleuth的开箱即用功能主要依赖于对常见HTTP客户端库的自动配置和增强，例如：

• RestTemplate: Spring框架提供的同步HTTP客户端。
• WebClient: Spring WebFlux提供的响应式HTTP客户端。
• Feign: Netflix开发的声明式HTTP客户端，常用于微服务间的REST调用。

当应用程序使用这些客户端发起HTTP请求时，Sleuth会自动拦截请求，从当前追踪上下文中提取Trace ID、Span ID、采样状态（Sampled）以及配置的自定义行李字段（Baggage fields，如Caller-Id），并将它们作为HTTP请求头（通常是X-B3-TraceId, X-B3-SpanId, X-B3-Sampled等）注入到传出的请求中。接收方服务如果也集成了Sleuth，则会自动解析这些头部，并继续追踪链。

SOAP服务追踪的挑战与限制

尽管Sleuth对RESTful服务（特别是通过Feign、RestTemplate等发起的）提供了无缝的追踪能力，但对于SOAP服务，情况则有所不同。问题在于SOAP服务通常不直接使用上述Sleuth自动支持的HTTP客户端。例如，当使用jaxws-spring这样的库来集成JAX-WS（Java API for XML Web Services）时，底层用于发起SOAP调用的HTTP客户端可能不是Sleuth默认集成的那些。JAX-WS的实现（如Apache CXF、Metro）会使用自己的底层HTTP传输机制，例如Java内置的HttpURLConnection或配置的Apache HttpClient等。

由于Sleuth无法识别并自动增强这些特定的SOAP底层HTTP客户端，因此它无法将追踪上下文（包括X-B3-*头部和自定义行李字段）自动注入到SOAP请求的HTTP头部中。这就是为什么在REST调用中Caller-Id等字段能够成功传播，而在SOAP调用中却缺失的原因。

手动集成Sleuth与JAX-WS/SOAP服务

为了解决SOAP服务追踪的问题，我们需要进行手动集成。这通常涉及在JAX-WS客户端的请求处理链中插入自定义的拦截器（或称为处理器/Handler），在该拦截器中手动获取当前的Sleuth追踪上下文，并将其注入到SOAP请求的HTTP头部中。

1. 引入必要的依赖

确保项目中包含Spring Sleuth和JAX-WS相关的依赖。

<dependency>
    <groupId>org.springframework.cloud</groupId>
    <artifactId>spring-cloud-starter-sleuth</artifactId>
</dependency>
<dependency>
    <groupId>com.revinate</groupId>
    <artifactId>jaxws-spring</artifactId>
    <version>1.0.0</version>
</dependency>
<!-- 如果底层使用CXF，可能还需要CXF相关依赖 -->
<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-frontend-jaxws</artifactId>
    <version>${cxf.version}</version>
</dependency>
<dependency>
    <groupId>org.apache.cxf</groupId>
    <artifactId>cxf-rt-transports-http</artifactId>
    <version>${cxf.version}</version>
</dependency>

2. 创建JAX-WS客户端处理器（Handler）

我们需要实现javax.xml.ws.handler.soap.SOAPHandler接口，在handleMessage方法中处理出站消息。

import brave.Span;
import brave.Tracer;
import brave.propagation.Propagation;
import brave.propagation.TraceContext;
import brave.propagation.TraceContext.Injector;
import brave.propagation.TraceContext.Extractor;
import brave.http.HttpTracing;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Component;

import javax.xml.namespace.QName;
import javax.xml.ws.handler.MessageContext;
import javax.xml.ws.handler.soap.SOAPHandler;
import javax.xml.ws.handler.soap.SOAPMessageContext;
import java.util.Collections;
import java.util.HashSet;
import java.util.Map;
import java.util.Set;
import java.util.HashMap;

@Component
public class SleuthSoapClientHandler implements SOAPHandler<SOAPMessageContext> {

    private final Tracer tracer;
    private final Propagation.Setter<Map<String, String>, String> headerSetter;
    private final Propagation.Getter<Map<String, String>, String> headerGetter; // 尽管是出站，但为了完整性可以考虑

    // 构造函数注入Tracer和HeaderSetter
    @Autowired
    public SleuthSoapClientHandler(Tracer tracer, HttpTracing httpTracing) {
        this.tracer = tracer;
        // 使用B3TextMapPropagation的Setter来注入B3头部
        // 对于自定义行李字段，需要单独处理或使用BaggagePropagation
        this.headerSetter = httpTracing.propagation().injector(Map::put);
        this.headerGetter = httpTracing.propagation().extractor(Map::get); // 示例，通常出站不需要getter
    }

    @Override
    public boolean handleMessage(SOAPMessageContext context) {
        Boolean outboundProperty = (Boolean) context.get(MessageContext.MESSAGE_OUTBOUND_PROPERTY);

        if (outboundProperty) { // 仅处理出站消息
            Span currentSpan = tracer.currentSpan();
            if (currentSpan == null) {
                // 如果没有当前Span，则可能是一个新的调用链的开始，或者不在Sleuth追踪的线程中
                // 此时可以选择创建一个新的Span，或者不注入任何头部
                // 为了与现有追踪链保持一致，我们通常只在有当前Span时注入
                return true;
            }

            // 获取当前HTTP请求头部
            Map<String, Object> requestHeaders = (Map<String, Object>) context.get(MessageContext.HTTP_REQUEST_HEADERS);
            if (requestHeaders == null) {
                requestHeaders = new HashMap<>();
                context.put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
            }

            // 将Sleuth追踪上下文注入到HTTP头部中
            Map<String, String> stringHeaders = new HashMap<>();
            headerSetter.inject(currentSpan.context(), stringHeaders);

            // 将stringHeaders转换并添加到实际的requestHeaders中
            stringHeaders.forEach((key, value) -> {
                // JAX-WS的HTTP_REQUEST_HEADERS通常期望List<String>作为值
                requestHeaders.put(key, Collections.singletonList(value));
            });

            // 额外处理自定义行李字段（如Caller-Id）
            // Sleuth的Baggage API提供了获取和设置行李字段的方法
            String callerId = tracer.currentSpan().context().findBaggage("Caller-Id");
            if (callerId != null && !callerId.isEmpty()) {
                requestHeaders.put("Caller-Id", Collections.singletonList(callerId));
            }

            // 更新消息上下文中的HTTP请求头部
            context.put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);
            context.setScope(MessageContext.HTTP_REQUEST_HEADERS, MessageContext.Scope.APPLICATION);
        }
        return true;
    }

    @Override
    public boolean handleFault(SOAPMessageContext context) {
        return true;
    }

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

    @Override
    public Set<QName> getHeaders() {
        // 返回此处理器感兴趣的SOAP Header，通常为空，因为我们处理的是HTTP Header
        return new HashSet<>();
    }
}

注意事项：

• headerSetter.inject(currentSpan.context(), stringHeaders); 会将Sleuth默认的追踪头部（如X-B3-TraceId, X-B3-SpanId, X-B3-Sampled等）注入到stringHeaders中。
• 对于自定义行李字段（如Caller-Id），需要通过tracer.currentSpan().context().findBaggage("Caller-Id")显式获取，然后手动添加到HTTP头部。
• MessageContext.HTTP_REQUEST_HEADERS通常期望Map>作为头部集合。在上述示例中，为了简化，我们将其转换为Map并使用Collections.singletonList(value)来封装单个值。如果需要处理多值头部，则需要更复杂的转换。

3. 配置JAX-WS客户端以使用处理器

有两种常见的方式来配置JAX-WS客户端使用这个自定义处理器：

a) 通过Spring配置（如果使用jaxws-spring）

在你的Spring配置中，为SOAP客户端代理工厂添加处理器链。

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import javax.xml.ws.BindingProvider;
import javax.xml.ws.handler.Handler;
import java.util.ArrayList;
import java.util.List;

@Configuration
public class SoapClientConfig {

    @Autowired
    private SleuthSoapClientHandler sleuthSoapClientHandler;

    @Bean
    public MySoapService mySoapService() {
        // 假设MySoapService是你的SOAP服务接口
        // 这是获取SOAP服务代理的一个示例，具体方式取决于你的jaxws-spring配置
        // 可能是通过FactoryBean或者直接的JaxWsPortProxyFactoryBean
        MySoapService service = new MySoapServiceService().getMySoapServicePort();

        if (service instanceof BindingProvider) {
            BindingProvider bp = (BindingProvider) service;
            List<Handler> handlerChain = new ArrayList<>();
            handlerChain.add(sleuthSoapClientHandler);
            bp.getBinding().setHandlerChain(handlerChain);
        }
        return service;
    }

    // 如果你使用JaxWsPortProxyFactoryBean，配置会更直接
    // @Bean
    // public JaxWsPortProxyFactoryBean mySoapServiceProxy() {
    //     JaxWsPortProxyFactoryBean factory = new JaxWsPortProxyFactoryBean();
    //     factory.setServiceName("MySoapServiceService");
    //     factory.setPortName("MySoapServicePort");
    //     factory.setServiceInterface(MySoapService.class);
    //     factory.setWsdlDocumentUrl("classpath:wsdl/MySoapService.wsdl");
    //     // 设置处理器链
    //     factory.setHandlerChain(Collections.singletonList(sleuthSoapClientHandler));
    //     return factory;
    // }
}

b) 通过代码直接设置（如果手动创建客户端）

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

// ...
public class MyClient {

    @Autowired
    private SleuthSoapClientHandler sleuthSoapClientHandler;

    public void callSoapService() {
        MySoapServiceService serviceLocator = new MySoapServiceService();
        MySoapService mySoapService = serviceLocator.getMySoapServicePort();

        if (mySoapService instanceof BindingProvider) {
            BindingProvider bp = (BindingProvider) mySoapService;
            List<Handler> handlerChain = new ArrayList<>();
            handlerChain.add(sleuthSoapClientHandler);
            bp.getBinding().setHandlerChain(handlerChain);
        }

        // 现在可以调用SOAP服务了
        // mySoapService.someOperation();
    }
}

总结

Spring Sleuth为分布式系统提供了强大的链路追踪能力，但其开箱即用的自动传播功能主要针对RestTemplate、WebClient和Feign等主流HTTP客户端。对于SOAP服务，由于其底层HTTP客户端实现机制的差异，Sleuth无法直接进行集成。

要实现SOAP服务的分布式追踪，开发者需要通过JAX-WS提供的客户端处理器（Handler）机制进行手动集成。核心步骤是创建一个自定义的SOAP处理器，在其中获取当前的Sleuth追踪上下文（包括Trace ID、Span ID和自定义行李字段），并将其作为HTTP头部手动注入到出站的SOAP请求中。通过这种方式，即使是SOAP服务调用，也能无缝地融入到整个分布式追踪链中，从而保持完整的可观测性。

以上就是本文的全部内容了，是否有顺利帮助你解决问题？若是能给你带来学习上的帮助，请大家多多支持golang学习网！更多关于文章的相关知识，也可关注golang学习网公众号。