接口API设计的艺术

转自：http://www.iteye.com/topic/1128913

 

最近在设计一些基础平台的API，在设计过程中总结了一些经验，记录如下：

 

1、方法参数不要多。

特别是同一种数据类型的方法参数不要过多，一旦过多，调用者容易搞混顺序，搞混了顺序，在编程阶段不会报错，但是在运行时会出错。并且这种错误时不宜排查的。

 

2、如果方法参数超过4个，若超过则适合使用参数类进行封装。

人的记忆一般适合于4个参数左右，参数多了不利于掌握。

 

3、谨慎使用重载，可以使用覆盖。

重载是动态类型的，执行时才会知道到底哪个方法被执行了，覆盖则是静态类型的，一旦调用者的类型确定了，执行哪个方法就确定了。所以重载更容易造成一些你意向不到的Bug。

 

4、方法名称不宜过长，建议使用驼峰式。

在这个快餐时代，简练的东西都像迷你裙一样受欢迎。注意是简练，不是说越短约好，还得让人知道是什么。尽量使用领域内的专业术语。

 

5、方法个数不宜过多。

特别是在同一个类中的方法，容易让使用者不知道使用哪个方法合适，并且不利于维护。如果不是非得需要，不要增加一些你臆想中的方法，方法应该像正交坐标系一样。

 

6、方法签名中参数尽量使用接口，不要使用具体类。

使用接口利于扩展，使用具体类限制了使用的客户端。

 

7、要对输入参数进行校验。

要控制住输入，“用户输入的都是对的”是不靠谱的，如果等到某个关键地方因为参数错误而抛出异常，会造成查bug非常困难，这种校验工作迟早是要还的。

 

8、必要时对于输入的参数进行拷贝。

Java中对数是引用，所以传入的参数很可能在外部被修改的，这种情况下即时通过了校验，也可能会出现问题。所以为了方法的健壮性，请使用拷贝。除非，你认为客户端会注意安全的调用你的方法。注意，非final类的clone方法不一定是可靠的。

 

9、站在使用者角度写写单元测试用例。

使用API是个逆过程，这个逆过程不一定好受。特别是序列化的时候，序列化容易，反序列化不一定容易。

 

10、维护好JavaDoc

都有为开源项目垃圾的JavaDoc吐槽的时候，既然不想遭遇同样的命运，就维护好的JavaDoc。今天还看到Jsoup本次升级中修改了JavaDoc的一个bug。