使用WSDL 2.0描述REST Web服务

　　Web服务这个术语通常与使用SOAP和WS*标准（例如WS-Addressing和WS-Security）的基于操作的服务相关联。REST Web服务这个术语一般是指使用HTTP和XML的基于资源的Web服务体系结构。其中每种体系结构的Web服务风格各有其影响力，但是直到最近，WSDL不再同等地支持这两种风格。WSDL 1.1 HTTP绑定不足以描述使用HTTP和XML的通信，因此没有办法使用WSDL来正式地描述REST Web服务。WSDL 2.0在设计时考虑到了REST Web服务，将WSDL 2.0作为World Wide Web Consortium (W3C)建议标准来发布意味着现在有了用于描述REST Web服务的语言。

　　REST

　　REST是一种体系结构风格，它将Web服务视为以资源为中心的应用程序。实际上，这意味着RESTful应用程序中的每个URL表示一个资源。URL 还易于理解和记忆。例如，某个书店可能为其销售的图书列表定义URLhttp://www.bookstore.com/books/，并对ISBN为0321396855的特定图书的相关详细信息定义了URL http://www.bookstore.com/books/0321396855/。这与以操作为中心的应用程序形成鲜明对比，后者通常具有很长的加密URL，用于描述要执行的特定操作，例如http://www.bookstore.com/action/query?t=b&id=11117645532&qp=0321396855。查询参数用于筛选结果。使用同样的书店示例，指定主题参数可以将图书列表限制到关于某个特定主题的图书。例如，URL http://www.bookstore.com/books/?subject=computers/eclipse 将返回关于 Eclipse 平台的图书列表。

　　Roy Fielding博士在他的博士论文中提出了术语REST，他在其中提到了“作为应用程序状态引擎的超媒体”。这意味着资源预期将包含超链接。这些超链接是用以进行转换的方法，该转换或者改变资源状态，或者转移到另一个资源。虽然超链接在由人类使用的(X)HTML应用程序中司空见惯，但它们通常不出现在由计算机使用的 XML 中。与 (X)HTML 一样，REST Web服务在XML中利用了超链接。

　　传统Web应用程序使用HTTP GET或POST操作来访问资源。相反，RESTful应用程序全面使用了HTTP谓词（POST、GET、PUT和DELETE），按照创建、读取、更新和删除模式来访问资源。

　　REST应用程序存在一个更重要的组件：RESTful应用程序应该是无状态的。这意味着在REST用程序中，服务器上没有存储任何会话状态。满足请求所需要的所有信息都携带在请求消息本身之中。因此在服务显式地允许的情况下，客户端可以缓存资源的表示形式，从而显著改进应用程序的性能。要了解有关 EST的更多信息，请参阅本文结尾的参考资料部分。

　　WSDL和REST

　　WSDL描述包含Web服务的所有详细信息，包括：

　　服务的URL。

　　服务所理解的通信机制。

　　服务所能执行的操作。

　　服务消息的结构。

　　客户端可以使用这些详细信息来与服务进行交互。

　　毫无疑问，REST Web服务到目前为止还没有利用WSDL 1.1 HTTP绑定的一个重要原因是由于WSDL 1.1 HTTP绑定不足以描述REST Web服务。

　　WSDL 2.0于2007年6月被宣布为W3C建议标准。创建 WSDL 的这第二个版本是为了解决WSDL 1.1存在的问题，Web服务互操作性（Web Services Interoperability，WS-I）组织已确了其中的许多问题。此外，WSDL 2.0还具有对HTTP绑定的良好支持。

　　WSDL是一种正式地描述Web服务的XML语言。可以将Web服务的WSDL描述看作是其与客户端之间签署的的API契约。WSDL描述指定Web服务的地址、允许的通信机制、接口和消息类型。简而言之，WSDL描述为客户端提供了使用 Web 服务所需要的所有信息。

　　WSDL的可用性不只是用作API契约。作为正式的定义，WSDL可由Web服务工具用于执行操作，例如：

　　采用各种语言生成客户端和服务存根。

　　发布Web服务。

　　动态测试Web服务。

　　绝大多数Web服务工具都包括 WSDL 1.1的支持，并且对WSDL 2.0的支持也正在增加。Apache Web服务项目包含两个目前支持WSDL 2.0的子项目。Woden是一个基于Java™的WSDL 2.0验证分析器。该项目还包含XSL Transformation (XSLT) WSDL 2.0优质打印机，用于提供更加可读的 WSDL文档形式。同样来自于Apache的Axis2是一个流行 Web服务运行时引擎，能够在WSDL 2.0文档的基础上生成Java客户端和服务器存根。

　　使用WSDL 2.0描述REST Web服务

　　本文的其余部分将指导您完成所需的步骤，以使用下面的简单示例场景来为一个REST Web服务创建WSDL 2.0描述。

　　您将运作一家具有创造性URL的书店http://www.bookstore.com。您先前已经创建了两个REST Web服务：

　　图书列表服务检索您的书店中销售的图书的列表。

　　图书详细信息服务检索有关某一本特定图书的详细信息。

　　信息在XML文档中返回。请考虑一下有关那些服务的详细信息：

　　图书列表服务的URL为 http://www.bookstore.com/books/。因为您是一家历史悠久的图书零售商，所以您销售的图书的列表相当大。因此您提供了以下查询参数列表，客户可以使用这些参数来筛选结果： Author 、Language 、Publisher 、Subject 、Title

　　例如，URL http://www.bookstore.com/books/?subject=computers/eclipse 返回有关Eclipse的计算机图书的列表，如清单 1 所示。

　　清单 1. 来自图书列表服务的响应

以下是引用片段：
　
<booklist:bookList


   xsi:schemaLocation=”http://www.bookstore.org/booklist/xsd booklist.xsd
                       http://www.bookstore.org/book/xsd book.xsd”>
  <booklist:book url=”http://www.bookstore.com/books/0321442598″
     title=”BIRT: A Field Guide to Reporting”/>
  <booklist:book url=”http://www.bookstore.com/books/0321205758″
     title=”Contributing to Eclipse: Principles, Patterns, and Plug-Ins”/>
  <booklist:book url=”http://www.bookstore.com/books/0321245873″
     title=”Eclipse AspectJ: Aspect-Oriented Programming with AspectJ and the…”/>
  <booklist:book url=”http://www.bookstore.com/books/0321288157″
     title=”Eclipse Distilled”/>
  <booklist:book url=”http://www.bookstore.com/books/0131425420″
     title=”Eclipse Modeling Framework”/>
  <booklist:book url=”http://www.bookstore.com/books/0321334612″
     title=”Eclipse Rich Client Platform: Designing, Coding, and Packaging Java…”/>
  <booklist:book url=”http://www.bookstore.com/books/0321396855″
     title=”Eclipse Web Tools Platform: Developing Java Web Applications”/>
  <booklist:book url=”http://www.bookstore.com/books/032142672X”
     title=”Eclipse: Building Commercial-Quality Plug-Ins (2nd Edition)”/>
  <booklist:book url=”http://www.bookstore.com/books/0321443853″
     title=”Integrating and Extending BIRT”/>
  <booklist:book url=”http://www.bookstore.com/books/0321268385″
     title=”Official Eclipse 3.0 FAQs”/>
  <booklist:book url=”http://www.bookstore.com/books/0321256638″
     title=”Official Eclipse 3.0 FAQs”/>
</booklist:bookList>

　　图书详细信息服务的 URL 为 http://www.bookstore.com/books/ISBN_NUMBER，其中ISBN_NUMBER应该替换为特定图书的ISBN。例如，URL http://www.bookstore.com/books/0321396855 将返回我的图书Eclipse Web Tools Platform的详细信息，如清单 2 所示（请参阅参考资料以获得指向该图书网站的链接）。

　　清单 2. 来自图书详细信息服务的响应
　

以下是引用片段：
<book:book

   xsi:schemaLocation=”http://www.bookstore.org/book/xsd book.xsd”>
  <book:title>Eclipse Web Tools Platform: Developing Java Web Applications</book:title>
  <book:author>
    <book:firstName>Naci</book:firstName>
    <book:lastName>Dai</book:lastName>
  </book:author>
  <book:author>
    <book:firstName>Lawrence</book:firstName>
    <book:lastName>Mandel</book:lastName>
  </book:author>
  <book:author>
    <book:firstName>Arthur</book:firstName>
    <book:lastName>Ryman</book:lastName>
  </book:author>
  <book:overview>
Discover Eclipse Web Tools Platform (WTP), the new end-to-end toolset for Java-based
Web development. The WTP seamlessly integrates all of the tools today’s Java Web
developer needs. Eclipse WTP is both an unprecedented open source resource for
working developers and a powerful foundation for state-of-the-art commercial products.
This book offers in-depth descriptions of every tool included in WTP, introducing powerful
capabilities never before available in Eclipse. The authors cover the entire
Web-development process — from defining Web application architectures and
development processes through testing and beyond. And if you’re seeking to extend WTP,
this book provides an introduction to the platform’s rich APIs. The book also
  </book:overview>
  <book:pages>752</book:pages>
  <book:publisher>Addison-Wesley Professional</book:publisher>
  <book:language>English</book:language>
  <book:isbn-10>0321396855</book:isbn-10>
  <book:isbn-13>978-0321396853</book:isbn-13>
  <book:price>54.99</book:price>
</book:book>

　　在下面的几个部分中，您将了解如何使用上面列出的详细信息来创建图书列表服务的WSDL 2.0描述。图书详细信息服务虽然在该场景中有用，但其WSDL描述并没有结构上的不同，因此本文将不介绍该服务。然而，本文结尾的下载部分提供了图书列表和图书详细信息服务的 WSDL 2.0 描述以及清单1和清单2中的相同文档。

　　在开始图书列表服务的WSDL描述之前，让我们首先看一下WSDL 2.0基础。

　　WSDL 2.0基础

　　WSDL 2.0是核心命名空间为 http://www.w3.org/ns/wsdl 的XML语言。WSDL 2.0文档的根元素是description元素。description具有四个子元素，它们共同封装了关于某个Web服务的所有详细信息。

　　WSDL 2.0 文档的框架如清单 3 所示。

　　清单 3. WSDL 2.0文档框架
　

以下是引用片段：
<wsdl:description >
  <wsdl:types/>
  <wsdl:interface/>
  <wsdl:binding/>
  <wsdl:service/>
</wsdl:description>

　　types元素包含了描述Web服务消息的所有XML模式元素和类型定义。WSDL 2.0对其他类型系统的使用保持开放，但实际上仅与XML模式一起使用。

　　interface元素定义Web服务操作，包括特定的输入、输出和所传递的错误消息，以及传递那些错误消息的顺序。

　　binding元素定义客户端如何与Web服务通信。在REST Web服务的情况下，一个绑定指定客户端可以使用HTTP进行通信。

　　service元素将Web服务的地址与特定的接口和绑定相关联。

　　WSDL 2.0定义了另外两个关于REST Web服务的相关命名空间：

　　HTTP命名空间 http://www.w3.org/ns/wsdl/http，其中包括HTTP绑定元素

　　WSDL扩展命名空间 http://www.w3.org/ns/wsdl-extensions，其中包括三个属性的定义：两个用于将XML文档中的超链接与Web服务描述相关联，第三个用于安全地描述Web服务操作

　　下面几个部分将更详细地介绍本部分中讨论的所有WSDL元素。

　　处理图书列表服务

　　提醒一下，图书列表服务的URL为 http://www.bookstore.com/books/。为了处理该服务，您将使用WSDL service元素，此元素至少需要一个endpoint子元素。endpoint元素的address属性用于指定该服务的URL，如清单 4 所示。endpoint元素还用于将某个绑定与具有 binding 属性的服务关联起来。service元素反过来又将某个接口与具有interface属性的服务关联起来。您将在以下几个部分中创建接口和绑定，因此现在可以将这些属性值保留空白。

　　图书列表服务的WSDL 2.0文档还需要一个目标命名空间，因此定义命名空间http://www.bookstore.org/booklist/wsdl。

　　清单 4. 图书列表服务定义
　

以下是引用片段：
<wsdl:description
   targetNamespace=”http://www.bookstore.org/booklist/wsdl”
   >
  <wsdl:service name=”BookList” interface=””>
    <wsdl:documentation>
       The bookstore’s book list service.
    </wsdl:documentation>
    <wsdl:endpoint name=”BookListHTTPEndpoint”
       binding=””
       address=”http://www.bookstore.com/books/”>
    </wsdl:endpoint>
  </wsdl:service>
</wsdl:description>

　　与图书列表服务进行HTTP通信

　　图书列表服务的绑定定义需要指定该服务使用HTTP来进行通信。为此，可以为binding元素的type属性指定值http://www.w3.org/ns/wsdl/http。

　　该绑定还可以选择引用某个接口。将interface属性保留空白；您将在下一个部分中创建该属性。如果某个接口与该绑定相关联，binding 可以选择声明一个子operation元素，用于镜像接口的operation元素。您需要创建一个存根operation元素，并在创建接口以后填充此引用。

　　存在四个HTTP通信谓词： GET 、PUT 、POST 、DELETE

　　图书列表服务是读取请求，因此使用HTTP GET进行通信。使用WSDL 2.0 HTTP命名空间中的HTTP method属性，在operation元素上设置GET谓词。要使用此属性，您首先需要在Description元素上声明命名空间http://www.w3.org/ns/wsdl/http。

　　清单 5 显示了图书列表服务的HTTP绑定声明。现在既然已经声明了绑定，您可以将endpoint元素的绑定引用更新为引用 tns:BookListHTTPBinding。

　　清单 5. 图书列表绑定定义
　

以下是引用片段：
<wsdl:description
   targetNamespace=”http://www.bookstore.org/booklist/wsdl”

   >
  <wsdl:binding name=”BookListHTTPBinding”
     type=”http://www.w3.org/ns/wsdl/http”
     interface=””>
    <wsdl:documentation>
       The RESTful HTTP binding for the book list service.
    </wsdl:documentation>
    <wsdl:operation ref=”” whttp:method=”GET”/>
  </wsdl:binding>
  <wsdl:service name=”BookList” interface=””>
    <wsdl:documentation>
       The bookstore’s book list service.
    </wsdl:documentation>
    <wsdl:endpoint name=”BookListHTTPEndpoint”
       binding=”tns:BookListHTTPBinding”
       address=”http://www.bookstore.com/books/”>
    </wsdl:endpoint>
  </wsdl:service>
</wsdl:description>

　　定义图书列表服务操作

　　到目前为止，您已经了解如何处理图书列表Web服务并与之通信。接下来您将指定图书列表服务操作，该操作描述图书列表服务的功能。

　　interface元素及其子operation元素用于定义服务的操作。在该图书列表服务的情况下，您将定义单个操作getBookList，此操作使用图书列表来响应请求。

　　下一步，指定operation元素的三个属性：

　　pattern：用于指定该操作的消息交换模式（message exchange pattern，MEP）。MEP定义操作中的消息顺序及其方向。在此例中，请指定值 http://www.w3.org/ns/wsdl/in-out，以指示该服务接收一个输入消息——图书列表请求——并发送一个输出消息——图书列表。为了支持此MEP，请指定operation元素的input和output子元素。这些元素用于引用定义消息结构的XML模式元素，下一部分将创建那些消息结构。

　　style：用于指定有关某个操作的附加信息。请指定值http://www.w3.org/ns/wsdl/style/iri，从而对input元素内容施加限制，例如要求它仅使用XML模式元素。

　　wsdlx:safe：在WSDL扩展命名空间中，此属性声明该操作是等幂的。这种类型的操作不修改资源，因此可以调用多次并获得相同的结果。为了利用此元素，可以在description元素上声明WSDL扩展命名空间 http://www.w3.org/ns/wsdl-extensions。

　　您可以在“WSDL 2.0 Part 2: Adjuncts”（请参阅参考资料以获得链接）中找到预定义的 MEP样式和afe属性定义。

　　在清单 6 中查看图书列表服务的接口声明。既然现在已经声明了接口和操作，您可以更新service和binding元素的接口引用和绑定operation元素的接口操作引用。

　　清单 6. 图书列表接口定义
　

以下是引用片段：
<wsdl:description
   targetNamespace=”http://www.bookstore.org/booklist/wsdl”


   >
  <wsdl:interface name=”BookListInterface”>
    <wsdl:operation name=”getBookList”
       pattern=”http://www.w3.org/ns/wsdl/in-out”
       style=”http://www.w3.org/ns/wsdl/style/iri”
       wsdlx:safe=”true”>
      <wsdl:documentation>
         This operation returns a list of books.
      </wsdl:documentation>
      <wsdl:input element=””/>
      <wsdl:output element=””/>
    </wsdl:operation>
  </wsdl:interface>
  <wsdl:binding name=”BookListHTTPBinding”
     type=”http://www.w3.org/ns/wsdl/http”
     interface=”tns:BookListInterface”>
    <wsdl:documentation>
       The RESTful HTTP binding for the book list service.
    </wsdl:documentation>
    <wsdl:operation ref=”tns:getBookList” whttp:method=”GET”/>
  </wsdl:binding>
  <wsdl:service name=”BookList” interface=”tns:BookListInterface”>
    <wsdl:documentation>
       The bookstore’s book list service.
    </wsdl:documentation>
    <wsdl:endpoint name=”BookListHTTPEndpoint”
       binding=”tns:BookListHTTPBinding”
       address=”http://www.bookstore.com/books/”>
    </wsdl:endpoint>
  </wsdl:service>
</wsdl:description>

　　定义图书列表服务操作消息

　　图书列表Web服务具有两个消息：一个输入消息和一个输出消息。您需要描述特定的消息结构，以便客户端知道要向服务发送什么消息，以及预期服务会返回什么消息。

　　WSDL 2.0支持使用多种类型系统来描述消息内容，但是目前仅使用了XML模式。本部分不介绍XML模式的详细信息。许多应用程序中都使用了XML模式，例如WSDL 1.1，并且存在许多关于它的优秀文章。本部分重点介绍如何将XML模式用于图书列表REST Web服务，以及如何使用WSDL 2.0定义的附加属性来标注模式属性。

　　要为图书列表REST Web服务创建两个消息，您需要创建两个全局元素：

　　getBookList表示输入消息。其中包含元素序列，包括服务上允许的每个查询参数，即作者、标题、出版商、主题和语言。getBookList元素的内容仅限于元素，因为您为接口操作指定了 IRI 样式。

　　bookList表示输出消息。其中包含book元素的序列。每个book元素包含title和url属性。title属性应该是不言而喻的。url属性是指向图书详细信息REST Web服务的链接，该服务返回特定图书的详细信息。

　　您的url属性定义包括两个来自WSDL扩展命名空间的属性。属 wsdlx:interface和wsdlx:binding标识该服务的特定WSDL 2.0接口和绑定。工具可以使用此语义信息来自动发现该服务。要利用这些属性，可以在schema元素上指定WSDL扩展命名空间。此外，还要在 WSDL 2.0 描述中包括图书详细信息服务的命名空间，以引用该服务的接口和绑定。

　　图书列表服务的XML模式如清单 7 所示。您可以在下载部分获取图书详细信息服务的描述。

　　清单 7. 图书列表服务的XML模式
　

以下是引用片段：
<schema
   targetNamespace=”http://www.bookstore.org/booklist/xsd”



   elementFormDefault=”qualified”>

  <element name=”getBookList” type=”tns:getBookListType”>
   <annotation>
     <documentation>
         The request element for the book list service.
     </documentation>
    </annotation>
  </element>

  <element name=”bookList” type=”tns:bookListType”>
    <annotation>
      <documentation>
         The response element for the book list service.
      </documentation>
    </annotation>
  </element>

  <complexType name=”getBookListType”>
    <sequence>
      <element name=”author” type=”string” minOccurs=”0″ maxOccurs=”unbounded”/>
      <element name=”title” type=”string” minOccurs=”0″ maxOccurs=”1″/>
      <element name=”publisher” type=”string” minOccurs=”0″ maxOccurs=”1″/>
      <element name=”subject” type=”string” minOccurs=”0″ maxOccurs=”1″/>
      <element name=”language” type=”string” minOccurs=”0″ maxOccurs=”unbounded”/>
    </sequence>
  </complexType>
  <complexType name=”bookListType”>
    <sequence>
      <element name=”book” type=”tns:bookType” minOccurs=”0″ maxOccurs=”unbounded”/>
    </sequence>
  </complexType>
  <complexType name=”bookType”>
    <attribute name=”title” type=”string”/>
    <attribute name=”url” type=”anyURI”
       wsdlx:interface=”booksvc:BookInterface”
       wsdlx:binding=”booksvc:BookHTTPBinding”/>
  </complexType>
</schema>

　　要引用XML模式中声明的输入和输出元素，您必须将该模式导入您的WSDL文档。要导入某个模式，您可以在types部分使用import元素，如清单 8 所示。您还需要在接口操作的input和output元素中添加对getBookList和bookList元素的引用，并将XML模式（图书列表模式）的命名空间声明添加到description元素。

　　清单 8 显示了图书列表REST Web服务的完整WSDL 2.0描述。可以在下载部分中获取此服务和图书详细信息REST Web服务的描述。

　　清单 8. 图书列表REST Web服务的WSDL 2.0描述
　

以下是引用片段：
<wsdl:description
   targetNamespace=”http://www.bookstore.org/booklist/wsdl”




   >
  <wsdl:documentation>
     This is a WSDL 2.0 description of a sample bookstore service
     listing for obtaining book information.
  </wsdl:documentation>
  <wsdl:types>
    <xs:import namespace=”http://www.bookstore.org/booklist/xsd”
       schemaLocation=”booklist.xsd”/>
  </wsdl:types>
  <wsdl:interface name=”BookListInterface”>
    <wsdl:operation name=”getBookList”
       pattern=”http://www.w3.org/ns/wsdl/in-out”
       style=”http://www.w3.org/ns/wsdl/style/iri”
       wsdlx:safe=”true”>
      <wsdl:documentation>
         This operation returns a list of books.
      </wsdl:documentation>
      <wsdl:input element=”msg:getBookList”/>
      <wsdl:output element=”msg:bookList”/>
    </wsdl:operation>
  </wsdl:interface>
  <wsdl:binding name=”BookListHTTPBinding”
     type=”http://www.w3.org/ns/wsdl/http”
     interface=”tns:BookListInterface”>
    <wsdl:documentation>
       The RESTful HTTP binding for the book list service.
    </wsdl:documentation>
    <wsdl:operation ref=”tns:getBookList” whttp:method=”GET”/>
  </wsdl:binding>
  <wsdl:service name=”BookList” interface=”tns:BookListInterface”>
    <wsdl:documentation>
       The bookstore’s book list service.
    </wsdl:documentation>
    <wsdl:endpoint name=”BookListHTTPEndpoint”
       binding=”tns:BookListHTTPBinding”
       address=”http://www.bookstore.com/books/”>
    </wsdl:endpoint>
  </wsdl:service>
</wsdl:description>

　　总结

　　在本文中，您了解REST以及WSDL 2.0 REST Web服务如何使用HTTP和XML来进行通信。RESTful应用程序以资源为中心而不是以操作为中心。以正式的方式描述REST Web服务的价值是使用该描述作为客户端与服务提供者之间的正式契约，并支持工具。WSDL 2.0支持REST Web服务的描述。您逐步地完成了使用WSDL 2.0 和XML模式来描述图书列表REST Web服务的过程。

源码下载：http://club.techtarget.com.cn/showtopic-73981.aspx

我们一直都在努力坚持原创.......请不要一声不吭，就悄悄拿走。

我原创，你原创，我们的内容世界才会更加精彩！

【所有原创内容版权均属TechTarget，欢迎大家转发分享。但未经授权，严禁任何媒体（平面媒体、网络媒体、自媒体等）以及微信公众号复制、转载、摘编或以其他方式进行使用。】

微信公众号