API设计

一、优秀的API具有哪些特征：

1、易学易记；

2、可读性高；

3、不容易用错；

4、容易扩展；

5、具有完整性：用户通过API能去做想做的事情，但是这是比较困难的。即便如此，至少也应该方便扩展和定制化（例如通过继承等等）。当然，设计一个完整的API这可能需要一个过程，但起码得保证有一个清晰的设计思路，或者在朝着正确的方向迈出的一步，因为并不是每一个API从最开始就是很完美的。

 

二、设计过程

1、了解需求

在 设计 或 实现 一个API之前 ，你应该有一个 good idea of the requirements。 有时， 需求 相当明确 ，但 在大多数情况下 ，您将 需要 梳理并分析 这些需求 。 一个 很好的着手点 是让 尽可能多的人 知道 （ 尤其 是 你的老板 ，你的同事， 和潜在用户 ） 他们 想 要看到 的特性 。

2、开始写任何代码前先描述用例

在写代码的时候，一个最常见的错误 是 先实现 功能 ， 然后再设计 API ， 并 最终 发布API 。用例反应需求，首先考虑做什么，然后才是考虑怎么做。在设计API时，不要去考虑实现的过程有多么复杂，而是去考虑是否能满足用户的需求和体验。

3、在同一个库中查找类似的API

在一个库中有多个API实现相同或者相近的功能是一件很糟糕的事情。

4、在实现API之前请先定义他

同开始写任何代码前请先描述用例一样。当我们在实现API之前也请先定义这个API。

5、让你的同事review你的API

6、写几个API的例子

7、准备用于扩展

8、不要发布未经过review的内部API

9、如果你对你的API存在疑问或者顾虑，请不要发布，或者标记为内部API或者稍后再重新思考

 

三、设计指南

1、观其名而知其意

2、名称不要有二义性，即使没有参考API的文档的前提下

3、不要让不相近的API，让人感觉他们相近——提防虚假的一致性

4、避免缩写

5、选择一个好的默认值

6、避免你的API过度智能

7、注意边缘的场景

8、The best API is no API