1. 理解WSDL与Java类转换的必要性
在spring boot项目中集成第三方soap web服务时，通常会收到一个wsdl url或文件。wsdl是一种xml格式的语言，用于描述web服务的接口、操作、数据类型和网络位置。为了在java应用程序中调用这些服务，我们需要将wsdl中定义的复杂类型和操作转换为相应的java类。这些生成的java类充当了服务契约的本地表示，允许开发者以面向对象的方式调用远程soap服务，而无需直接处理底层的xml消息。
2. 常见挑战与解决方案
在WSDL到Java类的转换过程中，开发者可能会遇到一些常见问题。
2.1 wsimport工具的兼容性问题
wsimport是JDK自带的一个用于生成JAX-WS（Java API for XML Web Services）客户端代码的命令行工具。然而，自Java 11起，JAXB（Java Architecture for XML Binding）模块（java.xml.bind）已从JDK中移除，成为一个独立的库。这意味着，如果您使用Java 11或更高版本运行wsimport，可能会遇到“Unable to locate a Java Runtime that supports wsimport”或类似的错误。
解决方案：
- 降级JDK版本： 如果项目允许，可以使用Java 8等旧版本JDK来运行wsimport。
- 显式添加JAXB依赖： 对于Java 11+环境，需要为构建工具（如Maven或Gradle）添加JAXB运行时依赖，并在执行wsimport时确保这些依赖可用。然而，更推荐的做法是使用构建工具插件来自动化此过程。
2.2 IDE工具的局限性
某些集成开发环境（IDE），如Eclipse，提供了内置的Web服务工具来生成Java客户端。但有时这些选项可能缺失，即使安装了“Enterprise Java and Web Developers”等特定软件包也可能不显示。
解决方案：
- 确保安装了正确且完整的IDE版本，包含所有Web服务开发组件。
- 优先使用构建工具： 无论IDE是否提供此功能，将WSDL到Java的转换集成到项目的构建流程中（如Maven或Gradle）是更健壮和可维护的方法。这确保了团队成员之间的一致性，并在持续集成/持续部署（CI/CD）环境中实现自动化。
3. 使用构建工具自动化WSDL到Java的转换
将WSDL到Java的生成过程集成到Maven或Gradle构建生命周期中是最佳实践。这不仅解决了上述兼容性和IDE问题，还确保了代码生成的自动化和可重复性。
3.1 Maven配置示例
以Maven为例，我们可以使用jaxws-maven-plugin来处理WSDL文件并生成Java类。
-
将WSDL文件放入项目： 建议将WSDL文件放置在项目的特定目录下，例如src/main/resources/wsdl/。这样做有助于版本控制，并确保WSDL文件的可追溯性。
src/main/resources/wsdl/yourService.wsdl
-
配置pom.xml： 在项目的pom.xml文件中，添加jaxws-maven-plugin的配置。
4.0.0 org.springframework.boot spring-boot-starter-parent2.7.5 com.example soap-client-demo0.0.1-SNAPSHOT soap-client-demo Demo project for Spring Boot SOAP client 17 org.springframework.boot spring-boot-starter-web-servicescom.sun.xml.ws jaxws-rt2.3.5 jakarta.xml.bind jakarta.xml.bind-api2.3.3 com.sun.xml.bind jaxb-impl2.3.5 runtime org.springframework.boot spring-boot-maven-plugincom.sun.xml.ws jaxws-maven-plugin2.3.2 wsimport ${project.basedir}/src/main/resources/wsdl yourService.wsdl com.example.soap.client ${project.build.directory}/generated-sources/jaxws true true -
执行代码生成： 在项目根目录运行Maven命令：
mvn clean install
或者只生成源文件：
mvn generate-sources
执行后，生成的Java类将位于target/generated-sources/jaxws目录下（根据sourceDestDir配置），并被自动添加到项目的编译路径中。
3.2 Gradle配置（简述）
对于Gradle项目，可以使用com.github.bjornvester.wsdl2java或gradle-jaxb-plugin等插件实现类似的功能。核心思想是在build.gradle中配置插件，指定WSDL源和输出目录，然后在构建任务中执行代码生成。
4. 在Spring Boot中消费SOAP服务
一旦WSDL转换为Java类，我们就可以利用Spring Boot的WebServiceGatewaySupport来构建SOAP客户端。
4.1 创建SOAP客户端配置
首先，创建一个配置类来定义WebServiceTemplate bean。
package com.example.soap.config;
import com.example.soap.client.YourServiceClient; // 假设这是生成的客户端接口或类
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.oxm.jaxb.Jaxb2Marshaller;
import org.springframework.ws.client.core.WebServiceTemplate;
import org.springframework.ws.client.support.WebServiceGatewaySupport;
@Configuration
public class SoapClientConfig {
@Bean
public Jaxb2Marshaller marshaller() {
Jaxb2Marshaller marshaller = new Jaxb2Marshaller();
// 设置生成的Java类的包名
marshaller.setContextPath("com.example.soap.client"); // 与jaxws-maven-plugin配置的packageName一致
return marshaller;
}
@Bean
public YourServiceClient yourServiceClient(Jaxb2Marshaller marshaller) {
YourServiceClient client = new YourServiceClient();
client.setDefaultUri("http://compA.com/ws/server"); // 第三方SOAP服务的实际地址
client.setMarshaller(marshaller);
client.setUnmarshaller(marshaller);
return client;
}
}4.2 定义SOAP服务客户端
创建一个继承自WebServiceGatewaySupport的客户端类。
package com.example.soap.client; import org.springframework.ws.client.core.support.WebServiceGatewaySupport; import org.springframework.ws.soap.client.core.SoapActionCallback; // 假设WSDL生成了一个名为 'GetYourDataRequest' 和 'GetYourDataResponse' 的类 // 并且有一个名为 'YourServicePort' 的接口或类定义了服务操作 import com.example.soap.client.GetYourDataRequest; import com.example.soap.client.GetYourDataResponse; public class YourServiceClient extends WebServiceGatewaySupport { public GetYourDataResponse getYourData(String inputParameter) { GetYourDataRequest request = new GetYourDataRequest(); request.setInputField(inputParameter); // 根据实际生成的类设置请求参数 // 调用WebServiceTemplate发送请求 // "http://compA.com/ws/server/GetYourData" 替换为实际的SOAP Action URI // 或根据WSDL中的定义 GetYourDataResponse response = (GetYourDataResponse) getWebServiceTemplate() .marshalSendAndReceive( getDefaultUri(), request, new SoapActionCallback("http://compA.com/ws/server/GetYourData")); return response; } // 可以添加更多服务方法... }
cePort' 的接口或类定义了服务操作
import com.example.soap.client.GetYourDataRequest;
import com.example.soap.client.GetYourDataResponse;
public class YourServiceClient extends WebServiceGatewaySupport {
public GetYourDataResponse getYourData(String inputParameter) {
GetYourDataRequest request = new GetYourDataRequest();
request.setInputField(inputParameter); // 根据实际生成的类设置请求参数
// 调用WebServiceTemplate发送请求
// "http://compA.com/ws/server/GetYourData" 替换为实际的SOAP Action URI
// 或根据WSDL中的定义
GetYourDataResponse response = (GetYourDataResponse) getWebServiceTemplate()
.marshalSendAndReceive(
getDefaultUri(),
request,
new SoapActionCallback("http://compA.com/ws/server/GetYourData"));
return response;
}
// 可以添加更多服务方法...
}4.3 在应用程序中使用客户端
在您的Spring Boot组件（如Controller或Service）中注入并使用YourServiceClient。
package com.example.soap.service;
import com.example.soap.client.GetYourDataResponse;
import com.example.soap.client.YourServiceClient;
import org.springframework.stereotype.Service;
@Service
public class MyApplicationService {
private final YourServiceClient yourServiceClient;
public MyApplicationService(YourServiceClient yourServiceClient) {
this.yourServiceClient = yourServiceClient;
}
public String fetchDataFromSoapService(String query) {
GetYourDataResponse response = yourServiceClient.getYourData(query);
// 处理响应数据
return response.getOutputField(); // 假设响应有一个outputField
}
}5. 注意事项与最佳实践
- WSDL版本控制： 始终将WSDL文件纳入您的版本控制系统（如Git），并与项目代码一起管理。这有助于追踪WSDL的变更历史，并在需要时重新生成客户端代码。
- 自动化构建： 确保WSDL到Java的生成是构建过程的一部分。这样，任何新的克隆或CI/CD流水线都能自动生成必要的类，避免手动步骤和潜在错误。
- WSDL变更处理： 当第三方服务的WSDL发生变化时，您只需更新本地的WSDL文件，然后重新运行构建命令即可生成更新后的Java类。这简化了服务维护。
- 错误处理： 在SOAP客户端中实现适当的错误处理机制，例如捕获WebServiceIOException或其他SoapFault异常，以优雅地处理服务不可用或返回错误的情况。
- 安全性： 如果SOAP服务需要认证，您可能需要在WebServiceTemplate中配置拦截器来添加安全头部（如WS-Security）。
总结
将WSDL转换为Java类是Spring Boot项目集成SOAP Web服务的关键一步。通过采用Maven或Gradle等构建工具，我们可以克服wsimport兼容性及IDE工具缺失等常见挑战，实现WSDL到Java代码生成的自动化和标准化。结合Spring Boot的WebServiceGatewaySupport，开发者可以高效、可靠地构建和消费SOAP服务，从而顺利地与外部系统进行集成。遵循上述最佳实践，将确保您的SOAP客户端代码健壮、可维护且易于管理。
