架構(gòu)Web Service: 交互界面，Web服務(wù)定義的核心

發(fā)布時(shí)間：2008-07-08 閱讀數(shù)：次來源：網(wǎng)樂原科技

內(nèi)容：

API概述
Catalog Service
Member Service
Feedback Service
Order Service
描述與注冊(cè): 發(fā)布Web服務(wù)
參考資料
作者簡介

相關(guān)內(nèi)容：

實(shí)戰(zhàn)Web服務(wù)
基于Web服務(wù)的應(yīng)用、解決方案和開發(fā)平臺(tái)
什么是Web服務(wù)?
為什么需要Web服務(wù)?

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

本文是架構(gòu)Web服務(wù)的系列文章的第五篇，以在前文中描述的應(yīng)用實(shí)例為基礎(chǔ)，詳細(xì)定義了Catalog服務(wù)的API消息，全部API是使用SOAP完成調(diào)用和返回的，本文通過API的具體定義，詳細(xì)介紹和演示了交互的數(shù)據(jù)結(jié)構(gòu)和API消息結(jié)構(gòu)的定義方法和相應(yīng)模式，為讀者在定義自己的Web服務(wù)接口時(shí)提供了實(shí)例的幫助和教程。
在本系列的前一篇文章中，對(duì)于給出的Case做了系統(tǒng)分析，并對(duì)系統(tǒng)作了模塊劃分，初步界定有如下在線服務(wù)組件：

Catalog Service - 類別(Category)管理，產(chǎn)品(Product)管理，數(shù)據(jù)交換，數(shù)據(jù)備份等；
Order Service - 接受訂單，向其他接受訂單的服務(wù)發(fā)送訂單等；
Feedback Service - 反饋信息(Feedback)管理，數(shù)據(jù)交換等。
由于這些服務(wù)顯然必須有一個(gè)用戶系統(tǒng)來支持，無論是因?yàn)榘踩缘目紤](有權(quán)限的才能做某些操作，還是因?yàn)槭聞?wù)的用戶相關(guān)性(顯然Order這樣的服務(wù)不大可能脫離用戶而實(shí)施)。因此我們需要增加一個(gè)在線服務(wù)Member Service，Membership的申請(qǐng)基本上可以依靠Web服務(wù)之外的流程完成，比如Web Application，因此Member Service的Web Service界面相對(duì)可以非常簡化。所有這些在線組件服務(wù)需要提供的對(duì)外接口，我們的詳細(xì)定義從下圖開始：

Figure 1. API消息

本文所引用的資源主要包括兩類，一類是Web服務(wù)的技術(shù)資源網(wǎng)站，包含了大量Web服務(wù)的技術(shù)信息，另一類是Web服務(wù)“stack"系列技術(shù)規(guī)范，他們是一個(gè)整體的技術(shù)體系，包括UDDI、SOAP、WSDL、XML等。本文的最后給出了這些資源的鏈接，有興趣的讀者可以通過這些資源鏈接找到所需的內(nèi)容。

API概述

對(duì)于整個(gè)系統(tǒng)的API設(shè)計(jì)，其遵循的原則有這樣幾條：

簡單性，由于這是一個(gè)對(duì)于公共開放的Web服務(wù)，它的API的設(shè)計(jì)首先應(yīng)當(dāng)是簡單的，要被大量用戶接受，要獲得比較好的應(yīng)用，那么API必須簡單，沒有哪個(gè)復(fù)雜難用的API會(huì)得到大家的廣泛接受的，除非是普及率太廣的系統(tǒng)，而目前我們要設(shè)計(jì)的Web服務(wù)是新系統(tǒng)，所以針對(duì)目前的應(yīng)用實(shí)況，API必須簡單。

可擴(kuò)展性，作為更新頻率較高，開放性較強(qiáng)的Web服務(wù)，其API應(yīng)當(dāng)具有很好的向后擴(kuò)展性，當(dāng)應(yīng)內(nèi)部需求的改變或外部需求的改變的需要時(shí)，API將根據(jù)新的商業(yè)邏輯發(fā)生變化，此時(shí)不應(yīng)當(dāng)將API從根本上推翻重建，而應(yīng)當(dāng)具備增量式的可擴(kuò)展的能力。

兼容性，其實(shí)兼容性與可擴(kuò)展性是互通的，API的兼容性指的就是向后兼容性，高版本的API應(yīng)該具備對(duì)低版本API的兼容性，也就是說使用高版本API的Web服務(wù)，應(yīng)當(dāng)能支持使用低版本API的調(diào)用。

高效性，API應(yīng)該在堅(jiān)持簡單性的前提下，兼顧高效性，當(dāng)某些組合操作應(yīng)用地非常頻繁的時(shí)候，我們應(yīng)當(dāng)為這樣的組合操作調(diào)用設(shè)計(jì)一個(gè)只需一次交互的單一入口調(diào)用，這樣能夠提升外部應(yīng)用的效率，同時(shí)減輕Web服務(wù)的負(fù)載。

完備性，所謂完備性就是說整個(gè)API要覆蓋所有需要對(duì)外公開的功能，這相對(duì)而言是最好實(shí)現(xiàn)的目標(biāo)，只要設(shè)計(jì)階段考慮得完備，就能達(dá)到完備性的要求。而且萬一發(fā)現(xiàn)不完備的情況，修正起來也是相對(duì)容易的。

Catalog Service

save_category: 保存category，在這個(gè)API調(diào)用中，包含了更新和新建的操作，同時(shí)category的遷移也可以通過這個(gè)API來完成。
delete_category: 刪除category，將指定category及其全部子元素從Catalog中刪除。
find_category: 在catalog中定位尋找category，可以通過多種方式，比如名稱，比如關(guān)鍵字等。
save_product: 保存product，在這個(gè)API調(diào)用中，同樣可以包含更新、新建和遷移的操作。
delete_product: 刪除product，將指定product的信息從Catalog中刪除。
find_product: 在catalog中定位尋找product，可以通過多種方式，比如名稱，比如所在的category，比如關(guān)鍵字等。
get_categoryDetail: 獲取category的完整信息，包括包含的所有category的簡要信息和product的詳細(xì)信息。
get_productDetail: 獲取product的完整信息。
get_categoryInfo: 獲取category及其所有子孫category和product的所有信息。
在定義這些消息之前，我們首先需要確定的是category和product這兩個(gè)實(shí)體的XML描述格式。參照前文中的實(shí)體關(guān)系模型，我們可以將它們定義如下：

Category的具體描述格式：

Product的具體描述格式：

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

compliantSpecBag描述的是一種計(jì)算機(jī)產(chǎn)品遵循了哪些相關(guān)的業(yè)界標(biāo)準(zhǔn)。在這個(gè)聚集里面，specification這個(gè)元素可以出現(xiàn)多次，每一個(gè)條目分別表示其遵循了一種工業(yè)標(biāo)準(zhǔn)，比如一臺(tái)娛樂型的便攜式計(jì)算機(jī)可能就會(huì)遵循諸如USB1.0、IEEE1394等等的工業(yè)規(guī)范。

featureBag描述的是一種計(jì)算機(jī)產(chǎn)品的重要特性。在這個(gè)聚集里面，feature這個(gè)元素可以出現(xiàn)多次，每一個(gè)條目使用字符串文本來描述某一種產(chǎn)品特性。比如一臺(tái)娛樂型的便攜式計(jì)算機(jī)可能的特性會(huì)包括"重量僅有2磅，厚度僅有1.9cm，超級(jí)便攜"這樣的特性描述。

parameterBag描述的是一種計(jì)算機(jī)產(chǎn)品的相關(guān)技術(shù)參數(shù)。在這個(gè)聚集里面，parameter這個(gè)元素可以出現(xiàn)多次，每一個(gè)條目使用keyName和keyValue名值對(duì)來描述某一個(gè)技術(shù)參數(shù)。比如一臺(tái)便攜式計(jì)算機(jī)可能的技術(shù)參數(shù)會(huì)是TFT_Size10.1"。

在定義了核心的數(shù)據(jù)模型之后，我們就可以來分別定義具體的API消息了。

save_category

用于保存category的最新信息，使用這個(gè)API調(diào)用，可以完成對(duì)category的更新、新建和遷移的操作。

<save_category>
<authInfo>……</authInfo>
<category categoryKey="…" parentCategoryKey="…"> *
<name>……</name>
<description>……</description>
<category /> *
<product /> *
</category>
</save_category>

在上述的語法描述中，大家應(yīng)該可以發(fā)現(xiàn)，save_category能夠用于保存一棵或多棵完整的category樹，而不光光是僅僅保存一個(gè)或多個(gè)category結(jié)點(diǎn)，這樣的設(shè)計(jì)是為了高效性的設(shè)計(jì)目標(biāo)而做的調(diào)整。

當(dāng)整個(gè)消息中的任意一個(gè)category或product所屬的標(biāo)識(shí)自身實(shí)體的鍵值categoryKey或productKey為空，即表示這是一個(gè)新增的category或product，需要被插入到數(shù)據(jù)庫中，在返回消息中，將回送這些元素的鍵值。

當(dāng)消息中任意一個(gè)category或product的parentCategoryKey沒有發(fā)生更改時(shí)，表明是要更新該元素的信息。而若parentCategoryKey發(fā)生更改的時(shí)候，表明該元素將從之前的由原有parentCategoryKey所標(biāo)識(shí)的category結(jié)點(diǎn)下被遷移到由新的parentCategoryKey所標(biāo)識(shí)的category結(jié)點(diǎn)下。當(dāng)然如果包含了數(shù)據(jù)更新操作，同樣會(huì)實(shí)施該數(shù)據(jù)更新操作。

細(xì)心的讀者一定已經(jīng)發(fā)現(xiàn)了在這個(gè)消息中，有一個(gè)authInfo元素，這是一個(gè)用于權(quán)限檢驗(yàn)的授權(quán)令牌。在后面我將指明這個(gè)元素是如何獲取并使用的。

save_category消息調(diào)用的返回是一個(gè)或多個(gè)完整的被接受的category信息，與提交的信息的差別就是僅有概要信息，沒有相信信息，同時(shí)原先空著的鍵值都被填上Web服務(wù)所指派的鍵值。下面是一個(gè)返回消息的例子：

delete_category

用于刪除category的API調(diào)用，能夠?qū)⒁粋€(gè)或多個(gè)category及其全部子元素從Catalog中刪除。

<delete_category>
<authInfo>……</authInfo>
<category categoryKey="…" /> *
</delete_category>

在上述的語法描述中，大家應(yīng)該可以發(fā)現(xiàn)，save_category能夠用于刪除一個(gè)或多個(gè)使用categoryKey標(biāo)識(shí)的category。當(dāng)一個(gè)category被刪除時(shí)，其所有子元素(包括category子元素和product子元素)都將被刪除。

delete_category消息調(diào)用的返回是一個(gè)或多個(gè)被實(shí)施刪除的category信息的鍵值列表。

find_product

用于在某個(gè)catalog中搜尋滿足指定條件的product，在這個(gè)API消息中，支持多種查詢方式，比如名稱，比如按照所遵循的行業(yè)規(guī)范等。

<find_product>
<authInfo>……</authInfo>
<category categoryKey="…" />
<name />
<compliantSpecBag />
<parameterBag>
</find_product>

在find_product消息中，支持四種搜索條件：

category，該元素描述了待搜索category子樹的根。表明待執(zhí)行的搜索的空間是由該元素中的categoryKey所標(biāo)識(shí)的category的所有子元素組成。
name，這個(gè)name元素中描述的字符串是作為名串的最左子串存在的，在搜索中實(shí)施的也是最左匹配，比如在這個(gè)name元素中描述了"中國"那么"中國汽車"，"中國計(jì)算機(jī)"就會(huì)被匹配到，而"優(yōu)質(zhì)中國汽車"就不會(huì)被匹配到。
compliantSpecBag，該元素中描述了一個(gè)業(yè)界規(guī)范的聚集，依靠這個(gè)搜索時(shí)指定的聚集，我們就可以將所有不符合這些規(guī)范的計(jì)算機(jī)產(chǎn)品排除在搜索結(jié)果集之外。例如該元素中包含了兩個(gè)規(guī)范USB1.1和IEEE1394，那么只有同時(shí)支持這兩個(gè)規(guī)范的產(chǎn)品才會(huì)被搜索到。
parameterBag，該元素中描述了一個(gè)技術(shù)參數(shù)的聚集，其使用方式與compliantSpecBag類似，所有不符合所描述的技術(shù)參數(shù)指定的計(jì)算機(jī)產(chǎn)品將被排除在搜索結(jié)果集之外。
對(duì)于compliantSpecBag和parameterBag默認(rèn)的搜索中的處理行為是邏輯與的方式，我們可以通過參數(shù)指定來定義邏輯或的方式。例如：

這個(gè)例子表示需要搜索的計(jì)算機(jī)產(chǎn)品要么兼容USB1.1，要么兼容IEEE1394接口，那么不支持這兩種規(guī)范中任一規(guī)范的計(jì)算機(jī)產(chǎn)品將被排除在搜索結(jié)果集之外。

find_product消息調(diào)用的返回是一個(gè)或多個(gè)被匹配到的product信息，但改信息列表是一個(gè)概要信息的列表。下面是一個(gè)返回消息的例子：

在分析了上述三個(gè)API消息之后，我們不難理解save_product、delete_product和find_category和前面三個(gè)消息基本類似，且形式更為簡化，因此就不在詳細(xì)說明，浪費(fèi)篇幅了。

而對(duì)于其余三個(gè)消息：get_categoryDetail，get_productDetail和get_categoryInfo，一來這三個(gè)消息相對(duì)簡單，傳入鍵值返回實(shí)體信息，二來經(jīng)過前面的演示，相信大家應(yīng)該有了一個(gè)具體的認(rèn)識(shí)，因此在這里就不花篇幅定義具體消息了。

Member Service

對(duì)于Member Service而言，提供兩個(gè)API消息：

get_authToken

用于向Member Service請(qǐng)求一個(gè)認(rèn)證令牌。在調(diào)用其他所有API 時(shí)都需要使用認(rèn)證令牌。此函數(shù)在功能上等價(jià)于那些完成登錄請(qǐng)求的程序。

<get_authToken generic="2.0" xmlns="urn:uddi-org:api_v2"
userID="someLoginName"
password="somePassword" />

userID參數(shù)必須出現(xiàn)，表示在線服務(wù)所授權(quán)的個(gè)體用戶。Member Service提供對(duì)用戶所提供的用戶ID和密碼進(jìn)行有效性檢查的方法。password參數(shù)必須出現(xiàn)，它表示了用戶ID所對(duì)應(yīng)的密碼。

discard_authToken

用于通知Member Service，先前提供的認(rèn)證令牌不再有效。當(dāng)其他Web服務(wù)在Member Service接受到本消息之后，仍然收到這一認(rèn)證令牌的使用，那么其他Web服務(wù)應(yīng)當(dāng)判斷其為非法。

<discard_authToken generic="2.0" xmlns="urn:uddi-org:api_v2" >
<authInfo/>
</discard_authToken>

authInfo這個(gè)參數(shù)是必需的，它是一個(gè)包含了認(rèn)證令牌的元素。認(rèn)證令牌可以使用 get_authToken API調(diào)用來獲得。

Feedback Service

save_feedback: 保存feedback，在這個(gè)API調(diào)用中，包含了更新和新建的操作，同時(shí)category的遷移也可以通過這個(gè)API來完成。另外，使用這個(gè)API還能完成刪除的操作(之所以這樣設(shè)計(jì)是因?yàn)榭紤]到刪除是萬不得已才會(huì)發(fā)生的操作)，刪除操作通過僅傳入feedbackKey和authInfo來完成操作。
find_feedback: 在catalog中定位尋找feedback，比如名稱，比如categoryKey等。
get_feedbackDetail: 獲取一個(gè)category下同層所有feedback的詳細(xì)信息。
get_feedbackInfo: 獲取一個(gè)category下整個(gè)子樹中所有feedback的詳細(xì)信息。
Order Service

request_order: 發(fā)出訂單請(qǐng)求，在這個(gè)API中包含了申請(qǐng)新訂單和取消訂單的兩個(gè)操作。當(dāng)傳入的orderKey為空并包含其他細(xì)節(jié)內(nèi)容時(shí)，即為申請(qǐng)新訂單操作。如果傳入的orderKey為已有的order的鍵值，同時(shí)不包含order的其他細(xì)節(jié)內(nèi)容，那么即認(rèn)為其是取消訂單的操作。該消息的返回分別可以指明對(duì)于訂單請(qǐng)求的接受或拒絕指示。
get_orderDetail: 獲取訂單的詳細(xì)情況，用于在事后參閱。
find_order: 搜索按照輸入?yún)?shù)指明的條件的相關(guān)訂單。
描述與注冊(cè): 發(fā)布Web服務(wù)

在本文中，詳細(xì)描述和介紹了Web服務(wù)的API是如何設(shè)計(jì)和定義的，其中介紹了一些基本的設(shè)計(jì)和應(yīng)用的模式。在本系列之后的文章中，我將以使用WSDL描述Web服務(wù)，以及使用UDDI注冊(cè)Web服務(wù)來結(jié)束這個(gè)系列。