前言

编写大型C++(www.cppentry.com)应用既复杂又棘手，设计健壮、稳定、易用且耐用的可重用C++(www.cppentry.com)接口更是难上加难。在这些努力中获得成功的最佳途径就是遵循优秀的应用编程(www.cppentry.com)接口（Application Programming Interface，API）设计原则。

API为软件组件提供逻辑接口，同时又隐藏实现该组件所需要的内部细节。它提供模块的高层次抽象，并通过多个应用共享相同的功能，以促成代码复用。

现代软件开发高度依赖于API，从底层应用程序框架到数据格式API，以及图形用户界面（GUI）框架。事实上，常见的软件工程术语，诸如模块化开发、代码复用、组件化、动态链接库（DLL）、软件框架、分布式计算以及面向服务的架构（SOA），都隐含了对高超的API设计技能的需求。

你也许了解一些流行的C和C++(www.cppentry.com) API，比如标准模板库（STL）、Boost、微软Windows API（Win32）、微软基础类库（MFC）、libtiff、libpng、zlib、libxml++、OpenGL、MySQL++、奇趣公司的Qt、wxWidget、GTK+、KDE、SkypeKit、POSIX pthreads、英特尔的线程构建模块（Threading Building Blocks）、Netscape插件API以及Apache模块API。除此之外，Google的许多开源项目也使用C++(www.cppentry.com)，在sourceforge.net、bitbucket.org和freshmeat.net网站上也有很多开源的C++(www.cppentry.com)代码。

在软件开发中，从桌面程序到移动计算和嵌入式系统，再到Web开发，都能见到上述API的踪影。例如，Mozilla Firefox网页浏览器就是在80多个动态库的基础上构建的，其中每一个动态库都提供了若干个API的实现。

因此，优雅而健壮的API设计对现代软件开发至关重要。它区别于标准应用程序开发的一个重要特征，就是对变更管理的巨大需求。众所周知，在软件开发中，变化是一个不可避免的因素。新的需求、功能要求以及错误修复，这些要求导致软件从最初的设计以来要经历一系列从未预料的演变。然而，若API由数百个最终用户应用程序共享，那么变化就将引发巨大的动荡，并最终可能致使客户抛弃该API。因此，良好的API设计的首要目标是：在为客户提供所需功能的前提下，使新发布的API对客户代码造成的影响最小，理想状况下应该是零影响。

本书的价值

如果有其他软件工程人员需要依赖你所编写的C++(www.cppentry.com)代码，那么你就是API的设计者，本书就是为你而编写的。

接口是你编写的最重要的代码，因为如果接口出现问题，那么修复它的代价比修复实现部分的代价要高很多。举例来说，接口的变化要求对所有依赖此接口代码的应用进行更新，相比之下，当客户端应用采用新版本的API时，仅略微更改的实现则可以被透明地、毫不费力地集成。从经济的角度看，设计拙劣的接口会极大缩短代码的生存期。因此，写出高质量的接口是一项必备的工程技能，也是本书的焦点所在。

Michi Henning曾指出，如今API设计比起20年前显得更为重要。因为近年来有更多的API被设计出来，这些API提供更为丰富和复杂的功能，并且被更多的最终用户应用所共享（Henning, 2009）。尽管如此，当前市面上着重介绍C++(www.cppentry.com) API设计的书籍却不多。

需要指出的是，本书并不是一般的C++(www.cppentry.com)编程(www.cppentry.com)指南--市面上这类优秀书籍已经有很多本了。本书当然会涵盖许多面向对象的设计材料并提供很多有用的C++(www.cppentry.com)技巧和窍门，但更侧重清晰地描述C++(www.cppentry.com)中模块接口的技巧。因此，我不会深入讨论如何实现接口背后代码的问题，诸如具体的算法选择，或是应用于函数体花括号内代码的最佳实践。

然而，本书将涵盖API开发的整个领域，从最初设计到实现、测试、文档编写、发布、版本控制、维护以及最终弃用。我还会讨论一些特殊的API主题，如创建脚本化API和插件式API。虽然总体上许多主题也和软件开发相关，但这里着重强调API设计。举例来说，当讨论到测试策略时，我将重点介绍自动化的API测试技术，而不会试图囊括最终用户应用的测试技术，如GUI测试、系统测试或人工测试。

我曾领导过若干由多个合作机构共享的研究性代码的API开发，还有奥斯卡获奖影片所使用的内部动画系统API，以及全球上百万用户所使用的开源客户端、服务器API等。本书的内容正是基于以上这些实际经验的，正是这些实践让我明白，高质量API设计是成功的关键所在。因此，本书旨在提供工业强度的API设计技术与策略的实践精华，它们均源自一系列实践经验。

本书读者对象

虽然本书不是C++(www.cppentry.com)初学者的指南，我还是竭尽全力使文字更通俗易懂，并且清楚地解释所有的术语和行话。因此，无论你是想提高设计技能掌握C++(www.cppentry.com)基础的新手程序员，还是想获得新的专业技能以完善已有才能的高级工程师和软件架构师，本书都具备一定的参考价值。

在写作本书时，我拟定了3类特定的读者群体。

在职软件工程师和架构师。正在从事特定API项目的初级和高级开发人员，需要一些如何构建优雅且持久设计的实用建议。

技术经理。负责开发API产品的开发经理，以及想深入理解API设计的开发过程和技术问题的产品经理。

学生和教学人员。计算机科学和软件工程专业的学生，正在学习如何编程(www.cppentry.com)，或者正在寻找总结了全面、大型项目实践经验的软件设计资料的学生。

为什么选用C++(www.cppentry.com)来描述API设计

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

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

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

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

术语及排版规约

传统上，我们使用术语"用户"（user）表示使用软件应用的人，比如Microsoft Word或者Mozilla Firefox的用户。而在本书所指的API 设计背景下，此术语表示借助API创建应用的软件开发人员。换言之，本书通常提到的是API用户并不代表应用程序用户。与此同时，术语"客户"（client）在这一点上也具有相同的语义。注意术语"客户"除了指代使用API的人之外，还表示调用API函数的其他软件。

虽然有许多文件格式后缀可以用来标识C++(www.cppentry.com)源文件和头文件，如.cpp、.cc、.cxx、.h、.hh和.hpp，但本书将统一使用.cpp和.h。本书会交替使用术语"模块"（module）和"组件"（component）表示一对.cpp和.h文件。很明显它们不等价于一个类，因为一个组件或模块可能包含多个类。本书使用术语"库"（library）表示一个物理集合，即组件形成的包。也就是说，库＞模块/组件＞类。

面向对象编程(www.cppentry.com)社区经常使用的术语"方法"（method）并不是严格的C++(www.cppentry.com)术语，它源自Smalltalk语言。在C++(www.cppentry.com)中与之等价的术语是成员函数（member function），但是也有一些软件工程师喜欢使用更为具体的虚成员函数（virtual member function）。本书并不特别关注这些术语的微小差别，故将交替使用方法和成员函数。同样，虽然在C++(www.cppentry.com)中，数据成员（data member）是更准确的表述，但是本书将术语"成员变量"（member variable）视为它的同义词。

考虑到印刷习惯，本书使用等宽字体编排所有源代码示例以及正文中出现的所有关键字。在本书给出的示例中，我习惯使用大写驼峰式命名法（upper camel case）书写所有类和函数的名字，即使用CamelCase而非camelCase或snake_case。不过，我会保留引用的外部代码的大小写形式，如std::for_each()。本书遵循在数据成员名前添加m前缀以及在静态变量前添加s前缀的习惯约定，如mMemberVar、sStaticVar。

应当指出，书中的源代码往往只是代码片段而并非功能完整的样例。我还会省略示例代码中的注释。这样做是为了简洁和清晰。特别地，我经常会省略头文件前后防止重复引用的预处理警戒语句。本书认定读者都已清楚C/C++(www.cppentry.com)头文件需要将所有内容包含在预处理警戒语句 （preprocessor guard）中，并且最好将所有的API声明都包含在统一的命名空间下（见第3章和第6章）。换言之，本书假定给出的每个头文件都默认包含如下代码：

#ifndef MY_MODULE_H  
#define MY_MODULE_H  
 
//需要#include的文件……  
 
namespace apibook{  
 
//API声明……  
 
}  
 
#endif 

提示
 
本书中，我也会强调各种有关API设计的小提示和关键概念。提供这些标注是为了让你能够快速搜索到想要重读的概念。如果你的时间非常有限，可以只浏览书中的这些小提示，然后阅读提示附近的内容以深入理解你最感兴趣的主题。 

本书的网站

本书也有一个支持网站：http://APIBook.com/。该网站提供了本书的全部信息以及一些辅助资料，如书中示例的完整源代码。读者可以随意下载并使用这些样例。样例设计得尽可能简单，但仍然极具价值。本书使用跨平台的CMake构建系统来编译和链接这些示例，因此它们可以在Windows、Mac OS X 及 Unix操作系统上运行。

我也会在此网站上发布所有对该书的新的修订以及勘误表，还有互联网上其他相关的API资源的链接，如有趣的工具包、文章和实用程序等。

本书的网站上也提供了一个由我编写的名为Diff的API组件。此程序可以通过可视化的对照方式，比较两个版本的API，并检查编码和注释上的不同之处。你也可以用它生成某个特定发行版本的变更报告，这样你的客户就能准确知道需要注意什么了。该工具适用于Windows、Mac OS X 及 Linux。