架构Web Service: 交互界面，Web服务定义的核心  
  


   
内容：

API概述
Catalog Service
Member Service
Feedback Service
Order Service
描述与注册: 发布Web服务
参考资料
作者简介


相关内容：

实战Web服务
基于Web服务的应用、解决方案和开发平台
什么是Web服务?
为什么需要Web服务?




柴晓路 (fennivel@uddi-china.org)
Chief System Architect
2001年9月17日

本文是架构Web服务的系列文章的第五篇，以在前文中描述的应用实例为基础，详细定义了Catalog服务的API消息，全部API是使用SOAP完成调用和返回的，本文通过API的具体定义，详细介绍和演示了交互的数据结构和API消息结构的定义方法和相应模式，为读者在定义自己的Web服务接口时提供了实例的帮助和教程。
在本系列的前一篇文章中，对于给出的Case做了系统分析，并对系统作了模块划分，初步界定有如下在线服务组件：

Catalog Service - 类别(Category)管理，产品(Product)管理，数据交换，数据备份等；
Order Service - 接受订单，向其他接受订单的服务发送订单等；
Feedback Service - 反馈信息(Feedback)管理，数据交换等。
由于这些服务显然必须有一个用户系统来支持，无论是因为安全性的考虑(有权限的才能做某些操作，还是因为事务的用户相关性(显然Order这样的服务不大可能脱离用户而实施)。因此我们需要增加一个在线服务Member Service，Membership的申请基本上可以依靠Web服务之外的流程完成，比如Web Application，因此Member Service的Web Service界面相对可以非常简化。所有这些在线组件服务需要提供的对外接口，我们的详细定义从下图开始：

Figure 1.   API消息


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

API概述

对于整个系统的API设计，其遵循的原则有这样几条：

简单性，由于这是一个对于公共开放的Web服务，它的API的设计首先应当是简单的，要被大量用户接受，要获得比较好的应用，那么API必须简单，没有哪个复杂难用的API会得到大家的广泛接受的，除非是普及率太广的系统，而目前我们要设计的Web服务是新系统，所以针对目前的应用实况，API必须简单。

可扩展性，作为更新频率较高，开放性较强的Web服务，其API应当具有很好的向后扩展性，当应内部需求的改变或外部需求的改变的需要时，API将根据新的商业逻辑发生变化，此时不应当将API从根本上推翻重建，而应当具备增量式的可扩展的能力。

兼容性，其实兼容性与可扩展性是互通的，API的兼容性指的就是向后兼容性，高版本的API应该具备对低版本API的兼容性，也就是说使用高版本API的Web服务，应当能支持使用低版本API的调用。

高效性，API应该在坚持简单性的前提下，兼顾高效性，当某些组合操作应用地非常频繁的时候，我们应当为这样的组合操作调用设计一个只需一次交互的单一入口调用，这样能够提升外部应用的效率，同时减轻Web服务的负载。

完备性，所谓完备性就是说整个API要覆盖所有需要对外公开的功能，这相对而言是最好实现的目标，只要设计阶段考虑得完备，就能达到完备性的要求。而且万一发现不完备的情况，修正起来也是相对容易的。

Catalog Service

save_category: 保存category，在这个API调用中，包含了更新和新建的操作，同时category的迁移也可以通过这个API来完成。
delete_category: 删除category，将指定category及其全部子元素从Catalog中删除。
find_category: 在catalog中定位寻找category，可以通过多种方式，比如名称，比如关键字等。
save_product: 保存product，在这个API调用中，同样可以包含更新、新建和迁移的操作。
delete_product: 删除product，将指定product的信息从Catalog中删除。
find_product: 在catalog中定位寻找product，可以通过多种方式，比如名称，比如所在的category，比如关键字等。
get_categoryDetail: 获取category的完整信息，包括包含的所有category的简要信息和product的详细信息。
get_productDetail: 获取product的完整信息。
get_categoryInfo: 获取category及其所有子孙category和product的所有信息。
在定义这些消息之前，我们首先需要确定的是category和product这两个实体的XML描述格式。参照前文中的实体关系模型，我们可以将它们定义如下：

Category的具体描述格式：


<category categoryKey="…" parentCategoryKey="…">
  <name>……</name>
  <description>……</description>
</category>




Product的具体描述格式：


<product productKey="…" parentCategoryKey="…">
  <name>……</name>
  <description>……</description>
  <compliantSpecBag />
  <featureBag />
  <parameterBag />
</category>




其中，compliantSpecBag、featureBag和parameterBag的具体格式分别如下：

<compliantSpecBag>
  <specification specificationKey="……" /> *
</compliantSpecBag>




compliantSpecBag描述的是一种计算机产品遵循了哪些相关的业界标准。在这个聚集里面，specification这个元素可以出现多次，每一个条目分别表示其遵循了一种工业标准，比如一台娱乐型的便携式计算机可能就会遵循诸如USB1.0、IEEE1394等等的工业规范。


<featureBag>
  <feature>……</feature> *
</featureBag>




featureBag描述的是一种计算机产品的重要特性。在这个聚集里面，feature这个元素可以出现多次，每一个条目使用字符串文本来描述某一种产品特性。比如一台娱乐型的便携式计算机可能的特性会包括"重量仅有2磅，厚度仅有1.9cm，超级便携"这样的特性描述。


<parameterBag>
  <parameter> *