WebService CXF WSDL描述

原文http://www.ibm.com/developerworks/cn/webservices/ws-wsdl/index.html

 

本文初步介绍了Web Service 'stack'中对于Web服务即时装配，自动集成起着关键作用的WSDL规范，首先介绍了WSDL的作用和意义，其次对WSDL文档的结构作出概要地介绍，对每个元素的作用作了探讨，分析了其开放和复用的体系设计的思想，最后通过一个实例详细说明了WSDL的工作模式。 

    本文所引用的资源主要包括两类，一类是Web服务的技术资源网站，包含了大量Web服务的技术信息，另一类是Web服务“stack"系列技术规范，他们是一个整体的技术体系，包括UDDI、SOAP、WSDL、XML等。本文的最后给出了这些资源的链接，有兴趣的读者可以通过这些资源链接找到所需的内容。 

Web Service "Stack" 

    在我的先前的文章中，我已经介绍过Web服务的整个技术体系Web Service "stack"，如下图： 

Figure 1. Web Service "stack" 
 


其中，绿色部分是先前已经定义好的并且广泛使用的传输层和网络层的标准：IP、HTTP、SMTP等。而蓝色部分是目前开发的Web服务的相关标准协议，包括服务调用协议SOAP、服务描述协议WSDL和服务发现/集成协议UDDI，以及服务工作流描述语言WSFL。而橙色部分描述的是更高层的待开发的关于路由、可靠性以及事务等方面的协议。黄色部分是各个协议层的公用机制，这些机制一般由外部的正交机制来完成。 

其中，一个可以使用的Web服务应当按照需要选用若干层次的功能，而无需所有的特性。但是无论如何为了实现一个一般意义上的Web服务，具备Web服务的基础特性：跨平台调用和接口可机器识别，那么必需使用WSDL和SOAP。SOAP是用来最终完成Web服务调用的，而WSDL则是用于描述如何使用 SOAP来调用Web服务的。 

    WSDL 是一种XML Application，他将Web服务描述定义为一组服务访问点，客户端可以通过这些服务访问点对包含面向文档信息或面向过程调用的服务进行访问(类似远程过程调用)。WSDL首先对访问的操作和访问时使用的请求/响应消息进行抽象描述，然后将其绑定到具体的传输协议和消息格式上以最终定义具体部署的服务访问点。相关的具体部署的服务访问点通过组合就成为抽象的Web服务。 

    在具体使用中，我们可以对 WSDL 进行扩展(类似SOAP的可扩展性)，这样无论通信时使用何种消息格式或网络协议，都可以对服务访问点及其使用的消息格式进行描述。在WSDL的框架中，可以使用任意的消息格式和网络协议，如同SOAP中可以使用任意的网络协议一样。在WSDL规范中，定义了如何使用SOAP消息格式、HTTP GET/POST消息格式以及MIME格式来完成Web服务交互的规范。 
WSDL概述 
    由于通信协议和消息格式在 Web 技术圈子里已经达到了标准化，我们知道在通常的开发过程中，对于对象的Interface一定具备相应的SDK描述文档，Web服务也是一种对象，只不过它是被部署在Web上而已。很自然的，我们也完全需要有对Web服务这个对象的界面的SDK描述文档。然而这两者又不尽相同，一来目前在Web上的应用已经完全接受了XML这个基本的标准，基本上所有新出台的技术都是基于XML标准的，二来Web服务的目标是即时装配，松散耦合以及自动集成的，这意味着 SDK描述文档应当是具备被机器识别的能力的。 

    也就是说，对于使用标准化的消息格式/通信协议的Web服务，它需要以某种结构化的方式(即XML)对Web服务的调用/通信加以描述，而且实现这一点也显得非常重要，这是Web服务即时装配的基本保证。WSDL正是这样一种描述语言，WSDL 定义了一套基于 XML的语法，将Web服务描述为能够进行消息交换的服务访问点的集合，从而满足了这种需求。WSDL 服务定义为分布式系统提供了可机器识别的SDK文档，并且可用于描述自动执行应用程序通信中所涉及的细节。 

    WSDL 文档将Web服务定义为服务访问点或端口的集合。在 WSDL 中，由于服务访问点和消息的抽象定义已从具体的服务部署或数据格式绑定中分离出来，因此可以对抽象定义进行再次使用：消息，指对交换数据的抽象描述；而端口类型，指操作的抽象集合。用于特定端口类型的具体协议和数据格式规范构成了可以再次使用的绑定。将Web访问地址与可再次使用的绑定相关联，可以定义一个端口，而端口的集合则定义为服务。因此，WSDL 文档在Web服务的定义中使用下列元素： 

  

Definitions	WSDL的根节点，主要包括：name属性，WebService服务名，可通过@WebService注解的serviceName更改；targetNamespace属性，命名空间，可通过@WebService注解的targetNamespace更改。
Types	定义web service 使用的数据类型，他是独立与机器和语言的类型定义，这些类型被message标签所引用。
Message	web service 使用的消息，他定义了WebService函数的参数。在WSDL中，输入输出参数要分开定义，使用不同的message标签体标识。message定义的输入输出参数被portType标签所引用。
Operation	对服务中所支持的操作的抽象描述，一般单个Operation描述了一个访问入口的请求/响应消息对。
PortType	对于某个访问入口点类型所支持的操作的抽象集合，这些操作可以由一个或多个服务访问点来支持。web service 执行的操作。引用message标签定义的内容来描述函数信息（函数名，输入输出参数等）。
Binding	特定端口类型的具体协议和数据格式规范的绑定。Web service 使用的通信协议。将portType中定义的服务绑定到SOAP协议，这部分XML 指定最终发布的 WebService的SOAP 消息封装格式、发布地址等。
Service	相关服务访问点的集合。这个元素的name 属性指定服务名称（这里与根元素的name 属性相同），子元素port的name 属性指定port名称，子元素address的location 属性指定Web 服务的地址。
Port	定义为协议/数据格式绑定与具体Web访问地址组合的单个服务访问点。

 

 

<?xml version="1.0"?>
<definitions name="StockQuote"
             targetNamespace="http://example.com/stockquote.wsdl"
             xmlns:tns="http://example.com/stockquote.wsdl"
             xmlns:xsd1="http://example.com/stockquote.xsd"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns="http://schemas.xmlsoap.org/wsdl/">


  <types>
    <schema targetNamespace="http://example.com/stockquote.xsd"
            xmlns="http://www.w3.org/1999/XMLSchema">
      <element name="TradePriceRequest">
        <complexType>
          <all>
            <element name="tickerSymbol" type="string"/>
          </all>
        </complexType>
      </element>
      <element name="TradePriceResult">
        <complexType>
          <all>
            <element name="price" type="float"/>
          </all>
        </complexType>
      </element>
    </schema>
  </types>

<?xml version="1.0"?>
<definitions name="StockQuote"
             targetNamespace="http://example.com/stockquote.wsdl"
             xmlns:tns="http://example.com/stockquote.wsdl"
             xmlns:xsd1="http://example.com/stockquote.xsd"
             xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/"
             xmlns="http://schemas.xmlsoap.org/wsdl/">


  <types>
    <schema targetNamespace="http://example.com/stockquote.xsd"
            xmlns="http://www.w3.org/1999/XMLSchema">
      <element name="TradePriceRequest">
        <complexType>
          <all>
            <element name="tickerSymbol" type="string"/>
          </all>
        </complexType>
      </element>
      <element name="TradePriceResult">
        <complexType>
          <all>
            <element name="price" type="float"/>
          </all>
        </complexType>
      </element>
    </schema>
  </types>

   
上面这部分是数据类型的定义，其中为定义了两个元素的结构: 

    * TradePriceRequest(交易价格请求): 将该元素定义为包含一个字符串元素(tickerSymbol)的复合类型元素。 
    * TradePriceResult(交易价格): 将该元素定义为一个包含一个浮点数元素(price)的复合类型元素。 
Java代码  

 

<message name="GetLastTradePriceInput">
    <part name="body" element="xsd1:TradePriceRequest"/>
  </message>

  <message name="GetLastTradePriceOutput">
    <part name="body" element="xsd1:TradePriceResult"/>
  </message>

<message name="GetLastTradePriceInput">
    <part name="body" element="xsd1:TradePriceRequest"/>
  </message>

  <message name="GetLastTradePriceOutput">
    <part name="body" element="xsd1:TradePriceResult"/>
  </message>

   这部分是消息格式的抽象定义，其中定义了两个消息格式： 

    * GetlastTradePriceInput(获取最后交易价格的请求消息格式): 由一个消息片断组成，该消息片断的名字是body，包含的具体元素类型是TradePriceRequest。(前面已经定义过了) 
    * GetLastTradePriceOutput(获取最后交易价格的响应消息格式) : 由一个消息片断组成，该消息片断的名字是body，包含的具体元素类型是TradePriceResult。(前面已经定义过了) 
Java代码  

 

<portType name="StockQuotePortType">
   <operation name="GetLastTradePrice">
     <input message="tns:GetLastTradePriceInput"/>
     <output message="tns:GetLastTradePriceOutput"/>
   </operation>
 </portType>

 <portType name="StockQuotePortType">
    <operation name="GetLastTradePrice">
      <input message="tns:GetLastTradePriceInput"/>
      <output message="tns:GetLastTradePriceOutput"/>
    </operation>
  </portType>

    这部分定义了服务访问点的调用模式的类型，表明StockQuoteService的某个入口类型是请求/响应模式，请求消息是GetlastTradePriceInput，而响应消息是GetLastTradePriceOutput。 
Java代码  

 

<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="GetLastTradePrice">
        <soap:operation soapAction="http://example.com/GetLastTradePrice"/>
          <input>
            <soap:body use="literal" namespace="http://example.com/stockquote.xsd"
                       encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </input>
          <output>
            <soap:body use="literal" namespace="http://example.com/stockquote.xsd"
                       encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </output>
        </soap:operation>
      </operation>
    </soap:binding>
  </binding>

<binding name="StockQuoteSoapBinding" type="tns:StockQuotePortType">
    <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
      <operation name="GetLastTradePrice">
        <soap:operation soapAction="http://example.com/GetLastTradePrice"/>
          <input>
            <soap:body use="literal" namespace="http://example.com/stockquote.xsd"
                       encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </input>
          <output>
            <soap:body use="literal" namespace="http://example.com/stockquote.xsd"
                       encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
          </output>
        </soap:operation>
      </operation>
    </soap:binding>
  </binding>

  
  这部分将服务访问点的抽象定义与SOAP HTTP绑定，描述如何通过SOAP/HTTP来访问按照前面描述的访问入口点类型部署的访问入口。其中规定了在具体SOAP调用时，应当使用的 soapAction是"http://example.com/GetLastTradePrice"，而请求/响应消息的编码风格都应当采用SOAP 规范默认定义的编码风格" http://schemas.xmlsoap.org/soap/encoding/"。 
Java代码  

 

<service name="StockQuoteService">
    <documentation>股票查询服务</documentation>
    <port name="StockQuotePort" binding="tns:StockQuoteBinding">
    <soap:address location="http://example.com/stockquote"/>
    </port>
  </service>

</definitions>

<service name="StockQuoteService">
    <documentation>股票查询服务</documentation>
    <port name="StockQuotePort" binding="tns:StockQuoteBinding">
    <soap:address location="http://example.com/stockquote"/>
    </port>
  </service>

</definitions>

   
这部分是具体的Web服务的定义，在这个名为StockQuoteService的Web服务中，提供了一个服务访问入口，访问地址是"http://example.com/stockquote"，使用的消息模式是由前面的binding所定义的。 

    按照这个WSDL文档的描述，在具体Web服务的使用中，具体发生的SOAP交互可能如下面所示： 

SOAP消息请求: 
Java代码  

 

POST /StockQuote HTTP/1.1
Host: example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.com/GetLastTradePrice"

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <m:TradePriceRequest xmlns:m="http://example.com/stockquote.xsd">
      <tickerSymbol>MSFT</tickerSymbol >
    </m:TradePriceRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

POST /StockQuote HTTP/1.1
Host: example.com
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn
SOAPAction: "http://example.com/GetLastTradePrice"

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
  <SOAP-ENV:Body>
    <m:TradePriceRequest xmlns:m="http://example.com/stockquote.xsd">
      <tickerSymbol>MSFT</tickerSymbol >
    </m:TradePriceRequest>
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

SOAP消息响应: 
Java代码  

 

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <m:TradePriceResult xmlns:m=" http://example.com/stockquote.xsd ">
      <price>74.5</price>
    </m:TradePriceResult >
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

HTTP/1.1 200 OK
Content-Type: text/xml; charset="utf-8"
Content-Length: nnnn

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
                   SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"/>
  <SOAP-ENV:Body>
    <m:TradePriceResult xmlns:m=" http://example.com/stockquote.xsd ">
      <price>74.5</price>
    </m:TradePriceResult >
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

大家可以参考下图，来理解一下WSDL文档的结构组织： 

Figure 2. WSDL元素的对象结构示意图 
 


    其中，Types是一个数据类型定义的容器，包含了所有在消息定义中需要的XML元素的类型定义，我将在今后的文章中结合XML Schema来详细说明如何进行类型定义。 

    Message具体定义了在通信中使用的消息的数据结构，Message元素包含了一组Part元素，每个Part元素都是最终消息的一个组成部分，每个 Part都会引用一个DataType来表示它的结构。Part元素不支持嵌套(可以使用DataType来完成这方面的需要)，都是并列出现。 

    PortType具体定义了一种服务访问入口的类型，何谓访问入口的类型呢？就是传入/传出消息的模式及其格式。一个PortType可以包含若干个 Operation，而一个Operation则是指访问入口支持的一种类型的调用。在WSDL里面支持四种访问入口调用的模式： 

   1. 单请求; 
   2. 单响应; 
   3. 请求/响应; 
   4. 响应/请求。 

    在这里请求指的是从客户端到Web服务端，而响应指的是从Web服务端到客户端。PortType的定义中会引用消息定义部分的一个到两个消息，作为请求或响应消息的格式。比如，一个股票查询的访问入口可能就会支持两种请求消息，一种请求消息中指明股票代码，而另一种请求消息中则会指明股票的名称，响应消息可能都是股票的价格等等。

    以上三种结构描述了调用Web服务的抽象定义，这三部分与具体Web服务部署细节无关，是可复用的描述(每个层次都可以复用)。如果与一般的对象语言做比较的话，这部分可以堪称是IDL描述的对象，描述了对象的接口标准，但是到底对象是用哪种语言实现，遵从哪种平台的细节规范，被部署在哪台机器上则是后面的元素所描述的。 

    Service描述的是一个具体的被部署的Web服务所提供的所有访问入口的部署细节，一个Service往往会包含多个服务访问入口，而每个访问入口都会使用一个Port元素来描述。 

    Port描述的是一个服务访问入口的部署细节，包括通过哪个Web地址(URL)来访问，应当使用怎样的消息调用模式来访问等。其中消息调用模式则是使用Binding结构来表示。 

    Binding结构定义了某个PortType与某一种具体的网络传输协议或消息传输协议相绑定，从这一层次开始，描述的内容就与具体服务的部署相关了。比如可以将PortType与SOAP/HTTP绑定，也可以将PortType与MIME/SMTP相绑定等。 

    在介绍了WSDL的主要元素之后，大家会发现，WSDL的设计理念完全继承了以XML为基础的当代Web技术标准的一贯设计理念：开放。WSDL允许通过扩展使用其他的类型定义语言(不光是XML Schema)，允许使用多种网络传输协议和消息格式(不光是在规范中定义的这些：SOAP/HTTP，HTTP-GET/POST以及MIME等)。同时WSDL也应用了当代软件工程中的复用理念，分离了抽象定义层和具体部署层，使得抽象定义层的复用性大大增加。比如我们可以先使用抽象定义层为一类 Web服务进行抽象定义(比如UDDI Registry，抽象定义肯定是完全一致的遵循了UDDI规范)，而不同的运营公司可以采用不同的具体部署层的描述结合抽象定义完成其自身的Web服务的描述。 
WSDL文档示例 
    下例是一个提供股票报价的简单Web服务的 WSDL 定义。该服务支持名为 GetLastTradePrice 的单一操作，这个操作是通过在 HTTP 上运行 SOAP 1.1 协议来实现的。该请求接受一个类型为字符串的 tickerSymbol，并返回类型为浮点数的价格。 
Java代码