使用规范驱动开发构建 API

回顾过去

“一切都完成了！”  在我上一份工作中，最后一行代码终于写完了，我们的 API 已经准备好发布到大众了！  我们再也无法感到更自豪了；这是六个月艰苦的跨公司会议、细致的编码以及 QA 大量耐心的最终成果。  在这个辉煌的时刻，我没有意识到，仅仅几个月后，整个项目就会在我们眼前崩溃，被迫关闭。

不，这不是高层领导改变了想法，也不是我们“战略性地转移”了重点，而是没有人想使用我们的 API。  尽管进行了许多长时间的会议、细致的编码和残酷的测试 – 我们却忘记了一个小细节。  我们忘记了在尝试构建 API 之前进行设计，并且将实际用户纳入设计周期。

可悲的是，在匆忙构建面向外部的 API 并将其交付给客户的过程中，公司却忘记了“销售”任何产品或服务的第一法则：了解客户的需求。
 

了解您为何要构建 API

当我与其他公司交流时，当我问他们为何要构建 API 时，我收到的最常见的回答是“他们想向开发者公开他们的应用程序/数据。”  但当我问“为什么”时，答案似乎站不住脚，不是因为他们没有提供优质的服务，而是因为他们没有花时间去理解或考虑开发者的用例。

在构建 API 之前，重要的是要理解您为何要构建 API。  重要的是要理解您是为谁构建的 – 是为了内部使用、您的客户，还是将扩展您的服务/补充他们自己服务的开发者？  是为了数据迁移还是服务利用？  您的 API 用户会期望执行哪些类型的操作？

这意味着要超越“他们将使用我们的数据”的说法，而是要绘制一个资源图，显示开发者将实际利用哪些服务，以及他们将如何利用这些服务。  很容易将此步骤与 CRUD 的实现混淆 – 试图将这些操作与 GET、POST、PUT、PATCH 和 DELETE 联系起来。  但这个过程应该更简单，因为在这个阶段，您只是在创建用户故事，而不是技术定义。  因此，与其关注 CRUD，不如关注客户端将能够做什么，例如您的 API 能够创建新用户、更新用户、重置忘记的密码等。  或者，如果您有一个消息系统，能够发送消息、创建草稿、发送草稿、查看消息、将消息移至文件夹、查看联系人等。

在此阶段，请务必让您的用户参与进来。  询问他们想做什么，什么对他们很重要。  因为无论您的 API 设计多么精心考虑，或者您如何细致地编写代码 – 如果它不是他们想要的，那将毫无用处。

一旦您有了 API 用户需求，现在是时候设计 API 了。  令人惊讶的是，许多公司会跳过这一步，而是直接进行开发。  问题在于，您的 API 是一份合同，是您与用户之间的协议。  这是您公司对他们的承诺，他们依赖您的 API 不仅是为了让他们的生活更轻松，也是为了他们的生计。  当您破坏向后兼容性、当您更改内容时，您就剥夺了他们专注于开发新功能的能，并迫使他们专注于修复由您自己的 API 引起的问题。

因此，确保您的 API 设计为 API 的初始发布以及未来的开发提供坚实的基础非常重要。  重要的是，您的 API 设计要关注长远发展。  不要只关注当前的产品路线图，而是要考虑您的产品在 2-3 年后可能会变成什么样 – 以及您的 API 将需要能够做什么。
 

利用规范驱动开发

做到这一点的最简单方法之一是利用规范驱动开发，或者将您的 API 分为两个不同的阶段：设计和开发。

第一阶段，即设计阶段，意味着与您的开发团队和潜在的 API 用户合作，制定一份规范，或者说是 API 应如何工作的蓝图。  有一些规范可以帮助您做到这一点，包括 RAML、Swagger 和 API Blueprint。  我个人最喜欢 RAML，因为它提供了一个单一格式 (YAML) 来管理您的 API，并允许代码重用，同时鼓励基于模式的设计。  RAML 也有一些很棒的 开源项目，包括一个 API 设计器，可以在您定义 API 的同时以可视化的方式显示它，交互式文档，以及一个 API Notebook，让用户可以使用 JavaScript 与您的 API 进行交互和探索。

使用 MuleSoft 免费托管的 API Designer ，您还可以原型化或模拟您的 API，让您在无需编写或修改任何代码的情况下获得即时用户反馈。  在设计过程中，API 的原型化/模拟至关重要，因为它可以帮助您识别潜在的设计缺陷和不一致之处，同时还能让您未来的 API 开发者为您提供您可能未曾想到的宝贵反馈和用例。

规范驱动开发的第二个阶段是开发，即为 API 的不同层编写代码。  通过拥有一份强大的蓝图供开发人员使用，他们可以快速无畏地构建您的 API，而无需担心他们的资源是否会与其他开发人员的资源兼容，或者模式是否匹配。

其理念是，在设计阶段，您将消除 99% 的设计缺陷/潜在设计错误。  因此，在开发周期中坚持使用规范非常重要。  很容易想偏离或更改内容，但这样做会让你回到原点 – 即时地创建 API，而事先没有经过仔细的思考。  请记住，我们在短期设计方面做得很好，但在长期设计方面却非常糟糕，而 API 的目的是长期存在的。

如果您在设计中确实发现了一个问题，那也没关系。  这意味着您需要回到设计阶段，实施解决方案，然后进行测试，以确保该解决方案按用户预期运行，并且不会破坏其他任何东西/引起任何不一致。  完成这些之后，您可以立即回到开发阶段。
 

一个痛苦的教训

他们说，一些人生中最好的教训是那些你用惨痛的代价学到的。  虽然我非常赞同，但我仍然希望在我们从事那个项目时，我们已经了解了规范驱动开发，并且有 RAML、Swagger 和 API Blueprint 等技术可用。  很难想象如果我们能在编写第一行代码之前就识别出 API 的问题，会发生什么。  API 可能今天是什么样子，以及我们会节省多少时间和金钱。

规范驱动开发并不能保证您的 API 会完美，甚至不能保证它会遵循 最佳 API 设计实践。 但是，它确实能确保您的 API 对用户来说是有意义的，并提供一个坚实、经过深思熟虑的基础，您可以在此基础上构建您的 API – 从而提高其灵活性、可扩展性和寿命。