構建soap服務 · springboot官方文檔中文版

# 產生SOAP Web服務本指南將引導您完成使用Spring創建基于SOAP的Web服務服務器的過程。 ## 你會建立什么您將使用基于WSDL的SOAP Web服務來構建一個服務器，以暴露來自歐洲各個國家的數據。為了簡化示例，您將使用英國，西班牙和波蘭的硬編碼數據。 ## 你需要什么 * 約15分鐘 * 最喜歡的文本編輯器或IDE * [JDK 1.8](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 或更高版本 * [Gradle 4+](http://www.gradle.org/downloads) 或 [Maven 3.2+](https://maven.apache.org/download.cgi) * 您還可以將代碼直接導入到IDE中： * [彈簧工具套件（STS）](https://spring.io/guides/gs/sts) * [IntelliJ IDEA](https://spring.io/guides/gs/intellij-idea/) ## 如何完成本指南像大多數Spring 一樣 [入門指南](https://spring.io/guides) ，您可以從頭開始并完成每個步驟，也可以繞過您已經熟悉的基本設置步驟。無論哪種方式，您最終都可以使用代碼。要 **從頭開始** ，請繼續進行“ [從Spring Initializr開始”](https://spring.io/guides/gs/producing-web-service/#scratch) 。要 **跳過基礎知識** ，請執行以下操作： * [下載](https://github.com/spring-guides/gs-soap-service/archive/master.zip) 并解壓縮本指南的源存儲庫，或使用對其進行克隆 [Git](https://spring.io/understanding/Git) ： `git clone [https://github.com/spring-guides/gs-soap-service.git](https://github.com/spring-guides/gs-soap-service.git)` * 光盤進入 `gs-soap-service/initial` * 繼續 [添加Spring-WS依賴項](https://spring.io/guides/gs/producing-web-service/#initial) 。 **完成后** ，您可以根據中的代碼檢查結果 `gs-soap-service/complete`. ## 從Spring Initializr開始如果您使用Maven，請訪問 [Spring Initializr](https://start.spring.io/#!type=maven-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=producing-web-service&name=producing-web-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.producing-web-service&dependencies=web,web-services) 以生成具有所需依賴項的新項目（Spring Web和Spring Web Services）。以下清單顯示了 `pom.xml` 選擇Maven時創建的文件： ~~~ <?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <parent> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-parent</artifactId> <version>2.4.3</version> <relativePath/>  </parent> <groupId>com.example</groupId> <artifactId>producing-web-service</artifactId> <version>0.0.1-SNAPSHOT</version> <name>producing-web-service</name> <description>Demo project for Spring Boot</description> <properties> <java.version>1.8</java.version> </properties> <dependencies> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-web-services</artifactId> </dependency> <dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-starter-test</artifactId> <scope>test</scope> </dependency> </dependencies> <build> <plugins> <plugin> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-maven-plugin</artifactId> </plugin> </plugins> </build> </project> ~~~ 如果使用Gradle，請訪問 [Spring Initializr](https://start.spring.io/#!type=gradle-project&language=java&platformVersion=2.4.3.RELEASE&packaging=jar&jvmVersion=1.8&groupId=com.example&artifactId=producing-web-service&name=producing-web-service&description=Demo%20project%20for%20Spring%20Boot&packageName=com.example.producing-web-service&dependencies=web,web-services) 以生成具有所需依賴項的新項目（Spring Web和Spring Web Services）。以下清單顯示了 `build.gradle` 選擇Gradle時創建的文件： ~~~ plugins { id 'org.springframework.boot' version '2.4.3' id 'io.spring.dependency-management' version '1.0.11.RELEASE' id 'java' } group = 'com.example' version = '0.0.1-SNAPSHOT' sourceCompatibility = '1.8' repositories { mavenCentral() } dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.boot:spring-boot-starter-web-services' testImplementation('org.springframework.boot:spring-boot-starter-test') } test { useJUnitPlatform() } ~~~ ### 手動初始化（可選）如果要手動初始化項目而不是使用前面顯示的鏈接，請按照以下步驟操作： 1. 導航到 [https://start.spring.io](https://start.spring.io) 。該服務提取應用程序所需的所有依賴關系，并為您完成大部分設置。 2. 選擇Gradle或Maven以及您要使用的語言。本指南假定您選擇了Java。 3. 單擊 **Dependencies，** 然后選擇 **Spring Web** 和 **Spring Web Services** 。 4. 點擊 **生成** 。 5. 下載生成的ZIP文件，該文件是使用您的選擇配置的Web應用程序的存檔。如果您的IDE集成了Spring Initializr，則可以從IDE中完成此過程。這倆 pom.xml 和 build.gradle 文件顯示其他構建信息，您將在下一步中添加這些信息。 ## 添加Spring-WS依賴項該項目需要包括 `spring-ws-core` 和 `wsdl4j` 作為構建文件中的依賴項。以下示例顯示了您需要對 `pom.xml` 如果使用Maven，則文件： ~~~ <dependency> <groupId>wsdl4j</groupId> <artifactId>wsdl4j</artifactId> </dependency> ~~~ 以下示例顯示了您需要對 `build.gradle` 文件，如果您使用Gradle： ~~~ dependencies { implementation 'org.springframework.boot:spring-boot-starter-web' implementation 'org.springframework.boot:spring-boot-starter-web-services' implementation 'wsdl4j:wsdl4j' jaxb("org.glassfish.jaxb:jaxb-xjc") testImplementation('org.springframework.boot:spring-boot-starter-test') } ~~~ ## 創建XML模式以定義域 Web服務域是在XML模式文件（XSD）中定義的，Spring-WS將自動將其導出為WSDL。使用操作返回一個國家/地區的操作來創建XSD文件 `name`, `population`, `capital`，和 `currency`。以下清單（來自 `src/main/resources/countries.xsd`）顯示必要的XSD文件： ~~~ <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:tns="http://spring.io/guides/gs-producing-web-service" targetNamespace="http://spring.io/guides/gs-producing-web-service" 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> ~~~ ## 基于XML模式生成域類下一步是從XSD文件生成Java類。正確的方法是在構建期間使用Maven或Gradle插件自動執行此操作。以下清單顯示了Maven所需的插件配置： ~~~ <plugin> <groupId>org.codehaus.mojo</groupId> <artifactId>jaxb2-maven-plugin</artifactId> <version>2.5.0</version> <executions> <execution> <id>xjc</id> <goals> <goal>xjc</goal> </goals> </execution> </executions> <configuration> <sources> <source>${project.basedir}/src/main/resources/countries.xsd</source> </sources> </configuration> </plugin> ~~~ 生成的類放在 `target/generated-sources/jaxb/` 目錄。要對Gradle進行同樣的操作，首先需要在構建文件中配置JAXB，如以下清單所示： ~~~ configurations { jaxb } bootJar { archiveBaseName = 'gs-producing-web-service' archiveVersion = '0.1.0' } ~~~ 生成文件有 tag 和 end注釋。這些標簽可以更輕松地將其提取到本指南中，以進行更詳細的說明。您不需要在自己的構建文件中使用這些注釋。下一步是添加 `genJaxb`任務，Gradle用來生成Java類。我們需要配置gradle以在以下位置找到這些生成的Java類 `build/generated-sources/jaxb` 并添加 `genJaxb` 作為...的依賴 `compileJava`任務。以下清單顯示了必要的添加： ~~~ sourceSets { main { java { srcDir 'src/main/java' srcDir 'build/generated-sources/jaxb' } } } task genJaxb { ext.sourcesDir = "${buildDir}/generated-sources/jaxb" ext.schema = "src/main/resources/countries.xsd" outputs.dir sourcesDir doLast() { project.ant { taskdef name: "xjc", classname: "com.sun.tools.xjc.XJCTask", classpath: configurations.jaxb.asPath mkdir(dir: sourcesDir) xjc(destdir: sourcesDir, schema: schema) { arg(value: "-wsdl") produces(dir: sourcesDir, includes: "**/*.java") } } } } compileJava.dependsOn genJaxb ~~~ 因為Gradle還沒有JAXB插件，所以它涉及到Ant任務，這使其比Maven更加復雜。在這兩種情況下，JAXB域對象的生成過程都已連接到構建工具的生命周期中，因此沒有多余的步驟可運行。 ## 創建國家/地區信息庫為了向Web服務提供數據，請創建國家/地區存儲庫。在本指南中，您將使用硬編碼數據創建虛擬國家/地區存儲庫實現。以下清單（來自 `src/main/java/com/example/producingwebservice/CountryRepository.java`）顯示了如何執行此操作： ~~~ package com.example.producingwebservice; import javax.annotation.PostConstruct; import java.util.HashMap; import java.util.Map; import io.spring.guides.gs_producing_web_service.Country; import io.spring.guides.gs_producing_web_service.Currency; import org.springframework.stereotype.Component; import org.springframework.util.Assert; @Component public class CountryRepository { private static final Map<String, Country> countries = new HashMap<>(); @PostConstruct public void initData() { Country spain = new Country(); spain.setName("Spain"); spain.setCapital("Madrid"); spain.setCurrency(Currency.EUR); spain.setPopulation(46704314); countries.put(spain.getName(), spain); Country poland = new Country(); poland.setName("Poland"); poland.setCapital("Warsaw"); poland.setCurrency(Currency.PLN); poland.setPopulation(38186860); countries.put(poland.getName(), poland); Country uk = new Country(); uk.setName("United Kingdom"); uk.setCapital("London"); uk.setCurrency(Currency.GBP); uk.setPopulation(63705000); countries.put(uk.getName(), uk); } public Country findCountry(String name) { Assert.notNull(name, "The country's name must not be null"); return countries.get(name); } } ~~~ ## 創建國家/地區服務端點要創建服務端點，只需要一個帶有一些Spring WS批注的POJO即可處理傳入的SOAP請求。以下清單（來自 `src/main/java/com/example/producingwebservice/CountryEndpoint.java`）顯示了這樣的類： ~~~ package com.example.producingwebservice; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.ws.server.endpoint.annotation.Endpoint; import org.springframework.ws.server.endpoint.annotation.PayloadRoot; import org.springframework.ws.server.endpoint.annotation.RequestPayload; import org.springframework.ws.server.endpoint.annotation.ResponsePayload; import io.spring.guides.gs_producing_web_service.GetCountryRequest; import io.spring.guides.gs_producing_web_service.GetCountryResponse; @Endpoint public class CountryEndpoint { private static final String NAMESPACE_URI = "http://spring.io/guides/gs-producing-web-service"; 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`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/server/endpoint/annotation/Endpoint.html)注解將類注冊為Spring WS，作為處理傳入SOAP消息的潛在候選者。這 [`@PayloadRoot`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/server/endpoint/annotation/PayloadRoot.html) 然后，Spring WS使用注釋基于消息的 `namespace` 和 `localPart`. 這 [`@RequestPayload`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/server/endpoint/annotation/RequestPayload.html) 批注指示傳入的消息將被映射到方法的 `request` 范圍。這 [`@ResponsePayload`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/server/endpoint/annotation/ResponsePayload.html) 注釋使Spring WS將返回的值映射到響應有效負載。在所有這些代碼塊中， io.spring.guides 除非您已運行任務以基于WSDL生成域類，否則這些類將在您的IDE中報告編譯時錯誤。 ## 配置Web服務Bean 使用與Spring WS相關的bean配置創建一個新類，如下清單（來自 `src/main/java/com/example/producingwebservice/WebServiceConfig.java`）顯示： ~~~ package com.example.producingwebservice; import org.springframework.boot.web.servlet.ServletRegistrationBean; import org.springframework.context.ApplicationContext; import org.springframework.context.annotation.Bean; import org.springframework.context.annotation.Configuration; import org.springframework.core.io.ClassPathResource; import org.springframework.ws.config.annotation.EnableWs; import org.springframework.ws.config.annotation.WsConfigurerAdapter; import org.springframework.ws.transport.http.MessageDispatcherServlet; import org.springframework.ws.wsdl.wsdl11.DefaultWsdl11Definition; import org.springframework.xml.xsd.SimpleXsdSchema; import org.springframework.xml.xsd.XsdSchema; @EnableWs @Configuration public class WebServiceConfig extends WsConfigurerAdapter { @Bean public ServletRegistrationBean<MessageDispatcherServlet> messageDispatcherServlet(ApplicationContext applicationContext) { MessageDispatcherServlet servlet = new MessageDispatcherServlet(); servlet.setApplicationContext(applicationContext); servlet.setTransformWsdlLocations(true); return new ServletRegistrationBean<>(servlet, "/ws/*"); } @Bean(name = "countries") public DefaultWsdl11Definition defaultWsdl11Definition(XsdSchema countriesSchema) { DefaultWsdl11Definition wsdl11Definition = new DefaultWsdl11Definition(); wsdl11Definition.setPortTypeName("CountriesPort"); wsdl11Definition.setLocationUri("/ws"); wsdl11Definition.setTargetNamespace("http://spring.io/guides/gs-producing-web-service"); wsdl11Definition.setSchema(countriesSchema); return wsdl11Definition; } @Bean public XsdSchema countriesSchema() { return new SimpleXsdSchema(new ClassPathResource("countries.xsd")); } } ~~~ * Spring WS使用不同的servlet類型來處理SOAP消息： [`MessageDispatcherServlet`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/transport/http/MessageDispatcherServlet.html)。注入和設置很重要 [`ApplicationContext`](https://docs.spring.io/spring/docs/current/javadoc-api/org/springframework/web/context/ApplicationContext.html) 到 [`MessageDispatcherServlet`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/transport/http/MessageDispatcherServlet.html)。否則，Spring WS將不會自動檢測Spring Bean。 * 命名這個豆 `messageDispatcherServlet`不替代Spring Boot的 [默認值 `DispatcherServlet`豆](https://docs.spring.io/spring-boot/docs/2.4.3/reference/htmlsingle/#howto-switch-off-the-spring-mvc-dispatcherservlet) 。 * [`DefaultMethodEndpointAdapter`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/server/endpoint/adapter/DefaultMethodEndpointAdapter.html)配置注釋驅動的Spring WS編程模型。這樣就可以使用各種注釋，例如 [`@Endpoint`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/server/endpoint/annotation/Endpoint.html) （較早前提過）。 * [`DefaultWsdl11Definition`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/ws/wsdl/wsdl11/DefaultWsdl11Definition.html) 通過使用公開標準的WSDL 1.1 [`XsdSchema`](https://docs.spring.io/spring-ws/sites/2.0/apidocs/org/springframework/xml/xsd/XsdSchema.html) 您需要為指定bean名稱 MessageDispatcherServlet 和 DefaultWsdl11Definition。 Bean名稱確定URL，Web服務和生成的WSDL文件可在該URL下使用。在這種情況下，WSDL將在 :/ws/countries.wsdl" class="bare" one-link-mark="yes">http://<host>:<port>/ws/countries.wsdl. 此配置還使用WSDL位置servlet轉換： `servlet.setTransformWsdlLocations(true)`。如果您訪問 [http：// localhost：8080 / ws / countries.wsdl](http://localhost:8080/ws/countries.wsdl) ，則 `soap:address`將有正確的地址。如果您改為從分配給計算機的面向公眾的IP地址訪問WSDL，則會看到該地址。 ## 使應用程序可執行 Spring Boot為您創建一個應用程序類。在這種情況下，無需進一步修改。您可以使用它來運行該應用程序。以下清單（來自 `src/main/java/com/example/producingwebservice/ProducingWebServiceApplication.java`）顯示了應用程序類： ~~~ package com.example.producingwebservice; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class ProducingWebServiceApplication { public static void main(String[] args) { SpringApplication.run(ProducingWebServiceApplication.class, args); } } ~~~ `@SpringBootApplication` 是一個方便注釋，它添加了以下所有內容： * `@Configuration`：將類標記為應用程序上下文的Bean定義的源。 * `@EnableAutoConfiguration`：告訴Spring Boot根據類路徑設置，其他bean和各種屬性設置開始添加bean。例如，如果 `spring-webmvc` 在類路徑上，此注釋將應用程序標記為Web應用程序并激活關鍵行為，例如設置 `DispatcherServlet`. * `@ComponentScan`：告訴Spring在服務器中尋找其他組件，配置和服務 `com/example` 包，讓它找到控制器。這 `main()` 方法使用Spring Boot的 `SpringApplication.run()`啟動應用程序的方法。您是否注意到沒有一行XML？沒有 `web.xml`文件。該Web應用程序是100％純Java，因此您無需處理任何管道或基礎結構。 ### Build an executable JAR 您可以使用Gradle或Maven從命令行運行該應用程序。您還可以構建一個包含所有必需的依賴項，類和資源的可執行JAR文件，然后運行該文件。生成可執行jar使得在整個開發生命周期中，跨不同環境等等的情況下，都可以輕松地將服務作為應用程序進行發布，版本控制和部署。如果您使用Gradle，則可以通過使用以下命令運行該應用程序 `./gradlew bootRun`。或者，您可以通過使用以下命令構建JAR文件： `./gradlew build` 然后運行JAR文件，如下所示： ~~~ java -jar build/libs/gs-soap-service-0.1.0.jar ~~~ 如果您使用Maven，則可以通過使用以下命令運行該應用程序 `./mvnw spring-boot:run`。或者，您可以使用以下命令構建JAR文件： `./mvnw clean package` 然后運行JAR文件，如下所示： ~~~ java -jar target/gs-soap-service-0.1.0.jar ~~~ 此處描述的步驟將創建可運行的JAR。您還可以構建經典的WAR文件。顯示日志記錄輸出。該服務應在幾秒鐘內啟動并運行。 ## 測試應用現在該應用程序正在運行，您可以對其進行測試。創建一個名為 `request.xml` 包含以下SOAP請求： ~~~ <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:gs="http://spring.io/guides/gs-producing-web-service"> <soapenv:Header/> <soapenv:Body> <gs:getCountryRequest> <gs:name>Spain</gs:name> </gs:getCountryRequest> </soapenv:Body> </soapenv:Envelope> ~~~ 在測試SOAP接口時，有一些選擇。您可以使用類似于 [SoapUI的](http://www.soapui.org) 工具，也可以在\* nix / Mac系統上使用命令行工具。以下示例從命令行使用curl： ~~~ # Use data from file curl --header "content-type: text/xml" -d @request.xml http://localhost:8080/ws ~~~ ~~~ # Use inline XML data curl <<-EOF -fsSL -H "content-type: text/xml" -d @- http://localhost:8080/ws \ > target/response.xml && xmllint --format target/response.xml <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:gs="http://spring.io/guides/gs-producing-web-service"> <soapenv:Header/> <soapenv:Body> <gs:getCountryRequest> <gs:name>Spain</gs:name> </gs:getCountryRequest> </soapenv:Body> </soapenv:Envelope> EOF ~~~ 如此一來，您應該看到以下響應： ~~~ <?xml version="1.0"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"> <SOAP-ENV:Header/> <SOAP-ENV:Body> <ns2:getCountryResponse xmlns:ns2="http://spring.io/guides/gs-producing-web-service"> <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> ~~~ 可能的是，輸出將是一個緊湊的XML文檔，而不是上面顯示的格式良好的文檔。如果您的系統上安裝了xmllib2，則可以 curl -fsSL --header "content-type: text/xml" -d @request.xml http://localhost:8080/ws > output.xml and xmllint --format output.xml 看到格式很好的結果。 ## 概括恭喜你！您已經使用Spring Web Services開發了基于SOAP的服務。