定义良好的web service接口

定义良好的web service接口
1, 接口是自说明的。2, 服务接口粒度要合适。3, 接口参数要尽量简单。4, 接口参数不应该增加客户端和服务端的耦合性。5, 要提供对接口参数和返回值的校验。6, 接口的返回值应该是简单的语言无关的。 7, 谨慎的抛出异常。8, 接口要尽量采用更新的标准。9, 要注意标准的通用性。10, 接口要测试方便。
本文同时发布在 http://osteching.com/node/1。
最近搞了两天的web service测试，对于这些web service接口感觉实在是XX，加上经常在网上看见兄弟们讨论web service相关的一些问题，觉得十分有必要对什么是比较好的web service接口有个统一的认识。今天这篇B文就来说说我眼中定义良好的web service接口是个什么鸟样子。

接口是自说明的。也 就是说，接口的名字、参数和返回值在一看之下就知道这接口大概是干什么用的。当然接口描述文档肯定是必须的，但这些描述文档的质量谁知道怎么样呢，谁有空 天天翻着文档写东西呢，又有谁会背下来呢？所以让人眼前一亮的接口命名绝对值得，这也是所有代码书会告诉你应该遵守的一条。想想看见个叫add的方法却做 multiply的悲惨生活吧，即使文档明确说了add是做multiply，是不是每次见了也都想骂人呢。

服务接口粒度要合适。web service服务接口粒度太小了，那纯粹是不考虑xml解析性能了。一般新手容易犯这毛病，简单的把类的方法暴露出来做服务接口，这样其实是把原来在 locale的调用放到了remote，除此之外几乎没有任何好处。粒度太大，会给使用着带来很多麻烦，因为在web service中，粒度很大的服务一般都需要很多参数来映射该服务各种各样的情况。

接口参数要尽量简单。那 位说了，web service是服务啊大哥，你让我就一个参数，怎么提供服务啊，你以为服务都跟查询天气预报一样简单啊，给个城市名子，回头告诉你天气情况。说实话，要 用一个接口提供一个完善的服务确实不容易。有个名词叫服务的粒度，这个粒度确实不好掌握，服务名定了之后要想让这个服务更丰满只能靠更多的参数来搞定。对 于需要数十个参数的服务接口来说，首先要想的应该是，我KAO，这个服务定义的有问题吧？让我们再来分析分析它，给它一个合适定位，给他瘦身。要是你非不 信邪发布个有三十多个参数的接口，严重建议你在发布接口之前自己拿来测试一下先。

接口参数不应该增加客户端和服务端的耦合性。兄 弟们肯定在很多地方看见过，不应该在方法参数上增加额外的耦合性这条原则。这个在web service中同样适用，甚至可以着重强调一下这一条，因为在web service中把字符串进行特别处理实在太容易了。比如作为参数的字符串对应特殊的业务规则，这么做会导致增加额外的说明文档，增加client和 server编程的负担。又或者传入sql语句，嗯，这个作为反面教材到处都在骂，我就简单点个名就好了。

要提供对接口参数和返回值的校验。严 格的来说，对接口参数和返回值的验证也应该算是web service接口声明的一部分。尤其是对document/literal的情况，要提供相应的schema以供校验之用（dtd应该处在逐渐淘汰中 了）。增加对参数和返回值的校验，有利于减少调用者的疑惑，系统接受什么样的参数，返回值什么格式都一目了然。但是这需要一个很好的权衡，否则调用者会觉 得你暴露的方法很难用，因为限制太多了。比较理想的系统应该是宽进严出的，目标用户越多越应该注意这一点。要在宽进严出和全面校验之间做好平衡确实挺难的。我的建议是，对要暴露的接口自己做测试，在测试的过程中体会这个度。一般来说如果自己感觉都不爽，那别人是绝对不会用的。

接口的返回值应该是简单的语言无关的。 看 见过很多人问如何返回ResultSet/DataSet之类的复杂类型，尤其是玩.net的人，也许是vs.net对封装DataSet提供了过于完美 的支持吧。但对于XML来说，把任何复杂对象映射到xml文档都是困难的。就好比把三维向二维投影一样，复杂性增加了可不是一点半点。在XML中说到底所 有的类型都是字符串，要想表达其他类型，就要加额外的说明。可以看看rpc/encode方式WSDL文档的complexType部分，体会下心情。

谨慎的抛出异常。可 以把web service中的异常（SOAP FAULT）对比Java的runtime exception。任何异常都应该对应系统意外，而不是业务例外。对于这点其实要具体情况具体分析。简单的可以归纳为三种情况。第一种情况是接口返回值 是简单类型，比如boolean型，就true和false两种情况，不抛出异常怎么办？选择有两种，一是抛出异常（废话！台下别扔鸡蛋，西红柿我喜欢 吃），二是改变接口，返回int用1和0对应true和false，用-1对应系统异常。第二种情况是接口返回值是复杂对象（RPC），这种情况下其实没 办法改变什么，忍一忍，抛出个简单的异常得了。注意这时候可别把异常对象再套个七八层，你不累用你接口的人也累。第三种情况是返回值是xml文档对象，这 种情况可以把xml文档定义的灵活一些，让它能够兼容正常和异常的情况。

接口要尽量采用更新的标准。如何让一次定义的接口能服务更好一点更久一点？在技术规 范上简单就两点：不超前，不落伍。超前，支持它的工具集不会太丰富，估计谁也不想弄出个看起来很美就是谁都用不了的东东；落伍，眼前所有的工具大概都支 持，不过明天就不一定了，技术发展这么快，不能把自己累死吧。尽量采用更新的标准的意思是在不落伍的基础上要有前瞻性。举个简单的例子来说，今天再采用 rpc/encode方式显得就不合时宜了，虽然它在前两年很流行，可今天都已经不提倡用了，明天说不定大家就都忘了都不用了。就算你及时更新了你的接 口，客户呢？他们一定比你更懒。嗯，说不定正好趁机换家供应商。兄弟，你就连粥都没得喝了。

要注意标准的通用性。虽 然都是一样的标准，但标准有不同的版本，而且即使对同一个版本的标准，不同的工具实现起来也还是有细微差别的。如果用户是特定的还好说，采用些工具绑定的 特性也没什么。但如果接口用户不是特定的人群，那就要注意了，在采用某一规范标准时一定要注意，不要用实现工具所特有的东西，否则很有可能造成客户的麻 烦，导致只有很少一部分客户能使用你提供的接口。多一个客户就多一分钱啊，兄弟，干嘛跟钱过不去？

接口要测试方便。测 试驱动倒不至于还，那是牛人们干得事，不过在正是发布之前测试测试自己也放心不是？方便测试的接口意味着自己麻烦少，测起来方便嘛（循环论证?）。同时这 点如果做的好，还会带来额外的好处－－客户用起来也方便。为什么？测试代码也是对接口的使用，测试方便不正说明的接口应用性强嘛。自己测试自己接口带来的 好处大概有N个，具体可以参考TDD的相关资料。

btw：写完回头一看，KAO，居然有十条，这绝不是我的本意，兄弟们自己看着取舍。