定义web service接口的十点注意事项

文/juleven  出处/blogjava

一、接口是自说明的。
也就是说，接口的名字、参数和返回值在一看之下就知道这接口大概是干什么用的。当然接口描述文档肯定是必须的，但这些描述文档的质量谁知道怎么样呢，谁有空天天翻着文档写东西呢，又有谁会背下来呢？所以让人眼前一亮的接口命名绝对值得，这也是所有代码书会告诉你应该遵守的一条。想想看见个叫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的相关资料。