為你的網(wǎng)絡(luò)服務(wù)制作文檔

一個(gè)WSDL文檔總是有definitions 元件作為它的根。文檔中指定WSDL的元件都術(shù)語WSDL名字域，它的URL是http://schemas.xmlsoap.org/wsdl/。任何WSDL語言元件可以包含名為document 的另一個(gè)元件。這個(gè)元件包含了人類可讀的文本并且意味著把所包含的元件用文檔說明。document 元件可以包含任意的文本和元件。WSDL指定的元件有：

1.types: 描述message使用的類型
　　
2.message: 定義在調(diào)用時(shí)從一點(diǎn)傳到另一點(diǎn)的數(shù)據(jù)
　　
3.portType: 定義operation的收集
　　
4.operation: 定義input, output, 和fault 消息的綜合
　　
5.input: 一個(gè)被發(fā)送到服務(wù)器上的 message
　　
6.output: 一個(gè)發(fā)送到用戶的message
　　
7.fault: 一個(gè)作為處理message 的錯(cuò)誤的結(jié)果返回的數(shù)值
　　
8.binding: 描述用來承擔(dān)網(wǎng)絡(luò)服務(wù)的通信的協(xié)議；捆綁了現(xiàn)有的SOAP, HTTP GET, HTTP POST, 和MIME
　　
9.service: 定義了port的收集；每個(gè)service 要映射到一個(gè)portType 中并且表現(xiàn)出訪問那個(gè)portType 中operation 的不同方法

這些元件中的許多還包含可擴(kuò)展性元件?？蓴U(kuò)展性元件定義了所給的傳輸?shù)母鞣N特性如何能被映射到那個(gè)特殊元件中。例如，在一個(gè)使用SOAP綁定的操作元件中，你可以指定SOAPAction 和通信的方式（RPC或文檔）。

這節(jié)中將給出關(guān)于WSDL文件所提供的項(xiàng)目的一個(gè)簡(jiǎn)短總結(jié)。對(duì)于完全的總結(jié)，參考WSDL規(guī)范，位于Web Services Description Language (WSDL) 1.1。

自定義類型

WSDL文檔可以定義消息所使用的類型。當(dāng)定義自定義類型時(shí)，你應(yīng)該使用XSD來代替其他類型定義語言。使用XSD允許你更簡(jiǎn)單地使用WSDL相關(guān)的工具箱。這也幫助那些也許必須手工生成定制客戶的人。但是，如果你看到需要定義呢自己的類型系統(tǒng)，你也許會(huì)－但是我不推薦。

類型在類型模塊中列出。使用這個(gè)，你可以映射你自己的語言規(guī)范，為XSD請(qǐng)求自定義類型。如果一個(gè)棒球隊(duì)希望得到一個(gè)隊(duì)員的名稱、平均擊球、年平均擊球數(shù)和隊(duì)員編號(hào)，他們就應(yīng)該按下面的類型定義來定義：

＜types＞

＜s:complexType name="Player"＞

＜s:sequence＞

＜s:element minOccurs="1" maxOccurs="1" name="Name" nillable="true"
type="s:string" /＞

＜s:element minOccurs="1" maxOccurs="1" name="Average"
type="s:double" /＞

＜s:element minOccurs="1" maxOccurs="1" name="Year" type="s:long" /＞

＜s:element minOccurs="1" maxOccurs="1" name="Number"
type="s:short" /＞

＜/s:sequence＞

＜/s:complexType＞
＜/types＞

這里使用了一些XML名稱域，它們?cè)谖臋n的其他地方定義。這里要注意的重要事情是，我們有一組定義隊(duì)員的元件的名稱。復(fù)雜的類型Player 現(xiàn)在被定義了，并且可以北映射到任何不同的語言中。這種類型也指定我們?cè)鯓硬拍茉谕ㄐ艜r(shí)對(duì)Player 進(jìn)行序列化。如果使用在一個(gè)消息中，這個(gè)元件將像下面的樣子：

＜message name="PlayerMessage"＞

＜part name="thePlayer" element="s0:Player" /＞

＜/message＞

portTypes 和Bindings

WSDL也可以既對(duì)一個(gè)給定的portType 上的操作又為詳細(xì)綁定的數(shù)據(jù)創(chuàng)建文檔。相關(guān)的操作應(yīng)該存在于一個(gè)給定的portType 中。這些操作間的關(guān)系代表性地用實(shí)現(xiàn)它們的語言片斷定義。例如，如果一個(gè)COM對(duì)象和Java類給出5個(gè)方法作為網(wǎng)絡(luò)服務(wù)，這5個(gè)方法一起來定義portType 。每個(gè)portType 都有一個(gè)匹配的binding 元件。這個(gè)binding 元件可以被用來定義portType中的每個(gè)operation 如何映射到特殊的協(xié)議中。你也許有一個(gè)按照下面定義的portType ：

＜portType name="PlayerStats"＞

＜o(jì)peration name="GetBattingAverage"＞

＜input message="s0:GetBattingAverageIn" /＞

＜o(jì)utput message="s0:GetBattingAverageOut" /＞

＜/operation＞

＜/portType＞

這個(gè)portType 也許被許多方法所支持（重新調(diào)用那個(gè)網(wǎng)絡(luò)服務(wù)可以通過許多協(xié)議，包括SOAP、HTTP GET和HTTP POST）。一個(gè)對(duì)SOAP的binding 也許像這樣：

＜binding name="PlayerStatsSoap" type="s0:PlayerStats"＞

＜soap:binding transport=http://schemas.xmlsoap.org/soap/http
style="document" /＞

＜o(jì)peration name="GetBattingAverage"＞

＜soap:operation
soapAction="http://www.seattlemariners.org/GetBattingAverage"
style="document" /＞

＜input＞

＜soap:body use="literal" /＞

＜/input＞

＜o(jì)utput＞

＜soap:body use="literal" /＞

＜/output＞

＜/operation＞

＜/binding＞

這個(gè)binding 元件表明這個(gè)操作將在HTTP上使用SOAP來傳輸。GetBattingAverage 操作使用HTTP SOAPAction 頭，http://www.seattlemariners.org/GetBattingAverage 。這個(gè)操作是面向文檔的并且使用文字編碼。

我們也可以定義特定服務(wù)的結(jié)束點(diǎn)在哪。如果這個(gè)結(jié)束點(diǎn)可以通過一些不同的綁定來達(dá)到，例如SOAP，HTTP GET和HTTP POST，這個(gè)服務(wù)片斷就會(huì)像這樣：

＜service name="PlayerStats"＞

＜documentation＞Gets player information for the Seattle

Mariners.＜/documentation＞

＜port name="PlayerStatsSoap" binding="s0:PlayerStatsSoap"＞

＜soap:address
location="http://someIP/baseball1/baseballservice.asmx" /＞

＜/port＞

＜port name="PlayerStatsHttpGet" binding="s0:PlayerStatsHttpGet"＞

＜http:address
location="http://someIP/baseball1/baseballservice.asmx" /＞

＜/port＞

＜port name="PlayerStatsHttpPost" binding="s0:PlayerStatsHttpPost"＞

＜http:address
location="http://someIP/baseball1/baseballservice.asmx" /＞

＜/port＞

＜/service＞

這個(gè)特殊服務(wù)描述指出了相同的結(jié)束點(diǎn)，http://someIP/baseball1/baseballservice.asmx ，可以處理所有三個(gè)綁定。你也可以使用這個(gè)片斷來在不同的地方描述相同的結(jié)束點(diǎn)。

＜service name="PlayerStats"＞

＜port name="PlayerStatsUSA" binding="s0:PlayerStatsSoap"＞

＜soap:address
location=
"http://someIPInUSA/baseball1/baseballservice.asmx" /＞

＜/port＞

＜port name="PlayerStatsJapan" binding="s0:PlayerStatsSoap"＞

＜soap:address
location=
"http://someIPInJapan/baseball1/baseballservice.asmx" /＞

＜/port＞

＜/service＞

使用文檔

你的網(wǎng)絡(luò)服務(wù)的文檔也應(yīng)該描述了你希望人們?cè)鯓觼硎褂媚愕木W(wǎng)絡(luò)服務(wù)。解釋錯(cuò)誤將如何被返回，如何初始化使用，等等。這個(gè)信息將幫助其他人來使用你的網(wǎng)絡(luò)服務(wù)。除非你做一些簡(jiǎn)單的事情，就像從股票行情自動(dòng)收錄器找到股票報(bào)價(jià)，人們就需要好的文檔。

首先，包含一個(gè)總結(jié)文檔。一個(gè)好的總結(jié)包括指出兵總結(jié)與網(wǎng)絡(luò)服務(wù)相關(guān)的文檔－WSDL位置，開發(fā)者指導(dǎo)，API參考等等。在開發(fā)者指導(dǎo)中，解釋如何使用網(wǎng)絡(luò)服務(wù)。描述典型使用情況，也描述錯(cuò)誤處理。

當(dāng)描述錯(cuò)誤處理時(shí)，列出每個(gè)網(wǎng)絡(luò)服務(wù)方法可能返回的錯(cuò)誤。給出返回代碼，這樣客戶程序開發(fā)者就可以查詢錯(cuò)誤代碼，然后用顯示消息和記錄條目的方法把相應(yīng)意義的消息提供給它們的最終用戶。對(duì)于個(gè)性化服務(wù)，我們有一節(jié)文檔來解釋如何處理錯(cuò)誤；它也提供了通常對(duì)如何處理SOAP錯(cuò)誤的總結(jié)。然后我們指出如何發(fā)現(xiàn)錯(cuò)誤代碼和錯(cuò)誤描述。我們通過提供一個(gè)指定什么樣的錯(cuò)誤存在和這些數(shù)字意味著什么地表格來在方法描述中找到這些。例如，我們寫道GetFavorite 調(diào)用可以返回下面的錯(cuò)誤：

數(shù)字 描述

1002 Invalid licensee key.

1005 Invalid user name.

作為替代在一個(gè)方法接一個(gè)方法的基礎(chǔ)上列出錯(cuò)誤，你也可以做一個(gè)所有網(wǎng)絡(luò)服務(wù)可能會(huì)返回的所有錯(cuò)誤的列表。但是，這樣做的困難在于，客戶程序開發(fā)者將不指定會(huì)從各種各樣的代碼片斷返回什么樣的錯(cuò)誤。這使得編寫錯(cuò)誤處理程序?qū)λ麄儊碚f變得困難，但是卻使你的文檔更容易創(chuàng)建和保存。我們確定我們最好去做這困難的工作，而不是讓開發(fā)人員通過反復(fù)試驗(yàn)來學(xué)習(xí)他們必須處理的錯(cuò)誤。這要以被大多數(shù)windows API文檔使用的模型為基礎(chǔ)，在那里每個(gè)函數(shù)都列出了它們也許會(huì)返回的錯(cuò)誤。

除了錯(cuò)誤處理，你也會(huì)希望未網(wǎng)絡(luò)服務(wù)中的各種操作做文檔。這應(yīng)該像其他API文檔一樣：

·解釋操作做什么
　　
·定義操作的參數(shù)的意義和類型
　　
·提供示例代碼
　　
·給出幫助提示

除了上面所說，在所用的通信方式（單通道，請(qǐng)求－響應(yīng)，等等）上給出一個(gè)示例SOAP消息交換。為了感覺我們?nèi)绾巫鲞@個(gè)，看一看個(gè)性化服務(wù)API參考。

你也許還希望花一些時(shí)間來定義對(duì)象或用WSDL的說法，portType 。也就是描述函數(shù)的收集并且給出用戶可以從哪里找到這個(gè)WSDL文件的指針。用戶程序開發(fā)人員會(huì)希望得到WSDLwenj，因此他們可以使用WSDL相關(guān)的庫來調(diào)用你的網(wǎng)絡(luò)服務(wù)。

最后，花一些時(shí)間開開發(fā)一個(gè)最常用的網(wǎng)絡(luò)服務(wù)提供的操作的示例客戶程序。確定例子看起來真的像你所期望的客戶開發(fā)者也許會(huì)創(chuàng)建的一樣。這個(gè)參考也許會(huì)提供許多你想不到的用處－開發(fā)者可以使用這個(gè)示例來驗(yàn)證在他們的設(shè)備中獲網(wǎng)絡(luò)服務(wù)自身的某個(gè)地方是否有問題。 　　結(jié)論

為了使你的網(wǎng)絡(luò)服務(wù)能夠成功，文檔是重要的。你需要提供比使用SOAP的結(jié)束端更多的東西。使用WSDL文檔描述網(wǎng)絡(luò)服務(wù)。客戶程序開發(fā)人員可以從許多代理庫和使用不需要接觸復(fù)雜的XML和HTTP頭的結(jié)束端。WSDL在事情變壞時(shí)通過讓他們知道消息是如何構(gòu)造的來幫助他們。在這點(diǎn)上，他們需要擴(kuò)充他們對(duì)SOAP的知識(shí)。WSDL給他們提供了一張地圖來解釋為什么他們應(yīng)該查看在他們的機(jī)器和你的之間的通信。

為用戶程序開發(fā)者解釋各種各樣的操作會(huì)返回什么樣的錯(cuò)誤。這將幫助他們編寫很好的錯(cuò)誤處理代碼，因?yàn)樗麄儠?huì)指定想要什么。如果你沒有把這點(diǎn)說明，開發(fā)者或者過度處理錯(cuò)誤，這會(huì)浪費(fèi)他們的時(shí)間，或者他們沒有錯(cuò)誤可處理。沒有錯(cuò)誤處理會(huì)導(dǎo)致對(duì)網(wǎng)絡(luò)服務(wù)的不滿，而這個(gè)不滿將導(dǎo)致你的網(wǎng)絡(luò)服務(wù)不被使用。

最后，文檔如何使用各自的操作，和給出如何調(diào)用各種操作的例子。詳細(xì)描述它，并且給出診斷普通問題的信息。也要從屬地為任何調(diào)用做文檔。例如，大多數(shù)個(gè)性化服務(wù)中的操作掌握一點(diǎn)，就是調(diào)用被第一個(gè)登陸的所取得。如果你有其他依賴，你將使別人使用你的工作變得容易得多。