最近搞了两天的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,居然有十条,这绝不是我的本意,兄弟们自己看着取舍。