为网络服务制作文档

　　WSDL文档可以定义消息所使用的类型。当定义自定义类型时，你应该使用XSD来代替其他类型定义语言。使用XSD允许你更简单地使用WSDL相关的工具箱。这也帮助那些也许必须手工生成定制客户的人。但是，如果你看到需要定义呢自己的类型系统，你也许会－但是我不推荐。

　　类型在类型模块中列出。使用这个，你可以映射你自己的语言规范，为XSD请求自定义类型。如果一个棒球队希望得到一个队员的名称、平均击球、年平均击球数和队员编号，他们就应该按下面的类型定义来定义：

　　这里使用了一些XML名称域，它们在文档的其他地方定义。这里要注意的重要事情是，我们有一组定义队员的元件的名称。复杂的类型Player 现在被定义了，并且可以北映射到任何不同的语言中。这种类型也指定我们怎样才能在通信时对Player 进行序列化。如果使用在一个消息中，这个元件将像下面的样子：

　　WSDL也可以既对一个给定的portType 上的操作又为详细绑定的数据创建文档。相关的操作应该存在于一个给定的portType 中。这些操作间的关系代表性地用实现它们的语言片断定义。例如，如果一个COM对象和Java类给出5个方法作为网络服务，这5个方法一起来定义portType 。每个portType 都有一个匹配的binding 元件。这个binding 元件可以被用来定义portType中的每个operation 如何映射到特殊的协议中。你也许有一个按照下面定义的portType ：

　　这个portType 也许被许多方法所支持（重新调用那个网络服务可以通过许多协议，包括SOAP、HTTP GET和HTTP POST）。一个对SOAP的binding 也许像这样：

　　这个binding 元件表明这个操作将在HTTP上使用SOAP来传输。GetBattingAverage 操作使用HTTP SOAPAction 头，http://www.seattlemariners.org/GetBattingAverage 。这个操作是面向文档的并且使用文字编码。

　　我们也可以定义特定服务的结束点在哪。如果这个结束点可以通过一些不同的绑定来达到，例如SOAP，HTTP GET和HTTP POST，这个服务片断就会像这样：

　　这个特殊服务描述指出了相同的结束点，http://someIP/baseball1/baseballservice.asmx ，可以处理所有三个绑定。你也可以使用这个片断来在不同的地方描述相同的结束点。

　　使用文档

　　你的网络服务的文档也应该描述了你希望人们怎样来使用你的网络服务。解释错误将如何被返回，如何初始化使用，等等。这个信息将帮助其他人来使用你的网络服务。除非你做一些简单的事情，就像从股票行情自动收录器找到股票报价，人们就需要好的文档。

　　首先，包含一个总结文档。一个好的总结包括指出兵总结与网络服务相关的文档－WSDL位置，开发者指导，API参考等等。在开发者指导中，解释如何使用网络服务。描述典型使用情况，也描述错误处理。

　　当描述错误处理时，列出每个网络服务方法可能返回的错误。给出返回代码，这样客户程序开发者就可以查询错误代码，然后用显示消息和记录条目的方法把相应意义的消息提供给它们的最终用户。对于个性化服务，我们有一节文档来解释如何处理错误；它也提供了通常对如何处理SOAP错误的总结。然后我们指出如何发现错误代码和错误描述。我们通过提供一个指定什么样的错误存在和这些数字意味着什么地表格来在方法描述中找到这些。例如，我们写道GetFavorite 调用可以返回下面的错误：

　　数字 描述
　　1002 Invalid licensee key.
　　1005 Invalid user name.

　　作为替代在一个方法接一个方法的基础上列出错误，你也可以做一个所有网络服务可能会返回的所有错误的列表。但是，这样做的困难在于，客户程序开发者将不指定会从各种各样的代码片断返回什么样的错误。这使得编写错误处理程序对他们来说变得困难，但是却使你的文档更容易创建和保存。我们确定我们最好去做这困难的工作，而不是让开发人员通过反复试验来学习他们必须处理的错误。这要以被大多数windows API文档使用的模型为基础，在那里每个函数都列出了它们也许会返回的错误。

　　除了错误处理，你也会希望未网络服务中的各种操作做文档。这应该像其他API文档一样：

　　·解释操作做什么
　　·定义操作的参数的意义和类型
　　·提供示例代码
　　·给出帮助提示

　　除了上面所说，在所用的通信方式（单通道，请求－响应，等等）上给出一个示例SOAP消息交换。为了感觉我们如何做这个，看一看个性化服务API参考。

　　你也许还希望花一些时间来定义对象或用WSDL的说法，portType 。也就是描述函数的收集并且给出用户可以从哪里找到这个WSDL文件的指针。用户程序开发人员会希望得到WSDLwenj，因此他们可以使用WSDL相关的库来调用你的网络服务。

　　最后，花一些时间开开发一个最常用的网络服务提供的操作的示例客户程序。确定例子看起来真的像你所期望的客户开发者也许会创建的一样。这个参考也许会提供许多你想不到的用处－开发者可以使用这个示例来验证在他们的设备中获网络服务自身的某个地方是否有问题。

　　结论

　　为了使你的网络服务能够成功，文档是重要的。你需要提供比使用SOAP的结束端更多的东西。使用WSDL文档描述网络服务。客户程序开发人员可以从许多代理库和使用不需要接触复杂的XML和HTTP头的结束端。WSDL在事情变坏时通过让他们知道消息是如何构造的来帮助他们。在这点上，他们需要扩充他们对SOAP的知识。WSDL给他们提供了一张地图来解释为什么他们应该查看在他们的机器和你的之间的通信。

　　为用户程序开发者解释各种各样的操作会返回什么样的错误。这将帮助他们编写很好的错误处理代码，因为他们会指定想要什么。如果你没有把这点说明，开发者或者过度处理错误，这会浪费他们的时间，或者他们没有错误可处理。没有错误处理会导致对网络服务的不满，而这个不满将导致你的网络服务不被使用。
最后，文档如何使用各自的操作，和给出如何调用各种操作的例子。详细描述它，并且给出诊断普通问题的信息。也要从属地为任何调用做文档。例如，大多数个性化服务中的操作掌握一点，就是调用被第一个登陆的所取得。如果你有其他依赖，你将使别人使用你的工作变得容易得多。

　　下一个专栏中，一个客人将写一篇关于即将到来的Project Lucy 的文章。

查看本文来源