PayPal 系列教程（二）：解密大规模 API 转换

关键点

• 为业务定义一个能力分类
• 把 API 视为产品来进行讨论和思考
• 使用以客户为中心的过程来管理 API 组合（Portfolio）
• 从 API 中解耦出服务实现组件
• API 演化是文化上的变革，并不是一个一次性的项目

这是总共三部分中的第二部分，这部分探究了 PayPal 是如何应用更多的 API 优先方法来构建平台服务的。在第一部分中，我们探讨了 PayPal 为什么将业务迁移到一个松耦合、API 驱动的架构，并了解了 PayPal 的一些能够完成大规模任务的基础架构。在这篇文章中，我们将会深入了解 PayPal 是如何管理它们的 API 组合（Portfolio）的。

要让每一笔 API 投资都有意义

你们一直都在构建新的功能。理论上，这些投资中的每一部分都是由一个合理的、深思熟虑的策略和路线图驱动的。

然而，现实中的情况可能会复杂一些。我们倾向于将路线图视为优先投资中不可分割的一部分，它有助于我们实现战略目标。然而，随着时间变迁，一些现实情况开始浮出水面。首要的就是，我们的即时执行计划往往会受到数量不多的高优先级项目和重要合作伙伴的严重影响。这在一定程度上源于大家希望能有一些有形的目标来让大家团结工作，同时另一个原因是，对时间敏感的交付品往往会得到更高的优先级。我们可能和一个大客户签订了一项重要协议。我们也可能收购了一家需要被整合的公司。这样或那样的功能就需要在我们的假期之前被剔除掉。这都是些非常真实的项目，有着真实的日期。事实证明，受到现实情况的影响，我们细致的、战略上一致的、哲学上合理的路线图会更多地受其它事件的驱动。

这是一个问题吗？其实并不是。站在实现团队共同目标和保证团队聚焦于最重要业务的角度来看，这并不是问题。它有助于调整组织。表现在战略层面的挑战是，我们把美好的平台愿景简化到一个狭义的解决方案。那些负责完成实际工作的实操人员就会很自然的对他们完成的工作持乐观态度。他们的上下文会成为直接的项目，这就意味着他们倾向于在这些解决方案的边界之间作出决策。

对于一个 API 优先的组织来说，这是一个巨大的挑战。我们试图构建一个可复用的功能集，并且它不会仅适用于特定合作伙伴或者特定项目。我们希望我们的技术投资能够将效果最大化，这就意味着，我们要去构建通用的、可复用的 API，使得它们能够应用在多种环境中。我们不仅需要满足由投资驱动的当前项目的需求，还要满足我们没有预见到的未来项目的需求。正如所能看到的那样，狭义的、项目驱动的路线图催生了一个更宽泛的目标，那就是最大化平台服务功能。有了这些限制，我们如何才能防止在服务设计中做出狭义的、目光短浅的设计呢？这种设计会限制我们未来业务的敏捷性。

识别你们的业务能力

问题空间的定义对如何解决问题有很大影响。有助于帮助我们始终都是构建平台功能而不是仅仅着眼于解决方案的一种方法是，明确定义构成业务的功能。这些就是你们的问题空间。

业务能力（Business capability）体现了业务的核心、可重用的构建块，这些都是支持业务正常运转所需的业务流程。通过定义业务能力分类，就能建立一种共享语言，全部的域都可以使用它来描述给定业务流程中的逻辑关系。这是一个稳定的、业务驱动的（并不是技术驱动的）环境，如果顺利的话，在这个环境中讨论解决方案会随着时间的推移保持相对一致。它同样建立了一个关键的连接，把在商业上如何看待其投资和在技术上如何利用它们连接了起来。

在一个小公司中，能力的集合是很有限的。由于资源高度受限，你们可以构建一些核心服务用来区分业务，并且利用其它服务提供商提供的一些通用服务，像消息推送、身份识别、支付等等。管理它们并不困难，因为它们很适合核心团队的负责人进行管理。然而，把它们记下来并清晰地对其进行定义仍然十分有益，但是这项管理工作可以由单个架构师或一小组紧密的利益相关者来完成。这样做基本不需要正式的流程，通常情况下是可取的。

当你们的组织发展壮大，情况就不一样了。如果你们有数百个分布在各个业务部门和产品线的 Scrum 团队，跟踪你们的业务情况和避免重复投资就变得很难了。为了解决这个问题，你们需要一些模型或者系统来追踪和管理不同拓展组织之间的 API 组合（portfolio）。这本身就是一个“项目”。

在重构 PayPal 平台时，我们很清楚目标是什么。我们花费了一年中的大部分时间来分解业务流程，为的是找出我们的核心业务能力。去理解全部数千万行代码是非常困难的，但是通过遵循 80/20 原则，我们得到了一个不错的起始分类法，我们用它来分类和管理我们想要构建的 API。也许对我们来说最重要的是，它给了我们一个通用语言来描述最终状态的边界。我们使用它来和各个域负责人进行建设性的、辩护性的并且大体一致的对话，来讨论他们正在构建的 API 和服务。

这个小例子展示了我们是如何定义业务能力的，并且是如何将它们进行分组的。这些组表示包含相关功能的更高级的域。注意，下图仅仅是全部模型一个简化版本。

我们在 7、8 个高级域之间共找出了超过 70 种业务能力。在过去的几年中，随着我们的模型成为了一项业务，并且更好地理解了各种业务流程，我们就围绕业务边缘逐渐调整了模型，但是最初的原始模型仍然是一个很有价值的基础。

当你们开始这样做时，去看看行业中的其它例子是很有帮助的。在我们的案例中，我们从银行业所开发的模型中学到了许多东西，因为我们和银行业有着许多相同的行业概念。尤其是 BIAN 模型给我们提供了许多帮助。当我们的业务和传统银行业产生分歧时，我们用其它行业中的业务能力扩充了 BIAN 模型。我们也为一些独有的业务做出了创新。这些独特的创新才是很有趣的部分，因为它们代表了你们所做的最具有差异化的和竞争力的能力投资。

在整个过程中，我们与整个公司的团队合作，验证我们的假设并且获得他们的认同。域架构师是关键的贡献者，但是你们也要注意，不要让当前的实现过多地影响到你们的业务架构定义。请记住，业务能力边界和业务能力语言应该受用户用例和支持它们的业务流程驱动。如果最终结果对你们组织之外的人没有意义，你可能需要重新审视它，并且你需要更努力地去调整内部实施和组织偏见。

转变想法，把 API 视为产品

不仅仅在定义业务能力边界时需要站在以客户为中心的角度考虑问题，在定义实际 API 的时候同样需要以客户为中心。工业界需要一段时间才会意识到，API 是产品。API 有用户，它们能解决问题，它们必须易于理解，使用它们的体验必须要好。你甚至有可能把一些 API 卖给客户，换成钱。对于许多工程界和产品界的许多人来说，这是一种全新的想法。

原因非常简单。由于在工程中需要连接各个系统并且需要提升模块化程度，API 应运而生。它们是“如何做”的一部分，它们对于当前项目之外的作用对许多人来说并不明显，尤其是产品经理。还请记住，我们的短期路线图往往针对相对狭义的项目成果定义成功。在制定 API 设计决策时，人们往往更加倾向于短期见效的优化而不是通用的可重用性，这一点也就不足为奇了，因为后者需要付出更多的努力。在项目执行的压力下，你为什么不去关心与你的薪水无关的 API 设计就变得容易理解了，因为你有一个截止期限要赶。

在 Sprint 中，每一个决定都是战术。

API 优先策略让我们意识到，如果设计好接口，并且注意通用可重用性，它们将会成为今后构建业务流程和产品的基石。你现在的投资会在日后收到回报。如今的挑战就是克服对项目优化决策的偏见，并且转变想法，把 API 视为产品。接下来让我们看看一些能够促进这一点达成的做法。

像客户一样去交流

第一件事就是从一个客户的角度开始讨论你们的 API。站在外部人员的角度来看，我们要采用一种易于他们理解的语言来描述业务功能。在你们的 API 分类中或者描述 API 的文档中应该禁用内部概念、密语和缩略词。使用以客户为中心的语言，将概念性业务能力和相关 API 从底层物理实现中剥离出来。这样做能让你们的 API 更易于理解，并且对于领域外的人来说也更有用。这样做是很要必要的。

第二件必要的事情是，请谨慎地命名你们的 API 和资源。这件事看起来微不足道，但是当你去理解你的 API 组合时，你就会知道 API 的命名是很重要的。你有时候可能会忽略，API 是提供给人去用、去理解的。计算机只是去做你让它们做的事情，名字并不重要。但是一个普通人需要依据你提供的 API 的名称来阅读、理解、概念化、总结这些方法。如果你使用了一些含义隐晦或者不直观的资源名称，你就增加了认知负担，这会使开发客户困难重重。对于想要用你的 API 的人来说，集成的成本就提高了。

管理 API 产品组合

如果你阅读了这个系列的第一篇文章，你会注意到对接过程中有一个步骤叫做“对齐（Alignment）”。这是在更大的能力组合之中识别出 API 位置的关键。这是至关重要的一步。你需要从这里开始考虑 API 需要支持的通用用例并且你还需要考虑去选择最合适的词汇去命名你的资源和接口的行为。

一种最好的实践是，把 API 正在解决的用例写下来。如果你强迫自己去写出优秀的客户用例，能够作为资源的关键词及其相关的动作就会从纸上自己冒出来，这是非常令人兴奋的一件事。答案往往自己就蹦出来了。这样一来，验证它是否适合于更大的 API 组合环境中也就变得更容易了。

挑战在于，大多数产品经理不参与到 API 的设计中，并且大多数开发人员在使用用例方面不去考虑他们的 API。开发人员往往只去考虑如何实现。如果你让一个开发人员去写一个用例，他可能会写下如下的东西：

我需要收集 region_2 的数据，把它插入到 legancyFoo 表中，为的是让 oldService_B 返回一个结果。

但是这样描述对于领域之外的人没有任何意义，同时它的结果可能是产生了一个同样晦涩难懂的 API。请相信我，我们所看到的比这个还要更糟糕。后退一步，去分析下产生这个业务流程的需求，之后得到一个如下的用例：

作为一名客户，我需要提供完成这笔交易所需的全部地址信息。

这样的描述对于一般人来说更好理解。一开始就把重点指向了一个叫做“地址”的潜在的资源。参考我们的模型，我们还能推断出这个地址可能和身份验证域中的账户能力有关。现在，我们就能轻易地看出这项能力内的其它 API 是一个新的资源，还是针对之前资源的拓展（或者是已经重复的功能，我们就能避免再做一遍）。

了解业务流程

把“流程”这个词想象为人们在退出一个拥挤的房间。乍看上去，这样的描述似乎和“有趣”以及“创造力”这样的词汇格格不入。事实是，由于流程的存在，才激活了决策的可扩展性和结果的一致性。虽然希望和梦想是很好的动机，但是你们仍然需要一些有形的东西来确保 API 组合能够稳健地发展下去。挑战在于快速、高效地实现业务流程，并且能够给你们的开发者客户们带来可见的增值。如果成功了，你们就已经把这个“业务流程”变成了一个有形的资产，这个资产对于开发者来说就是他们一直在找的更易于他们谋生的东西。这是对于所有有价值、生命长久的业务流程的一种至关重要的有效度量方法。

我们在 PayPal 所采用的主要方式是要求所有的 API 都要经过一个通用管理过程。我们有一个小的、中心化的、基本上自治的团队，由这个团队作为 API 组合的主要管理组。它由两部分人组成，一部分人是和利益相关者打交道的技术产品经理，另一部分人是各个业务领域的架构师。他们同每一个团队合作，来帮助大家定义他们的通用用例，推荐最合适的词汇去命名 API 名称、资源和端点。

起初，不如人所愿，这个模型遇到了许多阻力。我们仍然仅仅是站在了做完东西的角度，采取着官僚化的步骤。开发人员总是倾向于等到最后一分钟（通常是在几乎全部都实现了之后）才参与进来。这给双方都造成了很大的麻烦。随着时间的推移，大家的态度转变了。团队经历了几次这种麻烦之后，大家开始意识到了暴露出更多易于理解的端点接口（带有良好文档）的价值。他们的客户会有更少的问题，他们的支持开销也减少了。

如今，我们看到了许多团队在软件开发周期的早期就参与到了 API 组合对齐过程中。许多人主动在 SDLC（系统生存周期）早期主动寻求建议，因为他们看到了他们的通用方法是如何得到更简洁的接口和实现的。除此之外，客户视角和业务架构模型影响到了他们对长期架构实现的思考。这样有助于他们同业务保持一致步调。许多团队正在对他们的 API 进行第二次或者第三次迭代，向着更简洁、更简单的模型发展，这有助于他们更好地为客户服务。最重要的是，开发者们开始体会到不是所有的事情都需要他们亲力亲为。他们看到了这个业务流程的价值，它能帮助解决当前问题，这极大地鼓励了开发人员重新回来解决问题。

去和客户交流

获取用户反馈，了解他们的需求并且验证他们的满意度，这些当然都是一个合格的产品经理的主要任务。当你把 API 看做产品之后，你的主要客户是开发者们。

大多数人并不是这样看待 API 的。重申一次，API 开发通常由项目目标所驱动，同时也是由项目目标来度量成功。API 是达到目标的手段。我们该如何改变这种行为，使得开发者实际使用 API 的体验被真正重视起来呢？

为了鼓励这样做，我们在 PayPal 做了如下的事情：

• 在设计评审过程中，我们鼓励 API 开发人员同他们的客户进行联系，获得客户对他们设计的反馈，并且和客户合作，确保文档是完整的、易于理解的。
• 所有的 API 契约都在大家所知的 Github 仓库中进行管理，所有人都能订阅、评审修改并且提交 pull 请求。
• API 门户包含指向团队 Slack 的频道链接，因此客户能够轻易获得帮助和提出问题。
• 我们会在 Slack 上发布所有 pull 请求，以便 API 客户能够持续关注他们所感兴趣的 API，并且会在 API 改动后收到通知。
• 客户建议、缺陷和问题都可以通过 API 门户提交，这些都会在包含有 API 规范的同一 Github 仓库中自动追踪。

所有这些工具都很有用，但是在一天结束后，API 开发人员有理由去关心客户体验。管理层必须要及时进行激励，并且管理层必须意识到激励的重要性。某些形式的工具是用来衡量每个 API 开发者多大程度上满足了他们的客户期望的。这是我们刚刚开始探索的领域，因为我们正在寻找更多能带来良好 API 客户满意度的强制性行为。再次重申，这是一项需要花费时间的文化上的改变。它不一定根植于你们的组织 DNA 中，你们需要尝试不同的方法来形成这种肌肉。

产品经理的职责

我们一直都在谈要将 API 视为产品，却还没有提到产品经理的职责。它很可能因组织而异。如果你们是一个非常技术性的产品管理组织，大家可能会很积极地参与，都希望能带头做。他们本身就能理解主导谈话所能带来的需求和价值。API 组合管理就成为了所有领域的联盟，而产品是一个高度参与的利益相关者。如果你所处的情况就是这样的话，那无疑你是幸运的。

如果你们本身没有一个技术性的产品管理团队，那么组织一个中心化的团队来承担这个职责并且协调整个平台可能是唯一实用的短期解决方案。这其中的许多都将取决于你们组织的动态、文化和熟练程度。随着时间的推移，你们可能朝着更加分散的模式发展，因为你们将要加强产品组的技术能力（并且调整激励措施）。在有些领域我们还曾见到过很有驱动力并积极参与的产品经理，因此将这些方案进行组合也许是更合适的方式。你们需要确定组织中产品经理的参与程度并且定制你们的方案。

逻辑解耦与物理解耦

当谈论 API 时，我们谈的是服务交互行为的逻辑定义。实现 API 的服务是实际的、物理上部署的组件，它们会服务于请求的处理。很容易就能做出一个假设，它们之间的关系是 1：1 的。但是你应该去质疑这个假设。

我们发现这种关系可能有许多种。这有几个原因：

• 实现 API 的遗留服务正在被替换为遵从同一协议的新服务。这种替换方法逐步完成，并且存在交迭的时段，在这个阶段中，其中一些终端由遗留系统提供服务，而另一些端点由新系统提供服务。这样做的优点是，部分遗留的旧服务可以在每一个发布版本中进行替换，减轻了一次性替换一个大型服务的风险。
• 有时，两个 API 在实现上存在重叠，开发人员希望使用同一个服务来实现两个 API，这样做可以节省时间和开发精力。
• 有时对于一个 API 来说，读取和写入活动严重不平衡，架构上的解决方案是将读取和写入拆分为两个单独的服务。
• 有些不良的、目光短浅的或者是组织结构驱动的架构决策会导致这种关系不是 1：1。基本上，糟糕的设计或者是日期驱动的决策有时使得大家进行妥协，在损害完全封装这一目标、构建具有良好边界的服务和 API 关系之间做出折中。

显而易见，你们应该保证 API 协议和实现代码在不同的仓库中。这能让你们轻易地对 API 关系、API 生命周期和服务进行解耦。事实证明，API 生命周期由 API 版本控制和向后兼容性策略所决定。服务的生命周期可能由一些正交的问题所驱动，比如漏洞修复和对操作质量（如性能和可用性）的改进。只要能够始终遵循 API 契约，解耦能够使得每个部分都能独立的演化。

解耦也强化了 API 合同是产品中的最重要的部分这一概念。它应该驱动实现（API 优先），而不是相反。如果每个组件（artifact）的维护过程有着清晰划分的话，这种角色的反转会更易于得到强化。

当涉及到业务流程时，控制的问题是很重要的。在 Paypal，我们对于谁可以合并 API 中的更改保持着严格的控制。每一个变更都会基于 API 组合来进行考量，并且会根据标准得到一个成熟度分值。有一个中心化的团队会负责大部分相关的工作。随着团队的成熟，我们已经在整个组织中培训和授权开发人员，使组织以一种更接近联盟的方式来运作（更多内容详见下一篇文章）。即使如此，我们仍然尽量避免开发人员合并自己的更改，我们鼓励能尽可能多地促进跨域协作和审核。

最后，反对康威定律的斗争还在不断上演。

设计系统的组织，其产生的设计等同于组织之内、组织之间的沟通结构。

——M. Conway

开发人员从他们团队的任务中获得认同。在一个团队重组之后，他们喜欢做的第一件事就是创建一个以他们的团队名称命名的新服务：slicedbreadserv。这个服务代表了他们未来的工作和对组织的贡献。目标是构建稳定、长期的 API。就像许多其他产品一样，删除它们是需要很大开销的。相比之下，Reorgs 经常发生，并且经常由不同的力量所驱动。将你们对 API 平台产品的定义从底层实现更改的想法中解耦出来是非常有益的。你可以控制其中的一个，但是另一个你一定控制不了。

这是一种常态

我们从开发 API 组合管理规范的经历中学到了很多。我们知道了，可以把自己的思维和行为方式转变为以客户为中心，大规模地转变为 API 产品驱动是可能实现的。有时这样做是痛苦的，甚至是费力不讨好，但是通过倾听和接受双方开发人员的需求，我们已经不断地完善了我们的计划并且提高了内部客户满意度。老话说，开发人员是懒惰的。我们不同意这句话。当开发人员有一个有趣的问题需要解决时，他们会努力工作。他们渴求知识和技能，这些知识和技能能帮助他们更快、更优雅地解决问题。最重要的是，他们不愿意三番五次地解决同一个问题。

采用 API 产品化和设计优先的方式的另一个好处就是，我们能够一次性地解决很多人的相同问题。这自然就显得吸引人和优雅了。对它的理解需要花费一定的时间，但是一旦这样做了你就会知道它的强大之处。我们实现的这套方法论和流程帮我们对组织提供指导。如果你不从文化变革的角度（仅从一个项目的角度）去考虑这个问题，你永远不会明白，这套方法论的影响应该是很持久的。

在最后一篇文章中，我们将深入探讨计划管理的重要性，它会使组织保持一致，我们还会讨论市场化概念、提供培训以及创造各种鼓励采纳他人意见的激励措施。

关于作者

对于如何成长为一个伟大的产品经理，Erik Hogan已经思考了将近 20 年时间。这 20 年时间里，他知悉如何才能成为客户冠军和可信赖的领导者。他成功将复杂问题分解成可复用的各个部分，并且准确告诉工程师需要做什么事情。最近，他致力于产品功能的简单化、写书，以及聚焦于影响组织的变化——一种非常不同的产品类型。此外，每次他问妻子成功的标准时，他的妻子都会发火。

查看英文原文： Untangling an API-first Transformation at Scale. Lessons Learnt at PayPal – Part 2

感谢张卫滨对本文的审校。

给InfoQ 中文站投稿或者参与内容翻译工作，请邮件至 editors@cn.infoq.com 。也欢迎大家通过新浪微博（ @InfoQ ， @丁晓昀），微信（微信号： InfoQChina ）关注我们。