api设计规范性问题（API设计101）

> Photo by Startup Stock Photos from Pexels

API是应用程序编程接口。 这是一个程序向其他程序提供服务的一种结构化方式。

简单来说，就像在餐厅点菜。 你不能去厨房做饭。 您会看到一个菜单，并且您知道厨房正在做饭。 您使用服务员下订单。

服务员是API，它将您的请求带到准备它的厨房并带回给您。

类似地，某人（例如Facebook）为API提供了带有各种参数的有限命令菜单。 您的程序使用此API下订单，Facebook会开始执行该订单。

引用丹尼尔·杰克逊的话：

软件建立在抽象之上。 选择合适的程序，编程将自然而然地从设计中产生。 模块将具有小而简单的界面； 而无需进行大量重组，新功能就很可能适用。 选择错误的程序，编程将带来一系列令人讨厌的惊喜。

优质API的特点：

一个好的API是

· 简单易学

· 导致可读代码

· 难以滥用

· 易于扩展和

· 完备

简单易学

为了使API易于学习，它必须具有一致的命名约定和模式，对概念的仔细管理以及可预测性。 对于相似的概念，它使用相同的名称，对于不同的概念，它使用不同的名称。 用户必须能够重新应用他们在API的另一部分中学到的知识。

组成它的不仅是名称和方法，还包括其预期的语义，这些语义应该简单明了。 有些API很难学习，因为它们需要用户编写大量的样板代码才能入门。 易于学习的API使得仅用几行简单的代码即可编写" hello world"示例，并逐步对其进行扩展以获得更复杂的程序。

导致可读代码

有时即使一个库易于学习和记忆，它仍然可能导致完全不透明的代码。 API必须是可读的，因为应用程序代码仅编写一次，但是在应用程序的生命周期中由不同的开发人员反复读取。

可读代码更易于阅读和维护，即使存在错误，由于代码的可读性，它也更易于调试。 另外，可读代码始终处于正确的抽象级别上-既不隐藏重要内容，也不强迫程序员指定不相关的信息。

难以滥用

精心设计的API使编写正确的代码比编写错误的代码更容易，并鼓励良好的编程习惯。 它不会不必要地强迫用户严格按顺序调用方法或意识到隐性副作用。 通过消除冗余，我们可以使API难以滥用。

易于扩展

API的设计应考虑到增长。 在初始阶段，应该仔细考虑诸如新类，现有类的新方法，方法的新参数等内容。

完备

几乎不可能为任何内容提供完整的API，但是至少用户应该可以扩展或定制现有的API。 因此，API将是完整的，并允许用户执行他们想要的一切。

通过向现有API逐步添加功能，完整性会随着时间的流逝而出现。 但是，即使在那种情况下，通常也有助于明确未来的发展方向，因此每次添加都是朝着正确方向迈出的一步。

设计过程：

这需要几年的时间，并且需要很多人来构建良好的API。 流程的每个步骤都提供了改进API或破坏API的机会。

罗马不是一天建成的。

了解要求

在着手设计API之前，请先对这些要求有所了解。 在大多数情况下，您将需要进行某种需求分析。 一个好的出发点是向尽可能多的人（尤其是您的老板，同事和潜在用户）询问他们希望看到哪些功能。

在编写任何其他代码之前先编写用例

该实现应适应用户，而不是相反。 为此，在编写实现代码甚至设计API之前，首先要根据需求列表编写一些典型的应用程序代码片段。 在此阶段，不必担心实施API会遇到的困难。 在编写代码段时，API逐渐成形。

这些片段应反映Perl的座右铭，

"让轻松的事情变得容易，而让困难的事情变得可能"。

在实现之前定义API

在定义API之前，应在实现API之前先指定API及其语义。 对于具有数千个用户的库，如果API很简单。 有时实现起来可能会很棘手，但这没关系。

API及其语义是库提供的主要产品。 经验一次又一次地表明API比其实现更持久。

让您的同事查看您的API

寻找，询问甚至乞求反馈。 向您的同行展示您的API，并收集您获得的所有反馈。 尝试忘记实施请求的更改将需要进行多少工作。 当收到负面反馈时，请相信所有反馈都是有用的原则。 任何意见都是一条新的信息，您可以将其重铸为事实并添加到您的事实心智表中。

您拥有的事实越多，设计好的API的机会就越大。

准备扩展

设计API之后，请务必编写一些使用该API的示例。 使用API的人提供的反馈和示例将非常有用。

API可以通过两种方式扩展：

· 由维护者（添加/弃用）和

· 由将自定义API行为的用户决定。

规划可扩展性需要仔细考虑实际情况并考虑可能的解决方案。 如果您对API或功能有疑问，请将其排除在外，稍后再重新考虑。 它通常有助于等待用户的反馈。 实际上，不可能添加用户建议的所有功能。 一个好的经验法则是等到大量用户独立地要求功能后再实施它。

设计准则：

遵循准则，在设计API时无疑会改进它。 希望这些指南能帮助您正确使用API。 您可以在流程的各个阶段再次参考这些内容。

对于许多准则，可能会有同样真实的反准则（牛顿第三定律，大声笑）。 例如，

· "避免使API过于聪明"和"避免使API过于愚蠢"

· "注意边缘情况"和"关注一般情况"

API设计如此令人鼓舞的原因是，需要考虑产生相互矛盾的需求。 但最后，这些都无法替代您的大脑。

命名

· 选择不言自明的名称和签名。 方法的参数含义应该清楚。 布尔参数通常会导致代码无法读取，因此请注意这些内容。 并争取一致性。 固定参数顺序时，一致性特别重要。 避免使用单字母名称。

· 为相关事物选择不同的名称。 如果需要区分两个或更多个相似的概念，请选择与它们所表示的概念清晰对应的名称。 任何人都可以轻松地将名称与正确的概念相关联，而无需在文档中查找它们。

· API应该显示出良好的对称性。 形式的相似性使用户能够识别内容和功能的相似性。 另一方面，功能的不对称性应由形式的不对称性反映出来。 如果您习惯给setter方法加上" set"（例如setValue（））作为前缀，那么对于那些不是setter的方法，请避免使用该前缀。

· 避免缩写。 如果有缩写，则意味着用户必须记住哪些词是缩写。 通常避免这种情况。 可以允许使用非常常用的形式，例如" min"，" max"，" rect"，" prev"等，但是必须一致地应用此约定。 这不适用于首字母缩写词。

· 优先使用特定名称而不是通用名称。 特定名称使用户更易于联系，因为可能有数百个需要不同名称的类。

语义学

· 选择良好的默认设置，这样用户就不必只是为了入门而复制和粘贴或编写样板代码。 选择良好的默认值，我们不仅要消除样板代码，还可以使API简单且可预测。

· 注意边缘情况。 边缘情况很重要，因为它们往往会在API中产生波动。 例如，如果您的基本字符串搜索算法的边缘情况不正确，这可能会导致正则表达式引擎中的错误，从而导致使用正则表达式的应用程序中的错误。 首先处理一般情况，而不必担心边缘情况。 通常，您不需要任何额外的代码来处理边缘情况。 没人需要计算0的阶乘函数！ = 0，哈哈。 但是，请确保在单元测试中正确覆盖了边缘情况。

结论

设计API并不容易。 这需要大量的耐心和努力。 希望本文对您有所帮助。 当然，我可能已经错过了一些东西，请随时让我知道。

祝好运并玩得开心点！

(本文翻译自Deepak Surya的文章《API Design 101》，参考：https://medium.com/@ideepaksuryas/api-design-101-4da3e1d1767)

,