> 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)
