作者 | Jason Harmon

译者 | 马可薇

策划 | 丁晓昀

(资料图)

对大规模的 API 设计而言，一致性是需要花些功夫才能实现的。API 的胡乱堆砌和正经平台的主要区别就在于一致性。而在这种语境下，一致性仅仅意味着多个 API 中命名规则、分页等交互模式、授权机制等因素的统一性。

一般来说，评审委员会如果在人们以为工作已经完成后才延迟发现问题，将会给 API 开发者们带来心理创伤。更糟的则是委员会的设计取而代之，从而导致进度拖慢，或者开发者们为求免遭痛苦而想尽办法避开这一过程。

若想完全解锁现代平台，去中心化的治理是更易于伸缩和参与的方式。这种方式仅需要在每个领域或功能区都安排一位接受过标准和整体架构训练的专题专家，为 API 开发者们提供良好的引导。

更为重要的是，在大部分开发工作完成之前便确定 API 设计，可以在很大程度上避免在最后一刻才发现问题，从而影响交付时间（通常被称作是设计优先方法）。通过 OpenAPI（HTTP/"REST" API 的事实标准）等规格格式，可在所有的开发工作开始之前便定义 API，从而更早地进行调整并识别问题。

了解这一背景后，让我们来进一步分析 API 的设计评审要如何开展，流程如何制定，如何让组织做好准备，从而避免拖长的时间表和匮乏的开发者参与感。

下文中将列出部分能确保这一过程顺利的关键先决条件。

API 的使用是一项极为精炼的体验，因此语言在其中的影响相较于其他多数设计领域而言，所占据的比例要高得离谱。团队中对不同术语的定义和描述可能会因人而异，其表现形式便是 API 团队的混乱和生产力的下降。

虽然 API 门户或文档是良好开发者体验的必需品，但设计优秀的 API 应在无需这二者的情况下便能清晰表述大部分内容。消费者如果熟悉某个术语，且交互模式明显，那么这段体验将会是快速且无痛的。一致性是 API 的堆叠和真正的平台在体验上的主要区别。

从共通的语言开始，建立 API 的计划和治理流程。虽然这样乍一看并不现实，但为平台定义一个以客户为中心的共享词汇或语法是至关重要的，这将是组织的整体加速器。许多术语可能在公司内部都有不同的涵义，再加上终端用户甚至大多都不认识这些术语。

提前做好这些功课可以避免在 API 设计的过程中因命名而产生冲突。与相关的利益相关者一同定义每个领域中的共通术语，确保 API 设计的广泛使用和了解。确定了内部术语的标准化后，别忘了检查其是否也符合外部的需求。通过使用客户语言和以客户为中心的 API 开发视角，可帮助团队避免因为使用客户不熟悉的技术术语而带来混乱，为此，请确保内部理解和外部理解的同步。

API 的消费者在面对 API 之间不同的模型或参数时，可能会遭遇一段困惑、沮丧且耗时颇长的过程。举例来说，一个使用联系信息的 API 与同平台下另一个 API 使用了完全不同的模型，消费者将被迫去处理这二者之间的差异。更糟糕的是，处理数据的系统性差异将会进一步扩大，从而造成功能性上的差异。

尽早确定共用的组件（模型、参数、头，等等）和支持其的系统，通过在 API 定义中将共享组件相连，可确保后续对这些组件的修改可轻松在推广至全平台，减轻 API 消费者所不必要的认知负担。

所使用的共用组件越多，提升一致性、可复用性，以及后续合作和效率提升的机会便越高。开发者们都喜欢不走回头路的“DRY（Don’t Repeat Yourself） 方法”。共享组件越多，创新也越容易，人们不需要一次又一次地从头开始，重复同样的事情。共享组件还可让团队更迅速地扩展，更轻松地培训 API 团队之外的新开发者或利益相关者。

多数简单的命名规则、交互模式，以及认证机制，都能提供风格指南的自动化，并提早标记出不一致之处。

首个风格指南是于 2013 至 2015 年间制定的，为 API 的开发团队定下了外观和体感（又称 DX）的期望值。一致性的设计需求在 API 平台开发之初就很明显了，在 Paypal（当年作者也是这个团队的一员！）和 Heroku 的早期共同努力下，第一批成功项目的设计指南得到公开分享。

虽然能用于协助风格指南的自动化工具有很多，但开源工具 Spectral 已成为定义 API 提示规则集的标准。先对路径、参数等约定俗称的规则进行调整，定义自动提示规则，从而避免因纠结“正确”的规则而带来的冲突。规则一经探讨和确定，就尽量不要再反复讨论这个问题，让错误的提示消失就好了。

至于无法自动化的设计标准，应将其记录并使其便于 API 设计者获得。通过培训解释自动化和人工验证规则的重要性，可以为开发者建立全心全意支持这项举措的动力，避免意外和摩擦的发生。

虽然应设置一个 API 启用的团队负责策划这些设计标准并促进社区的发展，但也应在每个功能区或领域中启用权威。

API 标准固然重要，但系统约束、特定客户需求、组织优劣势等领域知识，最好还是由该领域内的专家来处理。如果指望着集中化的 API 启用团队成员了解公司的一切，那么交付延迟和开发人员脱离这些瓶颈几乎注定是会发生的。

培训课程可以成为传播 API 标准重要性的有利技术。此外，人们往往会找到合适的中小企业提供管理权限。寻找那些对 API 表现出热情、对一致性和标准相关性的知识，且在技术上能得到其他同行或上级尊重的人们（作者常称其为“叛逆者”）。

成功的 API 开发会涉及组织内的许多人，这些人往往具备截然不同的技能，有的人会构建和部署 API，有的人则能在商业问题的战略层面确定 API 的价值。在探讨设计审查需要牵涉的人员时，别忘了商业利益相关者。通常情况下，仅关注技术方面可能会导致后续的失败。视角越广越好！

平台内部的产品经理应在 API 组合或目录的整体构成上达成一致。分类有许多不同的形式，它们能对 API 进行整理，让人们在无需清楚明白自己目标的情况下，更轻松地找到自己要找的；也允许潜在用户按功能或其他用户的关注分类浏览可用 API。

好的分类应具备搜索和过滤功能，允许开发者轻松缩小选择范围；也应为分类中的每个 API 提供可对比、可接受的细节，让人有清晰的前进路线。

尽早通过用例和基本命名的功能性概述，对任何新推出的 API 进行审查，以确保语言的一致性、可复用性，以及新 API 与大平台整体的“契合度”。

启用团队中的产品经理负责组合的调整过程，团队成员则应各自负责一个可管理的领域集合。至少也要为特定领域的产品经理提供一个定期讨论的场所。

乍一看之下似乎要做很多事，但别忘了，API 的标准应该通过迭代而发展。随着 API 不断被设计，我们会意识到其中完善标准的机会。认识到这点后，我们应确保在前期的准备工作中覆盖基本知识，并确保 API 主管清晰地认知到要如何提出和采用对标准的修改。

在达成上述的先决条件后，API 设计审核也就基本完成了。对领域驱动的中小企业而言，设计审查通常可被整合到进行中的设计工作内。如果审查能在早期便于平台相磨合，设计审查人员则能更自信该 API 与大局相吻合。此外，如果 API 设计者在迭代过程中发现了错误的提示，那么除了对开发者培训相关提示性规则，以及简单解决提示性错误外，不应再有关于约定俗成规则的讨论。

不是所有东西都能被自动化，有时产品和架构需求会发生冲突。在手动执行管理检查、验证客户语言（这点很难被自动化），以及确定最终一致性之后，再进行 API 设计审查。确立这个时间线后，就不再需要会议时间了，异步的探讨往往便足以。

更重要的是密切关注 API 设计审查的周期。随着时间的推移，更多去中心化的中小企业将对现有标准和新标准的采用更加熟悉，API 设计审查频率也应明显地下降。

/articles/api-design-review/