设计优秀API的五大规则

人们在如何设计一款优秀的API上有着很强烈的意识。在互联网上有关API方面的网页和书籍有很多很多。本文我们将重点关注设计优秀API的规则。

规则就是当发生任何变化时，应当遵循“最小惊奇原则”。无论你想尝试什么样的个人风格或者品味，你都可以添加到API中，因此，这是优秀的API理应具备的特性之一。

设计“正规”API理应注意的几件事情：

规则1：建立强有力的条款

随着API的不断增长，这些条款会被重复使用。例如，这些行为会导致各种类/类型/方法（classes/types/methods）产生不同微妙的行为。

事实上，他们看起来很相似，需要通过命名来区分。以JDBC为例，无论你执行哪条语句，你都需要使用它们来执行。比如，你可以调用这些方法：

• execute(String)
• executeBatch()
• executeQuery(String)
• executeUpdate(String)

与之类似，无论你发布哪些资源，你都经常使用条款，比如，你会调用：

• Connection.close()
• Statement.close()
• ResultSet.close()

事实上，close在JDK中是一款强大的且已被确立的条款，这就导致java.io.Closeable (since Java 1.5)与java.lang.AutoCloseable (since Java 1.7)接口建立了释放资源约定。

违反例子1：Observable

这条规则违反了JDK中的一组条款，比如java.util.Observable 类。当其他“Collection-like”类型成立条款时： 

• size()
• remove()
• removeAll()

该类声明

• countObservers()
• deleteObserver(Observer)
• deleteObservers()

同样适用于Observer.update()，实则应称为notify()，JDK API里的另一个术语。

违反例子2：Spring. 

目前，Spring已得到了普及，很多Java项目都使用Spring框架，那么Spring又是如何违反这条规则的呢？

• AbstractBeanFactoryBasedTargetSourceCreator
• AbstractInterceptorDrivenBeanDefinitionDecorator
• AbstractRefreshablePortletApplicationContext
• AspectJAdviceParameterNameDiscoverer
• BeanFactoryTransactionAttributeSourceAdvisor
• ClassPathScanningCandidateComponentProvider
• J2eeBasedPreAuthenticatedWebAuthenticationDetailsSource.

下面进行客观点的分析：

• Creator和Factory之间有何区别？
• Source和Provider之间又有何区别？
• Source和Provider非微妙的差异是什么？
• Discoverer和Provider非微妙的差异是什么？
•  Advisor和AspectJAdvice有关联吗？
• ScanningCandidate还是CandidateComponent？
• TargetSource是什么？它与SourceSource区别是什么？SourceSourceTargetProviderSource与SourceTarget之间有何差别？

规则2：在组合上运用对称

一旦你创建强有力的条款，你会开始将他们结合起来。当你看到JDK收集APIS，你会注意到它们以对称的方式创建条款add()、remove()、contains()等等，在将其结合之前：

• add(E)
• addAll(Collection<? extends E>)
• remove(Object)
• removeAll(Collection<?>)
• contains(Object)
• containsAll(Collection<?>)

现在，Collection类型就是个很好的例子，当规则发生异常时，这个方法便不适用了。这可能是因为在retainAll(Collection<?>)情况下，不使用equivalent retain(E) 方法。

规则3：使用重载

人们之所以使用方法重载，主要是因为它给程序带来了许多方便。你经常希望在不同的地方做相同的事情，但每次去构造方法又很繁琐，那怎么办？你只需为API用户在相同的方法里提供额外的变量，并且把参数类型设置成友好型（friend）。下面以Collection为例：

• toArray()
• toArray(T[])

另外一个是Arrays utility类：

• copyOf(T[], int)
• copyOf(boolean[], int)
• copyOf(int[], int)

使用重载的两大原因：

1.  提供“default”参数行为，正如Collection.toArray()

2.  支持一些不兼容的“相似”参数设置，如 Arrays.copyOf()