好的API都有哪些特点

译者注：好的API是怎样的，应该具备哪些特点，作者对此进行了详细说明，并把API比作产品，主张编写API时从用户的角度换位思考。

如果用户通过他们自己的代码与你的代码进行交互，那么你将需要构建一个API。因此，理解好的API特性是至关重要的。那么什么是好的API呢?

“API”一词似乎是对软件开发人员的一种Rorschach Test。Web开发人员将API视为REST端点和wsdl。相比之下，桌面开发人员可能认为API是由来自其他组织的开发人员编写的“代码库”。人们编写像驱动程序这样的低级代码是为了提供操作系统调用的入口。

API提供了一种更通用的思维方式，我个人喜欢下面“技术术语”的定义。

API是一组命令、函数、协议和对象，程序员可以用它们来开发软件或与外部系统进行交互。它为开发人员提供了执行通用操作的标准命令，这样他们就不必从头开始编写代码了。

API定义了其他程序员如何与软件进行交互。因此，我提到的每一角色都有自己的正确答案，但只是一小部分。当你写代码的时候，想想调用这段代码的用户。如果该用户想通过自己的代码与你的代码进行交互，那么你将需要构建一个API。这方便于你公司的其他开发人员，甚至你的团队使用你的代码。

所以了解好的API的特性对我们至关重要。它会让其他人在你的工作上有所不同。而且老实说，会带来一定程度的职业自豪感。那么什么是好的API呢？让我们看看一些好的API的特性。

简单

首先简单是最重要的。程序员倾向于解决复杂的问题，这使得我们很容易地让这些复杂性影响到编写的用户API。保持简单就需要大量工作，有时还会带来严重的挑战。

我们想要帮助的意愿一定程度上增加了困难。通常，程序员想要提供几种不同的方法来做一些事情。“也许他们想通过构造函数传递这些依赖关系。但是如果他们更喜欢使用setter呢?我们应该让两者都存在。”通向复杂性的道路就是这样良好的意愿铺好的。

即使你认为它可能会有所帮助，也要努力去增加不必要的复杂性。好的api表现出简单性，而且要保持这种简单性需要付出很大的努力。

提供有用的抽象

接下来，考虑抽象的概念。当你成功地从用户的API中隐藏细节只留下要点时，你就提供了抽象。

这个世界充满了抽象的例子。设备驱动程序抽象处理供应商硬件的细节。线程模型提供了一种抽象，用于处理在OS级别上调度执行。操作系统本身为核心计算机硬件的不同提供了一个抽象概念。甚至你的编程语言也会抽象出编写机器代码的细节。

好的代码提供了抽象，API也不例外。你的API应该隐藏它对用户的详细信息，同时使其对用户有用。如果你的用户需要深入代码或执行来理解，你就提供了一个很差的抽象。

可发现的

简单和好的抽象会让你取得不错的成绩。但是，当你写出一个“可发现”的API时，你将走的更远。这与一个新手在使用你的代码时的效率有很大的关系。

我将选用一个非代码示例作有帮助的同类型比较。从用户体验角度想想看，最初的iPhone革命性的是什么。它有一个屏幕和一个按钮。它的应用程序把东西挂在屏幕的一边，让你发现可以通过左右滑动来提高你的使用频率。与之前的设备不同，这款可发现的设备让即使是最不聪明的用户也能快速的进行操作。

让你的API争取做到这一点。要知道，你的用户在拿起手册或打电话询问之前，他们会进行测试和实验。相应的计划和设计，包括文档和示例，以及自我描述访问点会让API具备可发现性。另外使用一个名为GetLastNameFromOrder(CustomerOrder orderToQuery)的方法可以帮助你达到预期目的。

一致和对称

假如你已经偏离了先前的考虑，那么请检查你的API以保持一致性和对称性。一致性相对容易理解。有时候不要称他们为“用户”或“客户”，用相同的方式命名相同的东西，保持一个共同的风格。从而让你的API是可预测的。

对称性是一个稍微有些微妙的考虑。当我谈到对称时，指的是一种以用户期望的方式关闭开放循环的偏好。例如，如果你有一个用于文件访问的API，它允许你调用Open(string文件名)，那么你也应该提供一个Close(string文件名)方法。打开和关闭具有相反的含义，因此，提供两种功能都可以作为操作的关注点来创建对称。调用Close方法是“销毁”，而如果没有关闭方法，会造成很大的混乱。

在API中，你可以通过对向用户公开的内容运用批判的眼光来实现这一特性。仔细阅读校对者的方法，检查一致性和对称性，然后根据需要重命名和修改。

遵循最不惊奇的原则

作为最后的考虑，我想给大家介绍一个聪明的“最小惊奇原则”。这表示“一个系统应该以与该组件的用户可能期望的行为一致的方式运行。也就是说，用户不应该对它的行为感到惊讶。”更坦率地说，不要编写API来让你的用户大吃一惊。

我上面关于对称的例子也可以被认为违反了这一原则。但是让我们稍微改变一下，让它更明显地说明这个原则是什么意思。假设你的文件API有一个开放的(字符串文件名)方法，然后它要求你通过调用Open()来关闭文件，而且没有参数。而无论何时你调用Close()，因为某些原因它都会发送一封电子邮件给一个叫Bill Smith的人。如果对这个过程做出反应，你就会得到一个“令人惊讶”的因素。

好的API并没有导致用户抓狂的属性，“但是这没有任何意义！”或者“我怎么知道这一点?！”向用户提供一个与它所宣称的功能无关的API，我想没有什么比这更快捷的方式来失去用户的信任了。

把API看作一种产品

简单、有用、可发现、一致、可预测，所有这些不仅描述了良好的API，还描述了良好的产品。这不是偶然的，当你编写API时，你将创建一个产品。不管你是否真的这样想，不管你是否真的把产品卖了，你手上都有一个别人想要用的产品。

作为开发人员，我们很容易忽视这一点。根据知识的偏差，假设我们的API用户是程序员，他们知道我们所知道的，理解我们所理解的，但我们并不认为他们是最终用户或客户。

要克服这种偏差，换位思考是设计好的API的关键思想。所以当你编写下一个API时，把自己放在客户的角度，想象你想要的是什么。