深入浅出设计优先的 API 开发方法

想一想世界上最伟大的杰作。

莎士比亚的“哈姆雷特”。达芬奇的“蒙娜丽莎”。弗兰克·劳埃德·赖特的建筑之美——“流水居”。维瓦尔第的“四季”协奏曲。我还可以继续说下去，如果我说得算，我还会把世界上最好的皮卡也包括进来。

但是，我想说的是，所有这些杰作都有一个共同点：它们都是设计优先的。没有蓝图是建不了房子的。我敢打赌，达芬奇的“蒙娜丽莎”不是即兴创作的。

从设计开始并不是一个新想法，世界上最伟大的创造者已经实践了好几代，但把“设计优先”的方法运用到应用程序编程接口（API）上是一个新想法。

是吗？你可能会表示怀疑。让我解释一下！

由于数字经济的爆炸式发展，目前全球有 2700 万软件开发人员。预计到 2030 年，这一数字将远远超过4500万。当前，这些开发人员中有 1900 万是API开发人员。到 2027 年，应用开发软件市场的规模预计将增长 196%。我不知道你怎么想，但我认为这是一个巨大的市场。

随着 API 行业的快速发展，开发人员和技术领导者都需要知道如何使这些努力取得成功。承担这些重要角色的人们越来越需要理解，如何构建一个成功、可靠、可扩展的 API 项目，从而推动业务价值的实现。

从哪里入手？最重要的考量因素是什么？

这当然很复杂，但我在这里要告诉你的是，要考虑的最重要的因素是在 API 策略中采用设计优先的方法。作为开发人员，下一个 API 杰作会从我们的指尖产生；我们只需要先设计好它。

践行 API 策略的方法

好吧，你有一个很好的 API 想法，可以让企业受益，但接下来呢？

你可以从编写 API 的业务需求开始，然后编码实现。或者，你可能决定先用规范语言（如 OpenAPI）来描述这个 API。你甚至可以说服组织采纳你的想法，将其转化为 API 优先的产品。选哪一个呢？

最常见的方法有代码优先、API 优先和设计优先。让我们逐个看下它们的优缺点。

• 代码优先：当开发人员需要快速部署 API 时，在收到业务需求后直接进行编码可以加快 API 的部署。有时，如果 API 只有几个端点，这是最快的选项。简而言之，代码优先是完全面向开发人员的，不关心其他潜在的 API 用户。

代码优先方法的问题是，以这种方式开发的 API 即使设计良好也注定要失败，因为 API 的成功是基于越来越多的用户使用。随着使用人数的上升，大多数新用户将不再是开发人员或懂技术的人——他们只是希望尽可能快速有效地解决问题。如果一个 API 不直观，不适合他们的环境，一般人就不会用它。

• API 优先：这是一种人们越来越推崇的方法。基本上，这意味着组织将把 API 作为核心关注点，并将它们视为组织运行所基于的关键业务资产。这个过程始于用 API 描述语言（如 OpenAPI）编写契约。这种方法本身并没有什么问题。而且，尽早对一个平台或一组产品进行标准化是明智的。问题在于，所选择的语言以及这种语言所固有的特性往往主导甚至限制了公司扩大规模和面向未来的能力。如果 API 是最重要的东西，那么对于所有开发和/或使用它的人来说，这又意味着什么呢？

• 设计优先：从根本上说，这意味着任何 API 工作——无论一个程序中有一个还是多个——都从设计过程开始。在这个模型中，在编写任何代码之前，用人类和计算机都能理解的方式对 API 进行迭代定义。我们的目标是让每个团队都说相同的语言，并且他们使用的每个工具都利用相同的 API 设计。与 API 优先的方法相比，这里有一个很关键的区别，鉴于 API 非常重要，设计过程确保了所有涉众都参与其中，并且他们的需求在创建过程中得以满足。

在设计优先的方法中，每个职能部门的技术和非技术人员一开始就参与进来，编写定义 API（或一组 API）用途和功能的契约。显然，这种方法需要提前花一些时间进行规划。这个阶段的目的是确保开始编写代码时，开发人员编写的代码在以后不需要废弃和重写。这有助于创建可迭代的、有用的 API，进而获得一个整体上更好、更可扩展的 API 程序——为业务创造价值。

无论选择哪种方法，最重要的是要考虑如何为利益相关者提供积极的体验，包括最终用户、第三方或内部开发人员，甚至来自公司其他部门的人。我认为，API 就像技术大使——品牌的数字化面孔——因为它们形成了一个内部和外部连接的网络。因此，应该精心设计和制作，就像公司提供的任何其他产品或服务一样。

成功的 API 项目会让用户尽早参与到设计过程中，以确保开发过程符合用户的期望。这个步骤对于内部和外部 API 同样重要。参与该过程的用户很可能成为早期采用者，最早推动人们接受和使用产品。

在 API 开发中采用设计优先方法的好处

“但是，Steve！（你可能会问）这种方法如何使开发人员、最终用户、内部合作伙伴以及其他更多的人受益?”好问题。让我们从最有价值的 API 开发资产开始：开发人员。

• 提升开发体验：设计优先的方法有许多好处，但最重要的是创造良好的开发体验。作为一个从事过开发的人，我可以告诉你，修复编写糟糕的 API 简直是一场噩梦。

如果没有特意进行设计，开发过程可能就会混乱、死板、脱节，在开发人员、安全、治理和文档团队之间造成隔阂。最终的结果是，开发人员要一直承受着巨大的压力把 API 开发完。

采用设计优先的方法，API 规范、治理、设计、开发和文档同时开始，开发和维护并行进行。这种内置的协调机制使开发人员可以专注于开发解决方案，并防止 API 清理工作拖慢他们的速度。设计优先是对开发人员友好的，使他们投入其中，专注于最终结果，而不会因为编写糟糕和不一致的 API 而分心或延迟。最终，快乐的开发者=令人快乐的 API 程序。

• 工程效率和成本节约：当使用设计优先方法开发出高质量的组件时，就可以在未来的 API 中重用。每个组件只需要构建一次，为技术团队节省了大量的时间和金钱。所有组件可重用可以显著节省开发的时间成本，同时提升新 API 推向市场的速度。

• 提升 API 安全性：尽管 API 在过去几年里蓬勃发展，但其设计缺陷和脆弱性，也使它们成为黑客和恶意软件的主要目标。如果不进行适当的设计，暴露的 API 端点很容易被黑客利用。作为技术领导者，安全一直是我最关心的问题，有意识地进行安全设计可以确保安全从一开始就构建到 API 策略中。

• 内部团队之间更好的协调：众所周知，大型跨职能团队很难协调，而让更多的利益相关者参与进来，并让所有人都达成共识，则是一个更大的挑战。使用这种方法，相关利益相关者从一开始就参与进来，在开发 API 时就可以考虑他们的输入。让所有利益相关者参与，甚至是那些 API 的非技术用户，确保 API 的设计可以兼容并满足所有可能的需求。

• 增加创新和增长机会：API 是实现增长、增加创新、改善用户体验的催化剂。从一个昂贵、低效的流程转变为对开发人员、客户和最终结果都更有利的流程比你想象的要容易得多。根据2020年开发者调查报告，目前有超过 40%的大公司使用了 250 个或更多 API，而且还会持续增长。据估计，每天新发布的公共API有2000个。

随着 API 的迅速增加和日益普及，它们现在几乎涉及世界上的每一个行业、领域和地域。作为技术之间的集成点（顾名思义），从汽车制造商到医疗保健，API 在各种公司中都很流行。例如，我们最大的客户之一就是一家全球啤酒制造商。我敢说：在 API 设计和开发方面，你不会首先想到这家公司。

我们知道，许多最重要的创新机会——跨行业、公共和私营部门——都是通过 API 获得的，这不是开玩笑。这就是正确地设计 API 以适应这种增长至关重要的原因所在。

好吧，但是设计优先真得有效吗？

我知道，你可能不愿意相信我的这个说法——“设计优先改变了 API 项目的游戏规则”——但我有几个案例可以证明这一点。

Transact 是一家校园服务科技公司。通过在 API 项目中采用设计优先的方法，他们将 API 开发时间减少了 80%（还记得我之前提到过的时间效率和成本节约吗？瞧！）。

Transact 公司高级工程经理 Paul Trevino 说：“比缩短开发时间更好的是，当使用设计优先的方法时，我们与其他团队的合作增加了，我们更早地获得了反馈，最终结果更优雅也更具专业水准”。

另一个案例是 Calendly（我经常使用的一个会议安排软件）。它有一个 API 团队，用设计优先的方法构建了一个全新的 API 平台。

Calendly 应用架构师 Dmitry Pashkevich 说，“对我们来说，设计优先的方法带来了更高质量的实现、一致性、治理水平和永不过时的文档。无论是对 API 生产者来说，还是对 API 消费者来说，这都很重要；文档永不过时，质量很高而又非常详细，所有这些好东西都是你期望从一个成熟的平台获得的。”

如何实施设计优先的方法？

好了，经过上面的讨论，是时候向你介绍一下如何在自己组织的 API 策略中实施某种设计优先的方法了。聚焦于去中心化治理、提高自动化程度以及通过编程风格指南等工具实现一致性，将引领你走上设计优先的成功之路，并通过最大限度地降低 API 消费者的复杂性来改善你的 API 项目。

从一致性和“良治（Good Governance）”入手

有句话说，如果你别无所长，至少可以有一致性。像星巴克这样的公司做得这么好是有原因的：这是因为我们知道可以期待什么。无论你在世界的哪个地方，当你走进星巴克的时候，体验都是可预期的，这让人很舒服。

现实世界中的人机界面（如星巴克）是如此，API 也是如此。保持 API 设计的一致性——体验可预测——至关重要。正如我们在 Stoplight 的说法，一致性是一堆 API 和一个结为一体的平台之间的主要区别。

为了保证一致性并持续进行完善的设计，在 API 策略中制定指导方针为执行标准提供了可能。API 风格指南是方便开发者或开发者团队在创建或使用 API 时查阅的所有相关信息。通常，风格指南参考提供了 API 的基本说明，从中你可以了解到它们是什么，以及在组织中创建、使用和实施的最佳实践。

这种一致性需要你对 API 项目进行强有力的管理。如果项目在设计时没有考虑 API 治理，标准化很快就会落空。API 治理是指对 API 应用规则和策略，如描述、契约、设计、协议、评审等。在设计 API 时，这种标准化有助于确保所有 API 保持一致，即使它们由不同的开发人员设计和构建。有效的治理计划可以帮助组织确保每一个 API 都是高质量且可发现的——无论他们是创建几个 API 还是几千个。

将 API 视为产品

应用设计优先方法的下一步是务必将 API 视为产品。API 即产品（API-as-a-Product）是一个成熟的、越来越流行的软件开发概念。本质上，它是说你要像人们消费或使用任何其他产品一样来操作 API。API，就像产品一样，应该易于使用，并得到积极维护和支持。

API 设计过程包括你为产品所做的规划和架构决策。就像产品设计一样，从 API 设计中可以看出用户体验，良好的设计原则可以满足最初的期望，并且可以持续地保持一致和可预测的行为。

获得利益相关者的支持

实施设计优先的方法，其中一项最重要的工作是获得所有利益相关者的支持（这也是设计优先方法的主要观点）。为 API 项目打基础，意味着你需要获得开发者的认同、管理者的认同、早期最终用户的反馈，以及任何其他可能与 API 交互的合作伙伴或内部人员的意见。

对于争取业务负责人的支持，我的建议是把重点放在业务价值上，最好包括可信赖的指标和概念验证。即使你一开始只有极少的数据可供展示，也要把它们用起来，让人们看到随着时间推移的不断改进。当你把球滚动起来的时候，势头自然就有了。一旦你获得了这样的支持，就可以开始考虑如何将这一任务转化为组织转型，以及这一目标的实现需要哪些关键人物。

为了获得开发者的支持，就要创造一个安全的空间，让他们能够自如地表达意见，并且还要创造一个空间，让他们可以测试什么可行（当然要有一套准则）。找到在开发组织中具有关系影响力的利益相关者，并基于你的 API 策略和他们确立合作方式（最好通过 API 设计工具来实现）。API 项目团队必须是一个多学科团队，拥有广泛的经验、用例和技能。

最后，一定要从早期采用者和最终用户（贯穿始终）那里获取反馈，了解关于 API 消费的实际体验。请记住，如果没人使用，它就没有用，所以它要能够提供一个积极的体验。有时，开发人员会忽视最终用户的体验，但设计优先的方法可以确保这一点始终得到足够的重视。

那么，我说服你了吗？

感谢你和我一起深入探讨设计优先方法。我希望你现在已经了解，它是确保 API 或 API 项目完善、健壮、易扩展的关键。（而且，如果你忽略我的提醒，可以点击这里，看看不遵循设计优先方法会发生什么。）

如果你需要一份指南，那么我强烈建议（我可能有偏见）你看下 Stoplight 提供的有关API设计的资源。

总的来说，我们知道 API 正风靡全球。为了创新和发展业务，几乎每个人都在寻找方法，以便可以构建出成功的程序。到现在为止，我希望你已经看到，如果不事先设计，就无法创建出一个 API 杰作。

就我个人而言，我倾向于认为，开发者是世界上最好的设计师和创造者，我迫不及待地想看到，你接下来会用设计优先的方法创造出什么。

作者简介

Steve Rodda 自 2020 年 7 月起担任 Stoplight 的 CEO。在此之前，他是 Cherwell 软件公司的首席运营官，负责为客户提供端到端交付、IT、支持、研发、产品管理和专业服务。在此之前，他曾在 Solarwinds 和 LOGICNow 工作，有 20 多年的科技行业经验。Steve 毕业于加州州立大学，获得了计算机科学学士学位。

原文链接：

Design-First Approach to API Development: How to Implement and Why It Works and How to Implement It