使用 Spring 构建 SOAP Web Service

最后修改:2025年3月26日

by baeldung

1. 概述

本教程将带你使用 Spring Boot Starter Web Services 构建一个 基于 SOAP 的 Web 服务。

2. SOAP Web 服务简介

简单来说，Web 服务是一种平台无关、机器与机器之间通信的协议，常用于跨网络的数据交换。

SOAP 是一种消息协议，请求和响应都是 基于 HTTP 的 XML 文档。XML 的结构由 WSDL（Web Services Description Language）定义，它规定了消息格式、绑定方式、操作接口和 Web 服务的地址。

由于 SOAP 中使用的 XML 结构可能非常复杂，因此推荐使用如 JAX-WS 或 Spring 这样的框架来简化开发，本文将重点介绍 Spring 的方式。

3. 契约优先开发模式

创建 Web 服务有两种方式：契约最后（Contract-Last）和 契约优先（Contract-First）。

  • 契约最后：先写 Java 代码，再生成 WSDL。
  • 契约优先：先定义 WSDL 契约，再生成 Java 类。

Spring-WS 只支持契约优先的开发方式。

4. 配置 Spring Boot 项目

我们将在 Spring Boot 项目中构建一个 SOAP Web Service 服务端。

4.1. 添加 Maven 依赖

首先，添加 spring-boot-starter-parent：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
</parent>

然后添加 spring-boot-starter-web-services 和 *wsdl4j 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web-services</artifactId>
</dependency>
<dependency>
    <groupId>wsdl4j</groupId>
    <artifactId>wsdl4j</artifactId>
</dependency>

4.2. 编写 XSD 文件

契约优先要求我们先定义服务的结构（方法与参数）。我们通过一个 XML Schema 文件（XSD）来定义，并由 Spring-WS 自动导出为 WSDL：

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://www.baeldung.com/springsoap/gen"
           targetNamespace="http://www.baeldung.com/springsoap/gen" elementFormDefault="qualified">

    <xs:element name="getCountryRequest">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="name" type="xs:string"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:element name="getCountryResponse">
        <xs:complexType>
            <xs:sequence>
                <xs:element name="country" type="tns:country"/>
            </xs:sequence>
        </xs:complexType>
    </xs:element>

    <xs:complexType name="country">
        <xs:sequence>
            <xs:element name="name" type="xs:string"/>
            <xs:element name="population" type="xs:int"/>
            <xs:element name="capital" type="xs:string"/>
            <xs:element name="currency" type="tns:currency"/>
        </xs:sequence>
    </xs:complexType>

    <xs:simpleType name="currency">
        <xs:restriction base="xs:string">
            <xs:enumeration value="GBP"/>
            <xs:enumeration value="EUR"/>
            <xs:enumeration value="PLN"/>
        </xs:restriction>
    </xs:simpleType>
</xs:schema>

在这个文件中，我们可以看到：

  • getCountryRequest 接收一个 name 字符串参数；
  • getCountryResponse 返回一个 country 对象；
  • country 对象中包含 currency 类型，是一个枚举。

4.3. 生成 Java 类

我们将使用 jaxb2-maven-plugin 插件，通过 XJC 工具在构建时自动生成 Java 类。

在 pom.xml 中配置插件：

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxb2-maven-plugin</artifactId>
    <version>3.1.0</version>
    <executions>
        <execution>
            <id>xjc</id>
            <goals>
                <goal>xjc</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <sources>
            <source>src/main/resources/countries.xsd</source>
        </sources>
        <outputDirectory>src/main/java</outputDirectory>
        <clearOutputDir>false</clearOutputDir>
    </configuration>
</plugin>

两个关键配置：

  • <source>：XSD 文件路径；
  • <outputDirectory>：生成 Java 类的路径。

运行以下命令即可自动生成：

mvn compile

4.4. 创建 SOAP 接口（Endpoint）

接口类负责处理所有请求、执行业务逻辑并返回响应。

首先创建一个 CountryRepository 用于提供数据：

@Component
public class CountryRepository {

    private static final Map<String, Country> countries = new HashMap<>();

    @PostConstruct
    public void initData() {
        // initialize countries map
    }

    public Country findCountry(String name) {
        return countries.get(name);
    }
}

接着定义接口：

@Endpoint
public class CountryEndpoint {

    private static final String NAMESPACE_URI = "http://www.baeldung.com/springsoap/gen";

    private CountryRepository countryRepository;

    @Autowired
    public CountryEndpoint(CountryRepository countryRepository) {
        this.countryRepository = countryRepository;
    }

    @PayloadRoot(namespace = NAMESPACE_URI, localPart = "getCountryRequest")
    @ResponsePayload
    public GetCountryResponse getCountry(@RequestPayload GetCountryRequest request) {
        GetCountryResponse response = new GetCountryResponse();
        response.setCountry(countryRepository.findCountry(request.getName()));

        return response;
    }
}

关键注解说明：

  • @Endpoint：注册为 Web Service 接口；
  • @PayloadRoot：根据 namespace 和 localPart 匹配请求；
  • @ResponsePayload：返回值将映射为响应体；
  • @RequestPayload：参数将从请求体中映射。

4.5. 配置 Web Service Bean

创建 WebServiceConfig 类，继承 WsConfigurerAdapter 并启用 SOAP 支持：

@EnableWs
@Configuration
public class WebServiceConfig extends WsConfigurerAdapter {
    // bean definitions
}

配置 MessageDispatcherServlet 用于处理 SOAP 请求：

@Bean
public ServletRegistrationBean<MessageDispatcherServlet> messageDispatcherServlet(ApplicationContext applicationContext) {
    MessageDispatcherServlet servlet = new MessageDispatcherServlet();
    servlet.setApplicationContext(applicationContext);
    servlet.setTransformWsdlLocations(true);
    return new ServletRegistrationBean<>(servlet, "/ws/*");
}

配置 DefaultWsdl11Definition 来暴露 WSDL：

@Bean(name = "countries")
public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema countriesSchema) {
    DefaultWsdl11Definition wsdl11Definition = new DefaultWsdl11Definition();
    wsdl11Definition.setPortTypeName("CountriesPort");
    wsdl11Definition.setLocationUri("/ws");
    wsdl11Definition.setTargetNamespace("http://www.baeldung.com/springsoap/gen");
    wsdl11Definition.setSchema(countriesSchema);
    return wsdl11Definition;
}

@Bean
public XsdSchema countriesSchema() {
    return new SimpleXsdSchema(new ClassPathResource("countries.xsd"));
}

5. 测试 SOAP 服务

5.1. 构建并运行项目

使用 Spring Boot 启动应用：

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

运行项目：

mvn spring-boot:run

访问 WSDL 地址验证是否成功：

http://localhost:8080/ws/countries.wsdl

5.2. 发送 SOAP 请求

创建 request.xml 请求文件：

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:gs="http://www.baeldung.com/springsoap/gen">
    <soapenv:Header/>
    <soapenv:Body>
        <gs:getCountryRequest>
            <gs:name>Spain</gs:name>
        </gs:getCountryRequest>
    </soapenv:Body>
</soapenv:Envelope>

使用 curl 发送请求：

curl --header "content-type: text/xml" -d @request.xml http://localhost:8080/ws

格式化输出（如果安装了 xmllib2）：

curl [command-line-options] | xmllint --format -

响应示例：

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
    <ns2:getCountryResponse xmlns:ns2="http://www.baeldung.com/springsoap/gen">
        <ns2:country>
            <ns2:name>Spain</ns2:name>
            <ns2:population>46704314</ns2:population>
            <ns2:capital>Madrid</ns2:capital>
            <ns2:currency>EUR</ns2:currency>
        </ns2:country>
    </ns2:getCountryResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

6. 总结

本文展示了如何使用 Spring Boot 构建一个 SOAP Web Service，包括：

✅ 使用 XSD 文件定义契约
✅ 自动生成 Java 类
✅ 配置 SOAP 接口和 Spring Bean
✅ 测试服务请求与响应

完整源码见 GitHub。

原始标题:Creating a SOAP Web Service with Spring | Baeldung

« 上一篇： 如何测试 @Scheduled 注解
» 下一篇： Hibernate 聚合函数详解