读《C++ API设计》
API简介
API是软件组织的逻辑接口，隐藏了实现这个接口所需的内部细节。
+-----------------------------------------------------+
| |
| Second Life Viewer | 应 用 程 序 代 码
| |
+-----------------------------------------------------+
+-----------+ +-------------+ +-------------+
| | | | | |
| IICommon | | IIMessage | | IIAudio | ... 内 部 API
| | | | | |
+-----------+ +-------------+ +-------------+
+----------+ +-----+ +---------+ +---------+
|OpenGL | | ARP | | Boost | |OpenSSL | 第 三 方 API
+----------+ +-----+ +---------+ +---------+
+-------------+ +--------------------------+
|标 准 C 库 | | 标 准 模 板 库 | 语 言 API
+-------------+ +--------------------------+
特征
本章主要用来回答下面这个问题：优质的API应该具有哪些基本特征。
getter，setter的优点：
- 有效性验证
- 惰性求值
- 缓存
- 额外的计算
- 通知
- 调试
- 同步
- 更精细的访问控制
- 维护不变式关系
将私有功能声明为.cpp文件中的静态函数，而不要将其作为私有方法暴露在公开的头文件中。
疑惑之时，果断弃之！精简API中共有的类和函数。
避免将函数声明为虚函数，除非有合理且迫切的需求。使用时，需要谨记一下几点原则：
- 如果类包含任一虚函数，那么必须将析构函数声明为虚函数。
- 一定要编写文档，说明类的方法是如何相互调用的。
- 绝不在构造函数或析构函数中调用虚函数，这些调用不会指向子类。
基于最小化核心API，以独立的模块或库的形式构建便捷API。
避免编写拥有多个相同类型参数的函数。
将资源的申请与释放当做对象的构造和析构。
不要将平台相关的#if或#ifdef语句放在公共的API中，因为这些语句暴露了实现细节，并使API因平台而异。
优秀的API表现为松耦合高内聚。
模式
主要涉及的模式有：
- Pimpl惯用法：支持在共有接口中完全隐藏内部细节。
- 单例和工厂方法
- 代理、适配器和外观：在现有的不兼容接口或遗留接口上封装API的各种途径
- 观察者：该行为模式可以用来减少类之间的直接依赖。
Pimpl
Pimpl使用示例：
// with out pimpl
// autotimer.h
#ifdef _WIN32
#include <windows.h>
#else
#include <sys/time.h>
#endif
#include <string>
class AutoTimer
{
public:
explicit AutoTimer(const std::string &name);
~AutoTimer();
private:
double GetElapsed() const;
std::string mName;
#ifdef _WIN32
DWORD mStartTime;
#else
struct timeeval mStartTime;
#endif
};
// with pimpl
// autotimer.h
#include <string>
class AutoTimer
{
public:
explicit AutoTimer(const std::string &name);
~AutoTimer();
private:
class Impl;
Impl *mImpl;
};
// autotimer.cpp
#include "autotimer.h"
#include <iostream>
#if _WIN32
#include <windows.h>
#else
#include <sys/time.h>
#endif
class AutoTimer::Impl
{
public:
double GetElapsed() const
{
...
}
std::string mName;
#ifdef _WIN32
DWORD mStartTime;
#else
struct timeval mStartTime;
#endif
};
AutoTimer::AutoTimer(const std::string &name) :
mImpl(new AutoTimer::Impl())
{
mImpl->mName = name;
#ifdef _WIN32
mImpl->mStartTime = GetTickCount();
#else
gettimeofday(&mImpl->mStartTime,NULL);
#endif
}
AutoTimer::~AutoTimer()
{
std::cout << mImpl->mName << ": took " << mImpl->GetElapsed() << " secs" << std::endl;
delete mImpl;
mImpl = NULL;
}
单例
单例是一种更加优雅地维护全局状态的方式，但始终应该考虑清楚是否需要全局状态。
依赖注入，实现：
/// 此处传入的Database是一个单例，这样，在该类的内部不用反复调用GetInstance，
/// 同时，这样的操作方式使得接口更加易于测试，因为对象的依赖项可以被
/// 替换为桩对象（stub）或模拟对象（mock），以便执行单元测试
class MyClass
{
public:
MyClass(Database *db) : mDatabase(db) {}
private:
Database *mDatabase;
};
初版《设计模式》的作者指出，他们计划从原列表中移除的一个模式就是单例模式。
工厂
让工厂类维护一个映射，此映射将类型名和创建对象的回调关联起来。示例：
#include "renderer.h"
#include <string>
#include <map>
class RendererFactory
{
public:
typedef IRenderer* (*CreateCallback)(); // 此处的CreateCallback可以是具体类的对应的Create函数
static void RegisterRenderer(const std::string &type, CreateCallback cb);
static void UnregisterRenderer(const std::string &type);
static IRenderer *CreateRenderer(const std::string &type);
private:
typedef std::map<std::string, CreateCallback> CallbackMap;
static CallbackMap mRenderers;
}
代理
代理提供了一个接口，此接口将函数调用转发到具有相同形式的另一个接口。
class Proxy
{
public:
Proxy() : mOrig(new Original()) {}
~Proxy() { delete mOrig; }
bool DoSomething(int value) { return mOrig->DoSomething(value); }
private:
Proxy(const Proxy&);
const Proxy &operator=(const Proxy&);
Original *mOrig;
};
使用代理模式的一些案例：
- 实现原始对象的惰性实例，当需要的时候才创建原始对象
- 实现对原始对象的访问控制
- 支持调试模式，实现不调用原始对象的方法，用来调试接口
- 支持资源共享，多个proxy对象，共享相同的原始基础类。
- 应对original类将来被修改
适配器
将一个类的接口转换为一个兼容的但不相同的接口。
优点如下：
- 强制API始终保持一致性。
- 包装API的依赖库
- 转换数据类型
- 为API暴露一个不同调用约定
外观
能够为一组类提供简化的接口。在封装外观模式中，底层类不再可访问。
常见用途：
- 隐藏遗留代码
- 创建便捷API
- 支持简化功能或者替代功能的API
观察者
观察者支持组件解耦且避免了循环依赖。
设计
+----------------------+ +------------------------+ +---------------+
| Analyze | | Design | | Implement |
| | | | | |
| Requirement | | Architecture | | Coding |
| +---------> +------> |
| User Case | | Class Design | | Testing |
| | | | | |
| User's Story | | Method Design | | Document |
| | | | | |
| | | | | |
+----------^-----------+ +------------^-----------+ +--------^------+
| | |
| | |
| | |
+----------------------------------+---------------------------+
演进式实现一个不错的选择是，将丑陋的旧代码隐藏在精心设计的新的API之后，然后利用这些整洁的API逐步更新所有客户端代码，并将代码自动化测试下。
创建API的架构过程可以分解为4个基本步骤：
- 分析影响架构的功能性需求；
- 识别架构的约束并加以说明；
- 创造系统中的主要对象，并确认它们之间的关系；
- 架构的交流与文档
架构约束可以细分为：
- 组织因素：预算，时间表，团队大小与专业知识，软件开发过程，决定子系统是自己构建还是购买，管理焦点等；
- 环境因素：硬件，平台，软件约束、客户端/服务器约束，协议约束，文件格式约束，数据库依赖，开发工具等
- 运行因素：性能，内存利用率，可靠性，可用性，并发性，可定制型，可扩展性，脚本功能，安全性，国际化，网络带宽
识别主要抽象，openscenegraph api顶层架构：
+-----------+
视 图 | |
^ | 节 点 工 具 包 |
遍 历 器 + | | |
+----------> | | |
+ | 仿 真 |
场 景 图 渲 染 <---+ |
数 据 库 +----------> | 地 形 |
^ | |
| | 动 画 |
+ | |
插 件 +-----------+
一些比较流行架构模式的一个分类：
- 结构化模式：分层模式，管道与过滤器模式和黑板模式
- 交互式系统：MVC，MVP，表示-抽象-控制模式
- 分布式系统：客户端/服务器模式，三层架构，点对点模式以及代理模式。
- 自适应系统：微内核模式与反射模式
循环依赖意味着无法对每个组件进行单独测试，也不能在不牵扯组件的情况下复用另一个组件。基本上要理解任何一个组件都必须理解全部组件。
在API的附属文档中要描述其高层架构并阐述其原理。
要集中精力设计定义了API80%功能的20%的类。
Liskov替换原则，在不修改任何行为的情况下用派生类替换基类，这应该总是可行的。
组合优先于继承。
开闭原则：类的目标应该是为扩展而开放，为修改而关闭。它关注的焦点是创建可以长期使用的稳定性接口。
迪米特法则，一个函数可以做的事情只包括：
- 调用同一个类的其它函数
- 在同一个类的数据成员上调用函数
- 在它接受的任何参数上调用函数
- 在它创建的任何局部对象上调用函数
- 在全局对象上调用函数
常见的互补的术语：
- Add/Remove
- Begin/End
- Create/Destroy
- Enable/Disable
- Insert/Delete
- Lock/Unlock
- Next/Previous
- Open/Close
- Push/Pop
- Send/Receive
- Show/Hide
- Source/Target
使用一致的、充分文档化的错误处理机制，返回错误码，抛出异常，中止程序。
在出现故障时，让API快速干净地退出，并给出完整精确的诊断细节。
风格
本章会介绍四种风格迥异的API
- 纯C API：func(obj,a,b,c)
- 面向对象的C++ API: obj.func(a,b,c)
- 基于模板的API
- 数据驱动型API：send("func",a,b,c); 这类接口特定是，将参数通过灵活的数据结构打包，连通命名的命令一起发送给数据程序，而不是调用特定的方法或自由函数。
C++用法
如果类分配了资源，则应该遵循“三大件”规则，同时定义析构函数、复制构造函数和赋值操作符。
考虑在只带有一个参数的构造函数的声明前使用explicit关键字。
避免使用友元。它往往预示着糟糕的设计，这就等于赋予用户访问API所有受保护成员和私有成员的权限。
使用内部链接以便隐藏.cpp文件内部的、具有文件作用域的自由函数和变量。也就是说，使用static关键字或匿名命名空间。
应该显示导出共有API的符号，以便维持对动态库中类、函数和变量访问性的直接控制。对于GNU C++，可以使用__fvisibility_hidden选项。
性能
不要以扭曲API的设计为代价换取高性能。
为优化API，应使用工具收集代码在真实运行示例中的性能数据，然后把优化精力集中在实际的瓶颈上。不要猜测性能瓶颈的位置。
- const引用
- 前置声明
- 冗余的include警戒语句
// head.h
#ifndef _HEAD_
#define _HEAD_
#endif
#ifndef _HEAD_
#include "head.h"
#endif
- 应该使用extern声明全局作用域的常量，或者在类中以静态const 方式声明常量，然后再.cpp中定义常量
- 初始化列表
- Vector.h detail/Vector.h
- 写时复制
- 时效分析
- 内嵌测量，代码内嵌计时器
- 二进制测量
- 采样
- 监控计数器
- 基于内存的分析：IBM Rational Purify，Valgrind，Parasoft Insure++，Coverity
- 多线程分析：Intel Thread Checker，Helgrind，DRD
版本控制 (TODO: Read Again)
主.次.补丁
只在必要时再分支，尽量延迟创建分支的时机。尽量使用分支代码线路而非冻结代码线路。尽早且频繁的合并分支。
文档
复用做起来远不如说起来那么简单，它同时需要良好的设计和优秀的文档。即使我们发现了难得一见的良好设计，如果没有优秀的文档，这个组件就很难得以复用。
doxygen常用命令：
- file [<文件名>]
- class <类名>[<头文件>][<头文件名>]
- rief 简要说明
- author
- date
- param
- param[in]
- param[out]
- param[in,out]
- eturn
- code endcode
- verbatim <字面文本块> endverbatim
- exception 异常对象 描述
- deprecated 解释及替代品
- attention 需要注意的消息
- warning 警告消息
- version
- ug
- see
- ame 组名
测试
为了确保不破坏用户程序，编写自动化测试所能采取的措施中最重要的一项。
非功能测试：
- 性能测试
- 负载测试
- 可扩展性测试
- 浸泡测试：尝试长期持续地运行软件
- 安全性测试
- 并发测试
API测试应组合使用单元测试，和集成测试，也可以适当运用非功能性测试，如性能、并发、安全。
单元测试是一种白盒测试技术，用于独立验证函数和类的行为。
如果代码依赖于不可靠的资源，比如数据库、文件系统或网络，那么可以使用桩对象或模拟对象创建个更健壮的单元测试。
google mock
使用SelfTest()成员函数测试类的私有成员。
使用断言记录和验证那些绝不应该发生的程序设计错误。
#ifdef DEBUG
#include <assert.h>
#else
#define assert(func)
#endif
脚本化 (TODO: read again)
可扩展性
Qt工具包可以通过QPluginLoader来扩展。
一般如果要创建插件系统，有两个主要特性是必须要设计的。
- 插件API：要创建插件，用户必须编译并连接插件API
- 插件管理器：核心API的一个对象，负责管理所有插件的声明周期，插件的加载、注册、卸载等各个阶段。该对象也叫做插件注册表。
为API设计插件时的决策：
- C还是C++：c可以跨平台跨编译器
- 内部元数据还是外部元数据
- 插件管理器是通用还是专用
- 安全性
- 静态库还是动态库
C++实现插件
开源库DynObj。
插件API
插件应该提供两个最基本的回调函数，初始化和清理函数。
// defines.h
#ifdef _WIN32
#ifdef BUILDING_CORE
#define CORE_API __declspec(dllexport)
#define PLUGIN_API __declspec(dllimport)
#else
#define CORE_API __declspec(dllimport)
#define PLUGIN_API __declspec(dllexport)
#endif
#else
#define CORE_API
#define PLUGIN_API
#endif
// renderer.h
class IRenderer
{
public:
virtual ~IRenderer() {}
virtual bool LoadScene(const char* filename) = 0;
virtual void SetViewportSize(int w, int h) = 0;
...
};
// pluginapi.h
#include "defines.h"
#include "renderer.h"
#define CORE_FUNC extern "C" CORE_API
#define PLUGIN_FUNC extern "C" PLUGIN_API
#define PLUGIN_INIT() PLUGIN_FUNC int PluginInit()
#define PLUGIN_FREE() PLUGIN_FUNC int PluginFree()
typedef IRenderer *(*RendererInitFunc)();
typedef void (*RendererFreeFunc)(IRenderer*);
CORE_FUNC void RegisterRenderer(const char* type, RendererInitFunc init_cb, RendererFreeFunc free_cb);
插件示例：
// plugin1.cpp
#include "pluginapi.h"
#include <iostream>
class OpenGLRenderer : public IRenderer
{
public:
~OpenGLRenderer() {}
...
};
PLUGIN_FUNC IRenderer *CreateRenderer() { return new OpenGLRenderer(); }
PLUGIN_FUNC void DestroyRenderer(IRenderer* r) { delete r; }
PLUGIN_INIT()
{
RegisterRenderer("opengl", CreateRenderer, DestroyRenderer);
return 0;
}
插件管理器：
- 加载所有插件的元数据
- 将动态库加载到内存中，提供对库中符号的访问能力，并在必要时卸载
- 初始化，清理
// pluginmanager.cpp
#include "defines.h"
#include <string>
#include <vector>
class CORE_API PluginInstance
{
public:
explicit PluginInstance(const std::string& name);
~PluginInstance();
bool Load();
bool Unload();
bool IsLoaded();
std::string GetFileName();
std::string GetDisplayName();
private:
PluginInstance(const PluginInstance&);
const PluginInstance &operator = (const PluginInstance&);
class Impl;
Impl *mImpl;
};
class CORE_API PluginManager
{
public:
static PluginManager &GetInstance();
bool LoadAll();
bool Load(const std::string& name);
bool UnloadAll();
bool Unload(const std::string& name);
std::vector<PluginInstance*> GetAllPlugins();
private:
PluginManager();
~PluginManager();
std::vector<PluginInstance*> mPlugins;
};
访问者模式
访问者模式的核心目标是，允许客户遍历一个数据结构中的所有对象，并在每个对象上执行给定的操作。
// 场景图层次结构的例子
+----------------+
| |
+--------------+ Transform0 +--------+
| | | |
| +------+---------+ |
| | |
| | |
| | |
| | |
| | |
+-----v----+ +---------v------+ +-------v--------+
| | | | | |
| Light0 | | Transform1 | | Transform2 |
| | | | | |
+----------+ +-+------------+-+ +-----------+----+
| | |
| | |
| | |
| | |
| | |
+------v-----+ +--v-------+ +----v--------+
| | | | | |
| Shape0 | | Shape1 | | Shape2 |
| | | | | |
+------------+ +----------+ +-------------+
// nodevisitor.h
class ShapeNode;
class TransformNode;
class LightNode;
class INodeVisitor
{
public:
virtual ~INodeVisitor() {}
virtual void Visit(ShapeNode &node) = 0;
virtual void Visit(TransformNode &node) = 0;
virtual void Visit(LightNode &node) = 0;
};
// scenegraph.h
#include <string>
class INodeVisitor;
class BaseNode
{
public:
explicit BaseNode(const std::string &name);
virtual ~BaseNode() {}
virtual void Accept(INodeVisitor &visitor) = 0;
private:
std::string mName;
};
class ShapeNode : public BaseNode {};
class TransformNode : public BaseNode {};
class LightNode : public BaseNode {};