编写函数式API相对容易，但要编写一个好的函数式API和授权您的用户需要计划和耐心。设计一个好的API就是要创造一种清晰和简单的感觉——它是你的意图和你的用户之间的桥梁。
与大多数软件开发一样，建立API是一个创造性的过程;完全定义所有案例中都有工作的硬度和快速的规则是不可能的。尽管如此，三个关键问题 - 从我认为良好API的关键特征源于您的关键特征 - 可以在您设计和编写API时作为功能指南服务：
- 是你的api的用法可发现还是
- 是你的api可兼容还是
- 是你的api安全使用还是
让我们仔细看看每个问题。
1.你的API的使用是否可发现?
在他着名的书中，日常事务的设计唐·诺曼创造了这个词可发现性．“当我们与产品互动时，”诺曼写道，“我们需要弄清楚如何使用它。这意味着要发现它能做什么，它是如何工作的，以及哪些操作是可能的。”
例如：例如：我们每天都与这些标准物理对象进行交互。通常，根据旋钮，手柄和推杆等带来的存在，它非常清楚如何打开或关闭门。但是，有时，门的设计将表明它实际上如何工作，并且因此，我们需要在正确使用之前指令。只想到你有多少次拉动实际需要推动的手柄。
当我们用错门的时候，我们会觉得自己很愚蠢，但这不是我们的错。实际上是设计不好。
使用不良的API可能会发生类似的东西。
考虑您使用的最后一个API。你是如何学习使用它的？你先阅读了所有文档了，还是刚跳进去？也许你不确定所有参数，所以你发送了零对于几个值并猜到他人。当你做错了什么时候，API会抛出错误消息，或者在没有任何反馈的情况下默默地失败了吗？错误消息是否清楚地定义了哪些参数是可选的，哪个参数不是？你只是继续堵塞，直到你对它有对吗？
事实:这是大多数用户学习API的方式。
你的用户只会学到足够的东西来引导自己，然后他们会在自己的过程中弄明白剩下的东西。记住这一事实，您可以通过增加API的可发现性来帮助他们。你可以通过文档来做到这一点;坚持概念模型;使用简洁、对称的语言。
假设您的用户不会读取文档 - 直到他们需要
仅仅因为您的用户不会读取您的文档并不意味着您不需要提供它。你绝对是。但是假设每个人都会在使用它之前阅读文档时，不要设计API。
一些用户宁愿尝试，而不是在文档中查找答案。每次我使用javasubstring（）方法例如，我永远记不起第二个值是偏移量还是长度，所以我写了一个小程序来尝试这两种方法。对我来说，这通常比查找答案更快，也更有趣。
在许多情况下，已经学会了不信任文档的用户无论如何都不会读取文档，至少在他们绝望之前。在过时或错误的文件是臭名昭着的。现在，这显然不是真的所有文档，但是想想有多少次您查阅文档(或帮助系统或知识库)，发现它提供的答案完全无用，或者根本不提供任何相关的答案。大量的文档在预测用户可能会问的问题或如何提问方面做得很差。此外，即使用户知道他们想要完成的任务是什么，他们也可能缺乏准确的词汇表，或者使用与文档不同的术语来完成任务，这使得搜索变得困难。
您还应该在文档中提供大量示例 - 因为用户想要它们。通常，示例是用户在学习新API时寻找的第一件事。只有在他们获得一点上下文之后，他们才能看看文档的其余部分。例子是用户如何了解整个API。
创建API如何工作的概念模型
Don Norman解释说，概念模型是“对事物如何运作的一种解释，通常是高度简化的。”概念模型不是原理图，它们应该与其他已知的概念模型相关。
概念模型的一个很好的例子是个人计算机上使用的文件系统结构。类似于Mac和Windows操作系统的文件系统，是基于我们在物理世界熟悉的文件和文件夹的概念的基础上。这使非技术用户可以轻松理解和发现如何复制，存储和检索其PC上的文件。
即使在今天，Unix在用户将设备(例如电话或外部硬盘驱动器)连接到操作系统时仍然使用这种文件和文件夹的概念模型，这就完全消除了用户每次连接设备时“发现”新API的需要。
面向对象编程中的“对象”是概念模型的另一个示例。他们特别称为物体，以便我们将它们视为自定义实体。就像A一样球计算机上的对象可能支持一个弹跳方法，以及其他类似的方法扔，通过其设计，现实生活中的一个球也支持弹跳和投掷操作。然而，在以数据为导向的编程中，您没有得到这种概念模型，因此您更有可能拥有一个弹跳函数，如果您发送的不是球．
在概念模型中工作的另一个例子是在面向对象编程中使用“对象”。在该编程模型中，对象代表来自现实世界的物理对象，例如服务器，数据库和负载均衡器，并且开发人员通过API创建这些对象之间的关系。
使用清除，一致和对称的语言
除了记录您的API之外，还应为API开发和发布术语字典 - 然后始终使用它。例如，我常见地看到apis使用术语宿主和主机名，和账户和帐户ID，几乎互换。迫使您的用户猜测正确呼叫可能是什么，或不断更改语言，不会促进可发现性。
与概念模型一样，对称语言有助于用户使用某些期望与您的API合作。如果你的语言是对称的，那么打开操作将与a平衡关闭， 和添加操作将与a平衡删除．
在Python例如，您使用流行音乐要删除元素，因此期望将是您使用的推添加元素，因为在大多数其他语言中都是这样工作的。相反,Python使用附加......并且有很多谷歌搜索结果来自这种糟糕的可发现性困惑。
你的API是可组合的吗？
当您构建可组合的API时，您允许用户选择API的组件，并以他们想要的任何模式使用它们。
小型和可协商的方法更容易描述和文档，而不是含有长时间步骤和警告的较大方法。他们也更容易运行回归和结束到最终测试。
但是，最重要的是，使用可组合组件为您的用户提供了与API构建自己的工作流程所需的工具。您无法预测所有用户的需求，因此不要强迫它们进入一个执行模式。相反，创建可组装组件，然后使用您的示例来展示如何将它们组合成更大的执行模式。
例如，考虑以下方法：
setname（firstName，lastName）
vs.
setFirstName (firstName)
setLastName（LastName）
第二个选项比第一个更易于组合，因为第二个方法允许您轻松地更新值姓．使用第一种方法，您将首先要获取价值名所以你可以用新的价值发送回来姓．
第二个选项也更易于扩展，因为你可以很容易地添加一个方法来设置中间名:setMiddleName (middleName)．
最后，第二个选项也是100%向后兼容现有代码。如果要将第一个方法更新为setname（firstName，middlename，lastName），你就会破坏现有的代码。
毫无疑问，你和你的用户都将享受免费的向后兼容性，因为从更小的、可组合的组件构建可以更容易地扩展API;并继续支持旧业务和新业务。
问题3。你的API使用安全吗?
确保您的API可以使用 - 它不会与用户期望或打破其工作流程不同的方式 - 与API的可发现性有关。但安全性是如此重要，我想分开地调用这个主题。发布API时，您可以与您的用户创建应基于信任和透明度的用户建立关系。以下是如何实现的：
实践最小惊讶原则
这令人惊讶的原则告诉我们系统的组成部分应该表现为大多数用户期望它表现的方式。这种行为不应该惊人或令人惊讶的用户。
这设置当前日期方法GNU的Coreutils例如，每当我使用它时，它都会让我感到惊讶，因为我希望集合方法能够放值与非值改变，更改它。如果您将年份设置为小于68的任何值，它会自动为该值添加2000;如果设置68到100之间的任何值，它会自动添加1900.每次我使用此方法时，我都会惊讶，并且必须重新阅读文档以确保我正确使用它。
遵守合同
不要试图解释你的内容思考你的用户想要做什么。例如，如果API需要一个数字，而用户提供了一个字符串，不要尝试从字符串中解析数字。您没有给任何人带来任何好处:当用户输入一个空字符串时会发生什么:是0还是null?
设计您的API，使其具有确定性和严格性。
信任并不快速失败
同样，您的API应验证用户发送的所有内容，并立即失败。进一步来说，垃圾不应该等于垃圾．垃圾应该失败。如果您的用户使用不正确的值调用您的方法，那么他们可能处于发现模式，有意测试边界并试图找出什么是可能的。
帮助他们理解什么是可能的，什么是不可能的。
从开始和积极贬值的旧版本中计划版本
如果您更改API的签名或外部行为，则为IT。
当您滚动API的版本前进，致力于激发用户的时间和资源。如果这是不可能的，请尝试重写旧版本，以便它们代理新实现。这些步骤将有助于避免创造技术债务 - 这就像金融债务一样，绝对会随着时间的推移累积。您的API的过时版本越长，您的用户库中越根深蒂固，而且将用户移出越难以越突出。设置迁移日期，并使其发生。
如果你发布了一个可能会快速变化的版本，通过将其标记为“孵化”、“不稳定”或“beta”来明确这个事实。如果您在发布新API时需要关闭旧API版本，这有助于为您提供喘息的空间。
将API与您的实施分开
最后，将API版本与其实现分开发布。实现的变化可能比API的变化要快，所以不要把两者联系在一起。
例如，当对库进行版本控制时，API和它的实现在同一个包中，所以您只能同时发布它们。但你至少可以用语义版本化使其清除哪些部件向后兼容。
但是，对于服务，您可以将API与其实现分开发布。事实上，有很多工具，包括Apache节俭那FlinBuffers.,昂首阔步，它允许你单独编写你的API。有了这些工具，你就可以编写规范，然后构建你的实现实施规格。
确立第一印象
您的API通常是用户的第一印象。花时间在可发现性，可携带性和安全性上，以确保第一印象是一个很好的印象。适当的规划和设计对您的API的有效性和成功至关重要。花时间通过将有助于使您的API成为一流的功能 - 不是仅仅是追求的或意味着结束。
