为什么使用API？什么情况下避免使用API？

什么是API

API（Application Programming Interface）提供了对某个问题的抽象，以及客户与解决该问题的软件组件之间进行交互的方式。组件本身通常以软件类库形式分发，它们可以在多个应用程序中使用。概括地说，API定义了一些可复用的模块，使得各个模块化功能块可以嵌入到终端用户的应用程序中去。

你可以为自己、你所在机构中的其他工程师或大型开发社区编写API。它可以小到只包含一个单独的函数，也可以大到包含数以百计的类、方法、全局函数、数据类型、枚举类型和常量等。它的实现可以是私有的，也可以是开源的。有关API的一个重要的基本定义是：API是一个明确定义的接口，可以为其他软件提供特定服务。

现代应用程序通常都是基于很多API建立起来的，而这些API往往又依赖于其他API。如图1-1中示例应用程序所示，该应用程序用到了3个类库（1、2、3）的API，而这3个API中有2个又用到了另两个类库（4和5）。举例来说，浏览图片的应用程序可能会用到加载GIF图片的API，而该API本身则可能又依赖更底层的压缩或解压缩数据的API。

图字翻译：
Application Code：应用程序代码
Library：类库

图1-1 从层次化API中调用例程的应用程序。每个方框代表一个软件类库，灰色部分表示其公共接口，对于类库而言即是其API，白色部分表示隐藏在API后面的具体实现。

API开发在现代软件开发中随处可见，其目的是为某个组件的功能提供一个逻辑接口，同时隐藏该模块内部的实现细节。举例来说，我们用来读取GIF图片的API可能仅仅提供一个LoadImage()方法，后者接收一个文件名作为参数，并返回一个2维的像素数组。所有文件格式和数据压缩的细节全部隐藏在这个看似简单的接口之下。这个概念也在图1-1中进行了说明，即客户端代码只能够通过该API的公有接口访问。API公有接口如图1-1中每个方框顶部的灰色区域所示。

为什么选用C++来描述API设计

虽然有很多通用API设计方法学（可适用于任何编程语言或编程环境）可以讲，但最终都需要使用一门特定的编程语言来表述。因此了解特定语言的特征以促进规范的API设计是非常必要的。所以，本书专门使用一种语言（C++）描述API设计的问题，而非分散内容使其适用于所有语言。然而，想要使用其他语言（如Java或C#）开发API的读者仍然可以从本书中获得许多通用的深刻见解。本书的直接目标读者是编写并维护API的C++工程师，他们的API要供给其他工程师使用。

目前，C++仍是大型软件项目中使用最广泛的编程语言之一，并且日渐成为注重代码性能项目的首选语言，因此，你可以在自己应用中选用的C和C++的API种类非常多（前面我已经列出一些）。本书重点关注如何使用C++编写优秀API，并引入了丰富的源代码示例以更好地阐述这些概念。也就是说，本书会涉及一些C++特有的主题，例如模板、封装、继承、命名空间、操作符、const正确性、内存管理、STL的使用、Pimpl惯用法，等等。

另外，在本书出版期间，C++也正经历着巨大的变革。新版的C++规范处于ISO/IEC的标准化进程中。目前，多数C++编译器遵循1998年首次发布的标准，即C++98。随后的标准于2003年出版，修正了前版的几处缺陷。自那时以来，标准委员会一直致力于一个重大的新版本规范。在标准被正式批准生效并确定发布日期之前，该版本一直被非正式地称为C++0x。当你读到本书时，新的标准可能已经发布了。但是，在我编写本书的期间，它仍然被称为C++0x。

尽管如此，C++0x已经达到标准化进程的高级阶段，我们可以满怀信心地预言一些新的特性。事实上，一些主流的C++编译器已经开始实现许多建议的新特性。在API设计方面，某些新特性可以用来构建更加优雅和健壮的接口。因此，我一直努力在整本书中强调和解释C++0x中的API设计。所以，本书在未来几年中应该依然具有参考价值。

为什么使用API

在软件项目中为什么要关注API，这一问题可以从两个方面理解：(1)为什么要设计并编写API？(2)为什么要在应用中使用其他人提供的API？我将在接下来的小节中回答这两个方面的问题，并指出在项目中使用API的各种好处。

如果你正在编写供其他开发人员使用的模块，不管他们是公司里的其他工程师还是外部客户，比较明智的办法是构建API来让他们访问这些功能。这么做会带来以下好处。

更健壮的代码

• 隐藏实现。通过隐藏模块内部实现的细节，开发人员就可以在未来的某个时间自由修改模块的实现而不给用户造成重大影响。如若不然，会导致以下结果：（1）代码的更新将会受到限制；（2）用户只有重写代码才能使用新版本的程序库。如果总是让用户不停地更新软件版本，他们很可能不愿再做更新，或者干脆弃用，另外寻找不需要太多维护工作的API。因此，优秀的API设计对业务或项目成功至关重要。
• 延长寿命。随着使用时间增长，那些公开了实现细节的系统的内部代码会变得错综复杂，系统的各个部分要依赖其他部分的内部实现细节。因此，系统将会变得脆弱、死板、不可移植且粘滞性高（Martin，2000）。如此一来，公司为了改善这些代码，就不得不花费大量人力财力，甚至推倒重写。事先花工夫做好API设计，而后维护好该设计以保证一致性，软件寿命就能延长，从长远看也能节省花费。在第4章的前面部分，我们会深入讨论该问题。
• 促进模块化。API通常用来完成一项具体的任务或用例。因此，API定义了一组具有一致目的的模块化的功能集。在大量API基础之上开发的应用，其结构将降低耦合而更加模块化，每一个模块的行为都不依赖其他模块的内部细节。
• 减少代码重复。代码重复是软件工程中最恶劣的行为之一，任何时候都要避免犯此类错误。通过把所有的代码逻辑置于一个严格的接口之后，让所有客户使用这个接口，就能将程序的某种行为统一处理。这样做意味着只需更新一处代码就可以改变向所有客户提供的API的行为。这样有助于消除代码中所有重复的实现。事实上很多的API就是这样实现的，人们首先发现有重复的代码，然后制作统一的接口取代这些重复代码，于是就产生了API。这是一件好事。
• 消除硬编码负担。很多程序可能包含硬编码的值，并在整个代码中不断复制。例如，在需要写日志文件的地方就使用具体的文件名“myprogram.log”。我们可以使用API来提供这些信息，而不用在整个代码层面复制这些常量，例如，使用GetLogFilename() API调用代替硬编码的“myprogram.log”字符串。
• 易于改变实现。如果将所有的实现细节隐藏在公共接口背后，就可以在不影响任何依赖此API代码的情况下改变其内部的实现细节。例如，可以将原本使用std::string解析文件的方式变为分配、释放、再分配char*缓冲区的方式。
• 易于优化。成功隐藏了实现细节后，在优化API的性能时就不用操心更改客户端代码。例如，可以利用加设缓存的方案优化某个计算密集型的方法。之所以这样做是因为所有读写潜在数据的操作都是通过该API进行的，因此该API更确切地知道何时缓存中的结果无效并且需要重新计算结果。

代码重用

代码重用就是使用已有的软件去构建新的软件。这是现代软件开发所追求的一个神圣的目标。API提供了一种代码复用的机制。

在早期的软件开发中，有种情况很常见，即公司不得不为其制作的任一应用编写所有代码。如果某个程序需要读取GIF图片或者解析文本文件，公司不得不自己编写全部代码。如今，随着优秀的商业库和开源库的增多，重用别人已经编写过的代码变得非常简单。举例来说，如今已经有各种开源的读取图像的API和解析XML的API供人们下载和使用。这些库被世界上许多程序开发人员不断地改进和调试，同时也已经在很多其他程序中被实践检验过。

通过使用不同的组件（它们用于构建应用程序各个模块）并借助组件已发布的API相互通信，软件开发从本质上已变得更加模块化。这种做法的好处是不需要了解每个软件组件的所有细节，如同前面提到的建造房屋的比喻，可以将很多细节问题委托给专业承包商。这样能够缩减开发周期，这一方面是因为可以重用已有的代码，另一方面则因为可以将各种组件的开发计划分离，还可以让开发者把重点放在核心业务逻辑上，而不必浪费时间重新发明轮子。

然而，实现代码重用的一个障碍是，常常需要比原本计划更加通用的接口，因为其他客户可能有额外的期望和需求。因此有效的代码重用来自对软件客户的深入了解以及结合了客户和自身利益的系统设计。

C++ API和WEB

依赖第三方API的应用程序在云计算领域里越来越普遍。该领域中，Web应用越来越依赖Web服务（API）为其提供核心功能。对于Web混搭应用程序（mashup），应用程序本身有时仅仅是对多种已有服务进行再次封装，从而提供新的服务。例如，将Google地图API和本地犯罪统计数据库相结合就可以为犯罪数据提供一个基于地图的界面。

实际上，花一些时间强调C++ API设计在Web开发中的重要性是值得的。肤浅的分析可能得出这样的结论：服务器端的Web开发局限于脚本语言，诸如PHP、Perl、Python（即流行的LAMP架构缩写中的“P”），或者基于Microsoft ASP（动态服务器页面）技术的.Net语言。对于小规模的Web开发可能确实如此，然而值得注意的是，许多大规模的Web服务器都使用C++实现的后台服务，以求最佳性能。

事实上，Facebook开发过一个名为HipHop的产品，它将PHP代码转换为C++，以此改善社交网站的性能。因此C++ API设计在可扩展的Web服务开发中确实占有一席之地。此外，使用C++开发核心API不仅可以构建高性能的Web服务，而且这些代码还可以在诸如桌面或移动电话版本等其他形式交付的产品中重用。

说句题外话，对于这种软件开发策略的转变，一种可能的解释是全球化推动的结果（Friedman，2008；Wolf， 2004）。实际上，互联网、标准网络协议和Web技术的汇聚已经创造了一个软件竞技平台。这使得来自世界各地的公司和个人都可以在大型复杂软件项目中进行创造、贡献和竞争。这种形式的全球化促成了一种环境，在该环境下，全世界的公司和开发者能够以开发软件子系统为生。世界各地的其他组织进而可以通过组合与扩展这些构建模块创建解决特定问题的最终用户应用程序。就本书讨论的焦点而言，API提供了促成现代软件开发全球化和组件化的机制。

并行开发

即使你只是编写内部软件，与你共事的工程师也很可能要使用你的代码编辑程序。如果使用良好的API设计技巧，就可以简化彼此的工作，不必回答诸多关于代码如何工作、如何使用的问题。这在多个开发者并行开发相互依赖的代码时显得尤为重要。

举例来说，假设你正在编写一个字符串加密算法，其他开发者需要使用该算法将数据写入配置文件。一种做法是让其他开发者等你完成所有工作，然后在其文件输出模块中使用你的算法。然而，更有效率的做法是，你们提前见面协商好恰当的API，然后你把API放在适当的位置，而API仅仅起占位符的作用，这样你的同事就可以立即调用它们了，例如：

#include  classStringEncryptor { public: ///设置Encrypt()和Decrypt()调用时使用的密钥 voidSetKey(conststd::string &key); ///基于当前密钥加密输入字符串 std::string Encrypt(conststd::string &str) const; ///基于当前密钥解密输入字符串 /// Decrypt()一个由Encrypt()返回的字符串 /// 返回同一个密钥下原始的字符串 std::string Decrypt(conststd::string &str) const; };

接着，你可以提供这些函数的简单实现，使得该模块至少可以编译和链接。例如，相关的.cpp文件可以像下面这样：

voidStringEncryptor::SetKey(conststd::string &key) { } std::string StringEncryptor::Encrypt(conststd::string &str) { return str; } std::string StringEncryptor::Decrypt(conststd::string &str) { return str; }

这样一来，你的同事就能够使用这个API继续工作而不被你的进度所耽搁。虽然目前你的API实际上不会加密任何字符串，但是这只是一个小的实现细节。重要的是已经有了一个双方都认可的稳定接口，即一个契约，而且该接口的行为恰当，例如Decrypt(Encrypt("Hello"))将会返回“Hello”。当你完成了工作，并以正确的实现更新了.cpp文件后，你同事的那部分代码不需要进行任何修改就能直接运行了。

实际上，有些接口问题很可能在编写代码之前并没有预料到，因此API设计可能需要多次迭代才能保证其恰到好处。在大多数情况下，API支持双方能够以最少的停顿并行工作。

这种方法还用利于测试驱动或者是测试先行的开发。事先确定了API，就可以编写单元测试来验证预期的功能，并且可以持续运行这些测试程序，以保证始终没有打破你和同事之间的协议。

将该过程延伸到组织层面，你的项目可以有独立的团队，他们彼此也许相距很远，甚至遵循不同的日程安排。通过预先确定各个团队的依赖关系，并通过创建API来为这些关系建模，各个团队就可以独立工作，而几乎不必关心其他团队如何实现API背后的工作。资源的有效利用以及削减相应的冗余通信，能够为组织节约大量整体成本。

何时应当避免使用API

设计并实现API相比编写普通的应用程序代码通常要花费更多精力，因为API的宗旨是提供健壮、稳定的接口供其他开发人员使用。因此，与仅在单一应用程序内部使用的软件相比，API在质量、设计、文档编写、测试、支持及维护方面有更高的要求。

因此，如果编写的是不需要和其他客户端通信的内部模块，那么为模块创建并维护稳定公有接口的额外开销就不值得了，然而这并不是编写劣质代码的理由。为坚持API设计原则而多花费些时间，从长远看来并不浪费时间和精力。

另一方面，假设你是一位想在应用程序中使用第三方API的软件开发人员。前一节讨论了在软件中重用外部API的一些理由，但有时也可能需要避免使用特定的API，在如下这些情况下，你应该花精力自己实现代码或寻找替代的解决方案。

• 许可证限制。虽然API可以提供所需的各项精巧功能，但是许可证限制可能让你望而却步。例如，如果你想使用GNU GPL（General Public License，通用公共许可证）发布的开源包，那么就必须使用GPL发布所有衍生作品。如果在程序中使用这个包，就必须发布整个应用程序的源代码，这是商业应用可能不会接受的约束。其他的许可证（如GNU Lesser General License GPL，LGPL）就更加宽松些，在软件库中也更加常见。许可证问题的另一种体现是：商业API的费用对你的项目来说可能过于昂贵，或者许可条款可能过于严格，比如要求向每位开发者甚至每位用户收取许可费用。
• 功能不匹配。虽然API看似能够解决所面临的问题，但是它有可能以一种与应用程序约束或功能需求不匹配的方式执行。例如，可能你正在开发一个图像处理工具，想要提供傅里叶变换功能。虽然有许多现成的FFT（Fast Fourier Transform，快速傅里叶变换）的实现，但是其中大多数是1D算法，而处理2D图像数据需要使用2D FFT。此外，许多2D FFT算法只能在大小是2的整数幂的数据集上工作（如256×256或512 × 512）。或许你找到的API不能在必须支持的平台上运行，或者它不能满足你对程序制定的性能标准。
• 缺少源代码。虽然有许多开源API，但是有时符合要求的最佳API可能是闭源产品。也就是说，只提供接口的头文件，而背后的C++源文件并不同库一起发布。这有几项重要的影响，其中之一就是当库中存在错误时，不能通过检查源代码的方式定位问题。对于跟踪错误进而找到解决方案来说，阅读源代码是一个很重要的方法。
  进一步说，不能访问API的源代码就丧失了通过修改源代码修复错误的能力。这意味着软件项目的进度可能会受到所使用的第三方API中不可预期问题的不利影响，并且需要等待该API的所有者处理你的错误报告并发布修复补丁。
• 缺乏文档。虽然API看似可以完全满足应用程序的需求，但是如果API的文档编写拙劣或根本没有文档，那么你最好再去寻找别的解决方案。在这种情况下，有可能是API的用法不清楚影响了它的使用，也有可能是你无法确定特定情况下API的行为，甚至可能是你根本无法信任那些连花点儿时间解释代码都做不到的开发者。

本文摘自《C++ API设计》