為你的網絡服務制作文檔

申請免費試用、咨詢電話：400-8352-114

為你的網絡服務制作文檔

 
介紹

一個網絡服務的文檔需要包含許多不同的元件。首先并且是最初，它應該提供一個有計劃地描述網絡服務的網絡服務描述語言（WSDL）文件。第二，它需要提供一份寫好的文檔，來描述如何使用網絡服務。這應該包含各種項目，包括一個API參考，問題和解決技巧合用法描述。最后，這份文檔應該為所有操作提供實例代碼，最好使用所需要的最少的代碼來調用所給的方法。傳來和送走的SOAP消息的例子應該與代碼在一起。這些示例消息將幫助開發(fā)人員用不同于示例中給出的語言開發(fā)一個客戶程序。理想情況下，文檔也應該包含一個使用網絡服務的示例用戶，用源代碼完成。

在這個專欄中，我將調查為什么需要這個信息并解釋它的價值。在一些站點，如XMethods，今天可以得到的許多網絡服務都有簡單的接口，并且返回信息，就像根據(jù)郵政區(qū)碼給出的當前溫度。但是，將來商業(yè)網絡服務將有更豐富和更復雜的接口；它們將需要文檔來描述它們的使用方法。 　　

WSDL文件

當為一個網絡服務做文檔時，你必須提供一個WSDL文檔。這個文檔提供了關于網絡服務的重要信息，開發(fā)者和編程工具都需要這些信息。用一個緊湊具體的方法，這個文檔描述所有事情，包括：

·網絡服務所理解的消息和對那些消息響應的格式
　　
·服務支持的協(xié)議
　　
·把消息送到哪

所有這些信息使程序員對系統(tǒng)希望外部應用程序如何與網絡服務相互作用有一個了解。因此，WSDL是你的用戶所需要的文檔的主要部分。

記住，例子和詳述文檔對于非瑣碎的網絡服務來說總是需要的。沒有例子和詳述文檔，開發(fā)者所編的網絡服務也許不會像你打算的那樣使用服務，或者也許會遇到問題并且因為受挫而放棄。

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

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

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

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

自定義類型

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

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

＜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名稱域，它們在文檔的其他地方定義。這里要注意的重要事情是，我們有一組定義隊員的元件的名稱。復雜的類型Player 現(xiàn)在被定義了，并且可以北映射到任何不同的語言中。這種類型也指定我們怎樣才能在通信時對Player 進行序列化。如果使用在一個消息中，這個元件將像下面的樣子：

＜message name="PlayerMessage"＞

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

＜/message＞

portTypes 和Bindings

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

＜portType name="PlayerStats"＞

＜operation name="GetBattingAverage"＞

＜input message="s0:GetBattingAverageIn" /＞

＜output message="s0:GetBattingAverageOut" /＞

＜/operation＞

＜/portType＞

這個portType 也許被許多方法所支持（重新調用那個網絡服務可以通過許多協(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" /＞

＜operation name="GetBattingAverage"＞

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

＜input＞

＜soap:body use="literal" /＞

＜/input＞

＜output＞

＜soap:body use="literal" /＞

＜/output＞

＜/operation＞

＜/binding＞

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

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

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

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

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

使用文檔

你的網絡服務的文檔也應該描述了你希望人們怎樣來使用你的網絡服務。解釋錯誤將如何被返回，如何初始化使用，等等。這個信息將幫助其他人來使用你的網絡服務。除非你做一些簡單的事情，就像從股票行情自動收錄器找到股票報價，人們就需要好的文檔。

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

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

數(shù)字 描述

1002 Invalid licensee key.

1005 Invalid user name.

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

除了錯誤處理，你也會希望未網絡服務中的各種操作做文檔。這應該像其他API文檔一樣：

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

除了上面所說，在所用的通信方式（單通道，請求－響應，等等）上給出一個示例SOAP消息交換。為了感覺我們如何做這個，看一看個性化服務API參考。

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

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

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

為用戶程序開發(fā)者解釋各種各樣的操作會返回什么樣的錯誤。這將幫助他們編寫很好的錯誤處理代碼，因為他們會指定想要什么。如果你沒有把這點說明，開發(fā)者或者過度處理錯誤，這會浪費他們的時間，或者他們沒有錯誤可處理。沒有錯誤處理會導致對網絡服務的不滿，而這個不滿將導致你的網絡服務不被使用。

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