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

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

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

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

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

自定義類型

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

類型在類型模塊中列出。使用這個，你可以映射你自己的語言規(guī)范，為XSD請求自定義類型。如果一個棒球隊(duì)希望得到一個隊(duì)員的名稱、平均擊球、年平均擊球數(shù)和隊(duì)員編號，他們就應(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名稱域，它們在文檔的其他地方定義。這里要注意的重要事情是，我們有一組定義隊(duì)員的元件的名稱。復(fù)雜的類型Player 現(xiàn)在被定義了，并且可以北映射到任何不同的語言中。這種類型也指定我們怎樣才能在通信時對Player 進(jìn)行序列化。如果使用在一個消息中，這個元件將像下面的樣子：

＜message name="PlayerMessage"＞

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

＜/message＞

portTypes 和Bindings

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

＜portType name="PlayerStats"＞

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

＜input message="s0:GetBattingAverageIn" /＞

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

＜/operation＞

＜/portType＞

這個portType 也許被許多方法所支持（重新調(diào)用那個網(wǎng)絡(luò)服務(wù)可以通過許多協(xié)議，包括SOAP、HTTP GET和HTTP POST）。一個對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＞

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

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

＜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＞

這個特殊服務(wù)描述指出了相同的結(jié)束點(diǎn)，http://someIP/baseball1/baseballservice.asmx ，可以處理所有三個綁定。你也可以使用這個片斷來在不同的地方描述相同的結(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)該描述了你希望人們怎樣來使用你的網(wǎng)絡(luò)服務(wù)。解釋錯誤將如何被返回，如何初始化使用，等等。這個信息將幫助其他人來使用你的網(wǎng)絡(luò)服務(wù)。除非你做一些簡單的事情，就像從股票行情自動收錄器找到股票報(bào)價，人們就需要好的文檔。

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

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

數(shù)字 描述

1002 Invalid licensee key.

1005 Invalid user name.

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

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

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

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

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

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

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

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

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