首页手记浅谈如何设计API（二）

浅谈如何设计API（二）

标签：

设计

API设计的一些原则
3.1 只公开必须的内容

在编写API时，肯定会有这样一种思考方式：是不是要多加一个参数呢？可能会有这种用法吧？参数要不要做到很灵活呢？接收一个Object数组吧（而且是不带泛型的）。。。有这样的想法能说明我们在设计API的时候思考了很多，但是这么实现的API是要命的、坑人的。

那么我们应该怎么做呢？精简、明确、直接。只公开必要的内容，不要为了“以后可能会有”而大伤脑筋，考虑未来的扩展固然是好事，但凡事总要有个度，过犹不及。
3.2 面向接口编程

面向接口编程，在一些面向对象语言中提及的比较多（比如java）。面向接口编程，就是在参数的传递和返回使用接口而不是实现类，这样可以方便的替换实现方，从而达到程序容易扩展、实现更加灵活的目的。

比如我们在设计一个API的时候，传入参数使用接口Map就会比使用具体的类如HashMap、TreeMap更加灵活。比如JDBC，我们使用的都是Connection、ResultSet这样的一些接口，具体的实现则由数据库厂商提供，MySql、Oracle等厂商都提供了JDBC的实现。
3.3 方法重载

方法重载在很多API、SDK中有着广泛的使用，之所有使用重载是因为它为程序实现带来了极大的便利。一个明显的例子是：在不同的地方做相同或类似的事情，重载这种方式的优越性就凸显出来了。我们看下面的例子：
在JDK的java.util包下的Collections类有两个个排序的静态方法：
sort(List<T> list)；
sort(List<T> list, Comparator<? super T> c);

同样的方法名不会让人疑惑，参数的丰富让人一眼就能看到重载方法的区别以及自己该调用哪个。
3.4 返回值

当API具有返回值时，应该在一组（或同一种类）的API中使用同样规则的返回值。
下面提供一种参考方式：如返回的结果是单个对象，当没有找到符合条件的结果时，应返回null；如果返回值是List、Map或数组，那么应该返回空的Lisp、Map、数组，而不是null。
上面的方式不一定是适合所有场景的，也可以使用另外的一种通用规则替代，比如当查询不到符合条件的数据时抛出异常，这也是一种通用的方式，具体使用哪种，根据实际情况而定。