`

定义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的相关资料。
分享到:
评论

相关推荐

Global site tag (gtag.js) - Google Analytics