浅谈API设计-白红宇

浅谈API设计

阅读量：5137 次

发布时间：2019-06-13

本文共 3215 字，大约阅读时间需要 10 分钟。

[非原创，]

为什么需要了解一些API设计？

只要你编程，你就是API Designer

一个好的设计，模块之间的耦合应该也是API级别的

一个程序，如果你独立开发，那你既是API的Designer，也是API的User

如果你和你的同事一起开发，，你既是你开发的模块API的Designer，也是其他同事模块API的User

一个好的API应该具备哪些特点？

1. 易学易用（Easy to learn and use）

要做到易学易用，需要满足以下基本要求：

a. API命名的要适应用户的习惯并遵循一些模式。例如：使用类似于add/delete, get/set，push_bach/pop_back这种大家比较熟悉的命名方法。避免用户使用get获取一个数据，但是需要使用insert插入数据。

b. API的设计需要尽量简化用户的使用复杂度，我们看下STL vector的使用，非常简洁！

[cpp]

// vector::push_back

#include <iostream>

#include <vector>

int main ()

{

std::vector<int> myvector;

int myint;

std::cout << "Please enter some integers (enter 0 to end):\n";

do {

std::cin >> myint;

myvector.push_back (myint);

} while (myint);

std::cout << "myvector stores " << int(myvector.size()) << " numbers.\n";

return 0;

}

// vector::push_back#include 
     
      #include 
      
       int main (){  std::vector
       
         myvector;  int myint;  std::cout << "Please enter some integers (enter 0 to end):\n";  do {    std::cin >> myint;    myvector.push_back (myint);  } while (myint);  std::cout << "myvector stores " << int(myvector.size()) << " numbers.\n";  return 0;}

c.尽量提供一些方便用户的api方法

例如提供一个STL vector提供at方法供用户获取指定位置的元素

reference at (size_type n);

但同时也提供API供用户直接获取第一个和最后一个元素

reference front();

reference back();

2. 引导用户写出可读性高的代码（Leads to readable code）

好的API设计，可以引导用户写出高可读性的代码，下面这个例子非常生动：

实现 1：

[cpp]

slider = new QSlider(8, 128, 1, 6, Qt::Vertical, 0,

"volume");

slider = new QSlider(8, 128, 1, 6, Qt::Vertical, 0,"volume");

实现 2:

[cpp]

slider = new QSlider(Qt::Vertical);

slider->setRange(8, 128);

slider->setValue(6);

slider->setObjectName("volume");

slider = new QSlider(Qt::Vertical);slider->setRange(8, 128);slider->setValue(6);slider->setObjectName("volume");

显然第二种设计更易引导用户写出可读性高的代码

3. 很难被误用

一个好的API设计，会使用户很容易写出正确的代码，而不是错误的代码。

这点非常重要，如果你的API很容易用错，那么，一方面用户会吐槽，另一方面，API的维护成本也很高

so，当你收到很多错误报告的时候，不要抱怨用户的使用方法有问题，review下自己的API，是不是很容易被误用

4. 方便扩展（Easy to extend）

api会变的越来越“大”，未来，api会提供新的类，类中会有新的方法，方法会有新的参数，枚举数据也会有新的枚举值。

因此，在API设计过程中，需要时刻提醒自己保证API的可扩展性

5. 完整（Complete）

所谓的完整，并不是指API满足用户所有的功能需求，而是说，基于这些API，可以满足所有功能需求。

我们还是拿STL::Vector来做说明，从获取数据的角度，API提供了reference at (size_type n); 就是完整的，另外提供的front back都是方便用户获取数据，用户完全可以个性化实现这样的功能。但是，如果只提供了front、back，而没有提供at这样的api，就是不完整的

兼容性

在设计API时，非常重要的点是要提前考虑API的发布方式，在发布过程中，兼容性非常重要

我们可以将兼容性分为：源代码兼容，二进制兼容，功能兼容

在Deliver新版本的API时，需要明确告知用户，API版本在哪些层面做到了向后兼容

源代码向后兼容：老的程序，使用新的API库依然能够正常工作

二进制向后兼容：直接升级库文件，老的程序不必重新编译就能使用新的库文件

功能兼容向后兼容：老的程序，使用新的API库，不影响已有功能

功能兼容是业务的范畴，这里不展开。着重讨论下源代码兼容和二兼职兼容。一个很有意思的讨论

一般来说，二进制兼容是源代码兼容的子集。如果你的代码打破了源代码兼容，基本上可以肯定你也打破了二进制兼容。相反则不成立，一个API是源代码兼容但不是二进制兼容表示你的代码无需如何修改，只要重新编译程序即能正常工作。

我们看下c++来，什么情况下我们会满足源代码兼容，但不满足二进制兼容

c++发布api有静态和动态库两种方式，这两种发布方式各有优劣，当采取动态库的发布方式，就面临二进制兼容问题

c++通过头文件使用动态库，编译时也据此产生二进制代码，因此，在考虑动态库兼容性的时候，只要考虑库使用已有的头文件是否和新的动态库兼容