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

申請免費(fèi)試用、咨詢電話：400-8352-114

架構(gòu)Web Service:交互界面，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í)例的幫助和教程。

在本系列的前一篇文章中，對于給出的Case做了系統(tǒng)分析，并對系統(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的申請基本上可以依靠Web服務(wù)之外的流程完成，比如Web Application，因此Member Service的Web Service界面相對可以非常簡化。所有這些在線組件服務(wù)需要提供的對外接口，我們的詳細(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概述

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

簡單性，由于這是一個(gè)對于公共開放的Web服務(wù)，它的API的設(shè)計(jì)首先應(yīng)當(dāng)是簡單的，要被大量用戶接受，要獲得比較好的應(yīng)用，那么API必須簡單，沒有哪個(gè)復(fù)雜難用的API會得到大家的廣泛接受的，除非是普及率太廣的系統(tǒng)，而目前我們要設(shè)計(jì)的Web服務(wù)是新系統(tǒng)，所以針對目前的應(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)該具備對低版本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要覆蓋所有需要對外公開的功能，這相對而言是最好實(shí)現(xiàn)的目標(biāo)，只要設(shè)計(jì)階段考慮得完備，就能達(dá)到完備性的要求。而且萬一發(fā)現(xiàn)不完備的情況，修正起來也是相對容易的。

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的具體描述格式：

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

<featureBag>
  <feature>...</feature> *
</featureBag>

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

<parameterBag>
  <parameter> *
    <keyName>...</keyName>
    <keyValue>...</keyValue>
  </parameter>
</parameterBag>

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

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

save_category

用于保存category的最新信息，使用這個(gè)API調(diào)用，可以完成對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í)體的鍵值categoryKey或productKey為空，即表示這是一個(gè)新增的category或product，需要被插入到數(shù)據(jù)庫中，在返回消息中，將回送這些元素的鍵值。

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

<result>
  <category categoryKey="a01" parentCategoryKey="...">
    <category categoryKey="a02" parentCategoryKey="a01" />
    <category categoryKey="a03" parentCategoryKey="a01" />
    <category categoryKey="a04" parentCategoryKey="a01" />
    <product productKey="p01" parentCategoryKey="a01" />
    <product productKey="p02" parentCategoryKey="a01" />
  </category>
  <category categoryKey="b01" parentCategoryKey="...">
    <category categoryKey="b07" parentCategoryKey="b01" />
    <category categoryKey="b08" parentCategoryKey="b01" />
    <product productKey="p09" parentCategoryKey="b01" />
  </category>
</result>

 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)識的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)識的category的所有子元素組成。
name，這個(gè)name元素中描述的字符串是作為名串的最左子串存在的，在搜索中實(shí)施的也是最左匹配，比如在這個(gè)name元素中描述了"中國"那么"中國汽車"，"中國計(jì)算機(jī)"就會被匹配到，而"優(yōu)質(zhì)中國汽車"就不會被匹配到。

compliantSpecBag，該元素中描述了一個(gè)業(yè)界規(guī)范的聚集，依靠這個(gè)搜索時(shí)指定的聚集，我們就可以將所有不符合這些規(guī)范的計(jì)算機(jī)產(chǎn)品排除在搜索結(jié)果集之外。例如該元素中包含了兩個(gè)規(guī)范USB1.1和IEEE1394，那么只有同時(shí)支持這兩個(gè)規(guī)范的產(chǎn)品才會被搜索到。

parameterBag，該元素中描述了一個(gè)技術(shù)參數(shù)的聚集，其使用方式與compliantSpecBag類似，所有不符合所描述的技術(shù)參數(shù)指定的計(jì)算機(jī)產(chǎn)品將被排除在搜索結(jié)果集之外。

對于compliantSpecBag和parameterBag默認(rèn)的搜索中的處理行為是邏輯與的方式，我們可以通過參數(shù)指定來定義邏輯或的方式。例如：

<compliantSpecBag>
  <logicBehavior value="OR" />
  <specification specificationKey="Key[USB1.1]" />
  <specification specificationKey="Key[IEEE1394]" />
</compliantSpecBag>

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

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

<result>
  <product productKey="p01" parentCategoryKey="a01" />
    <name>...</name>
    <description>...</description>
  </product>
  <product productKey="p02" parentCategoryKey="a01" />
    <name>...</name>
    <description>...</description>
  </product>
</result>

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

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

Member Service

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

get_authToken

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

<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提供對用戶所提供的用戶ID和密碼進(jìn)行有效性檢查的方法。password參數(shù)必須出現(xiàn)，它表示了用戶ID所對應(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)榭紤]到刪除是萬不得已才會發(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ā)出訂單請求，在這個(gè)API中包含了申請新訂單和取消訂單的兩個(gè)操作。當(dāng)傳入的orderKey為空并包含其他細(xì)節(jié)內(nèi)容時(shí)，即為申請新訂單操作。如果傳入的orderKey為已有的order的鍵值，同時(shí)不包含order的其他細(xì)節(jié)內(nèi)容，那么即認(rèn)為其是取消訂單的操作。該消息的返回分別可以指明對于訂單請求的接受或拒絕指示。

get_orderDetail: 獲取訂單的詳細(xì)情況，用于在事后參閱。

find_order: 搜索按照輸入?yún)?shù)指明的條件的相關(guān)訂單。

描述與注冊: 發(fā)布Web服務(wù)

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

 參考資料

 柴曉路: 上海得易電子商務(wù)技術(shù)有限公司(DealEasy)首席系統(tǒng)架構(gòu)師、XML技術(shù)顧問。UDDI-China.org藍(lán)色火焰工作室(Blue Blaze Studio)成員。UDDI Advisor Group成員，WSUI Working Group成員。2000年獲復(fù)旦大學(xué)計(jì)算機(jī)科學(xué)碩士學(xué)位，曾在國際計(jì)算機(jī)科學(xué)學(xué)術(shù)會議(ICSC)、亞太區(qū)XML技術(shù)研討會(XML Asia/Pacific'99)、中國XML技術(shù)研討會(北京)、計(jì)算機(jī)科學(xué)期刊等各類國際、國內(nèi)重要會議與期刊上發(fā)表論文多篇。專長于基于XML的系統(tǒng)集成和數(shù)據(jù)交換的技術(shù)研究，同時(shí)對數(shù)據(jù)庫、面向?qū)ο蠹夹g(shù)及CSCW等技術(shù)比較擅長。