API（模块）设计之道（一）

原文地址：How To Design a (module) API 

翻译：Ai92     http://blog.csdn.net/ai92

为什么需要API？

API是应用程序设计接口（Application Programming Interface）的缩写，在我们对如何编写API进行深入描述并给出建议之前，有必要来分析下这个术语的含义。

 

单词interface表示API存在于至少两个不同的主题（subjects）之间。例如应用程序的内部结构对一方面来说是可见的，而前端应用程序则从另一方面来调用它的。换句话说，程序员（或者团队）在一方面开发应用程序和它的API，而其它的程序员们则从另一方面使用这个应用程序。对于这两个例子都具有着一个重要的特征，这两方面是分离的——独立编译抑或由进度，目标和需求完全不同的团队分别开发。

 

这种分离正好意味着设计和维护API需要一组规则。如果应用程序不存在分离的情况，整个产品由一个紧密协作的团队开发构建，那就没必要为编写API而烦恼（它的确耗费很多工作精力），也没有必要撰写这篇指南了。但是现实中的软件产品是由许多独立的工程组成的，而这些工程的开发团队根本不需要彼此认识，他们有着完全不同的进度并且独自构建着他们的工程。然而这些团队之间也需要通信（communicate），因此在通信中需要使用稳定的契约。

 

例子：Linux是由Mandrake或者RedHat发行的，但是系统的内容是由数以千计的独立开源工程组成的。发行商们不能干涉他们的工作，仅仅需要知道在给定的时间内能够得到什么样的稳定工程，并保证顺利集成和释放新版本。

什么是API？

为什么使用API的理由就是允许团队之间、应用程序之间进行通信，以便进行分离式（seprated）和分布式（distributed）的开发。那“什么是API”的答案将包括能影响这种开发方式的所有东西。

 

API就是其它团队或者应用程序可以依赖的一切：

 

l         方法与域——应用程序间的通信通常是表现为调用函数和传递数据结构。如果方法名称，方法参数或者传递的数据结构发生了变化，则整个程序不能运行，甚至不能正常地连接。

l         文件及其内容——许多应用程序需要读取不同种类的文件，而这些文件的内容影响着应用程序的行为。设想在调用某个应用程序之前，依赖另一个应用程序读取它的配置文件并修改其内容。如果文件的格式发生了变化或者文件的存在被彻底的忽略了，则应用程序之间的通信就断掉了。

l         环境变量——例如cvscan的行为受到变量CVSEDITOR的影响。

l         协议——例如打开套接字（socket）准备解析到来的数据流，或者读取数据到剪切板（clipboard）或者在反复的拖放（drag and drop）之间形成其它应用程序可依赖的API。

l         行为——动态行为稍微难以把握，但是对于分离来说非常重要。程序流（program flow）会是什么样子——执行的目的是什么，在调用期间那些需要锁定，调用发生在哪一个线程里面等等。

l         本地化（L10N）信息——由于将应用程序本地化为某种语言的开发人员并不是编写代码的人员，可是他们都需要使用相同的关键字（NbBundle.getMessage ("CTL_SomeKey")），代码编写者与翻译者之间需要有着固有的契约——一组API。

 

就分布式开发（distributed development）而言，重要的事情是知道可能存在的API——其它代码可以依赖使用。只有识别出其它应用程序要依赖自身应用程序的这一方面，才不会破坏独立开发的应用程序之间的协作。

面向用例设计的重要性

通常判断一个程序的好坏并不难——如果没有作任何有用的工作就崩溃了，这就是坏的。甚至程序都不能编译，那就更差了。但是如果它能运行，并且帮助完成了某些工作，仅在某些时候会崩溃，那它不能算是好的，但是也不能算是完全坏的。衡量的标准依赖于评估时的感觉。主观感觉在其中起着作用。这同样适用于评价一个设计的好坏。不管它是一个UI设计还是API设计。个人感觉是很重要的。

 

另一方面软件工程是（至少应该是）由工程师们实施的，而软件工程最重要的部分是它的可度量性。所以设计的最终理想就是使其可测量，消除主观影响并定义一系列规则来度量设计的质量。当然，定义的规则需要一些个人观点，但是一旦规则被拟定，他就能从工程师的角度用科学的方法来测量对规则的满意度。

 

但是就像上面判断程序好坏的例子所显示的那样，用户的主观感觉是很重要的。同样在设计中也是如此。对代表着应用程序内部结构及其功能列表之间接口的API来说，有主观感觉的人就是使用它的程序员。程序员就是API的用户。他将对设计作出评价，而这将代表设计的好坏。当然这些完全是个人意见，是源于在学习设计和使用API过程中获得的经验。API越易于使用，用户对于设计的感觉越好。

 

外部程序（external programmer）关心学习API的时间，完成工作需要编写的代码行数和契约的稳定性。编写API的艺术在于满足这些对应需求。

 

一般程序需要向更多的用户、更高的效率进行优化。使用API的人员要远远多于其开发人员，这就是为什么我们应该特别关心简化用户使用的难度。如果满足了大多数用户简单的使用，那么应用程序的实现稍有点复杂也是可以接受的。为了更好的满足用户的要求，那么就必须更好的知道和理解他们的需求。如果对普通的任务，API可以简单实现，那么它就是好的API。

 

这就是为什么API设计的初始步骤是调查和搜集应用程序潜在用户的情况（scenarios）。编写这些用例为API各方面的评估以及设计的有效性提供了可能。用例充当了验证API设计的定点（fixed point）。判断设计的质量事实上是不可能的，但是判断设计是否满足用例需求与否却相对容易得多。

 

    一旦用例被支持，那么就必须坚持到最后（例如，直到没有人再对它感兴趣）。