设计优秀API的五大规则

2013-4-11 14:05| 发布者: 红黑魂| 查看: 2072| 评论: 0|来自: CSDN

摘要: 人们在如何设计一款优秀的API上有着很强烈的意识。在互联网上有关API方面的网页和书籍有很多很多。本文我们将重点关注设计优秀API的规则。规则就是当发生任何变化时，应当遵循“最小惊奇原则”。无论你想尝试什么样 ...

违反例子1：TreeSet

在JDK中很难找到一个例子，是与本规则相违背的，但也有另外，就是TreeSet和TreeMap。他们的构造函数可以被多次重载，下面让我们来看下这些构造函数：

这两个构造函数在不同的操作行为下，返回的值也是不一样的：

SortedSet<Object> original =// [...]
  
// Preserves ordering:
new TreeSet<Object>(original);
  
// Resets ordering:
new TreeSet<Object>((Collection<Object>) original);

规则4：参数顺序一致

为了确保参数顺序的一致性，把数组类型放在第一位会给你带来很多好处：

你会注意到，在上面那个类中，把所有数组操作都放在第一位，一些其他例子：

binarySearch(Object[], Object)
copyOfRange(T[], int, int)
fill(Object[], Object)
sort(T[], Comparator<? super T>)

违反例子1：Arrays

Array是如何违反这条规则的，它在两个参数之间添加了一些可选参数，如：

依照这种方式，copyOfRange()也和fill()一样，遵循了相同的参数顺序：

如果你的API存在过分重载现象，那么你将不得不面对这些问题。

违反例子2：String

另一个例子是String类：

问题所在：

很难理解明白这两个方法之间的差异，而且可选的布尔参数排在参数列表的最前面。
很难理解每个int参数的作用，在一个方法里有过多参数。

规则5：建立返回值类型

当涉及到返回值类型时，你应该创建一致的、正规的API，下面提供一套设置规则（你可能会对下面的规则存在异议）：

当方法返回一个单独的对象，但并没有对象被发现时，应该返回null。
当方法返回多个对象，但并没有对象被发现时，应该返回空List、Set、Map、array等，而不是null。
方法应该抛异常以防万一

对于上面的1、2条，最好的实践应该是：

抛出ObjectNotFoundExceptions当没有对象被发现时
返回null代替empty Lists

违反例子1：File

File是JDK中的一个类，它违反了许多规则，其中一条就是关于返回值类型。

正确遍历文件名称（如果你做的是防御性编程）：

String[] files = file.list();
  
// You should never forget this null check!
if (files != null) {
    for (String file : files) {
        // Do things with your file
    }
}