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

关键点

• 在一个大型组织内部实施 API 优先转型，是技术问题，也有人的问题。
• 组织行为会严重影响 API 优先策略的成功。
• 将转变本身看作是一种促进长期成功的产品。
• 过程与管理缺一不可，但是也需要保证对客户有效及轻量级。
• 不要忽略了对工具、基础设施，以及工作需要的人员的投资。

开始你的 API 策略

一直到不久之前，向外部暴露内部核心业务的想法都是被禁止的。真正的产品是构建于内部逻辑之上的应用程序和经验。大多数产品开发产生了垂直的集成解决方案，该解决方案提供了一套相对有限的功能。如果在完全不同的用户案例或者产品线上使用这套解决方案，通常是不可能的或者难度很高的。在这种场景下，很自然地会考虑底层基础设施，作为沉没成本或者内部唯一管道。很难想象他们的差异点。

情况发生了改变。现在很多公司或多或少有自己的 API 策略，通过可重用服务形式暴露结果，努力平衡技术投资的大部分。高层次目标是，通过让核心业务能力易于访问和可重用，加快业务灵活性。降低集成成本不仅仅对内部的周转率有积极影响，而且也提供了增强了整合客户、合作伙伴和被并购公司的灵活性和速度。单一化、垂直排列的泥球方式正在快速地接近生命周期的尾声。大众称之为“微服务”的理念通过良好的设计和文档化的 API 对外暴露，我们想要的目标是有明确的上下文意义及语义不同的商业价值。

API 经济

为什么会有改变？API 经济的出现改变了规则。

世界上的一些高价值公司，比如 FaceBook、Google、Amazon 等，所有这些公司都在之前解决了这个问题，打开内部逻辑，允许外部程序员访问内部核心逻辑，这种伟大的方式有利于对他们的技术投资，加强了产品组合，并且扩大了合作机会。他们建立了加强共享和可重用原则的企业文化，这是成功的关键因素。这种方式催生了 API 经济，并且让许多产品的构建和市场测试速度很快，也让产品的价格较之前下降很多。API 提供商收获了更多的客户、更多的流量、更深入的整合等等利益，并且对于一些价值数十亿美元的企业来说，又有了新的机会。甚至 Twitter 将它的早期成功归功于这一点开放性策略，虽然后来 Twitter 收回了这样的策略。

第二波公司，例如 Twilio 和 Stripe，直接完全地跳过了传统的“产品”部分。他们制定了核心产品的 API，然后集中精力将提供更好的开发人员体验作为首要目标。他们的客户快速集成这两家公司的产品，从中获得很好的收益，而不需要去自己构建和维护无差异化的功能。敏捷方法提升了。黑客马拉松发生了。应用程序和初创企业爆发性增长。它变成了构建新的经验、迭代以及验证产品市场符合度的默认方式。

为了保护竞争力，作为组织的一员你也需要去接受 API 优先方式。对于你如何看待和思考你的技术组合来说，这是一个很普通的话题。

实现你的未来

对于新公司来说，这种方式已然是第二天性。他们很可能在新的现实情况下成长。但是如果你是一家大型公司，拥有大量的现存基础设施和客户，你该怎么办？如何在保持现有业务正常运行的前提下进行这样的过渡？

首先，你的技术架构可能看起来完全不同。你现存的代码可能受 SOA 影响，在开发微服务之前可能还没有启动，这样就要先放放了。过去的几年里你们可能构建了很多技术债，也没有在公司内部强化整洁组件和可重用组件文化。测试可能存在问题，并且它们可能是公司内部重构或者遗弃项目的剩余骨架。文档可能存在很多不满意的地方。这种基础水平可不是迁移到微服务的理想时机。我们称之为，有很多“挑战”存在。

另一个主要的考虑点是组织行为。高管可能想要推销 API 优先策略，但是执行层的理解可能会有差异。理解你在光谱射线的那个位置对于成功实施 API 有限策略至关重要。

一方面，你获得了曼哈顿项目。巴士站，每个人都 100% 地投入到了这个项目，最高优先级，其他事情都先放到一边。这种情况很少见。如果你发现自己身处这种情况，跟着做起来。把这个项目看成一个大项目，快速地运行起来。你不可能获得第二次这样的机会。

更有可能的是，现实情况你身处某个中间位置。可能执行层有一点降低运行效率，但是总体来说还在前进，随着时间的推进可能需要更换车轮。作为本次转型的领导者，你感到有一些混乱。它们带来了很多困难和重要的问题，而这些问题又没有明确的答案。优先级应该如何排序？哪个团队去做？如何协调？什么时候能好？你的工作变得更加复杂。它不再是一个项目，而是一个会持续多年的复杂转变，这是一个由于技术改造带来的组织变革。

戴上你的产品帽子

在 PayPal，我们针对这样的过程已经花费了 3 年时间。我们从一个整体方式转变为客户导向方式，实现了原本的单一化服务转变为由超过 150 个服务组成的松耦合架构、现代化的 API。

有一种趋势是把这种项目当做工程项目。PayPal 没有这样做。相反，我们把它作为一个更大的、组织化的改变问题，把“产品”作为我们设计和构建 API 的一个根本性转变。从这种角度来看，我们专注于识别和服务所有关键的“客户”- 使用 API 的开发人员以及支持他们的高管人员。这种思维塑造了我们的策略，我们如何沟通，如何评估我们所构建的工具是否成功。找出你的客户，并且聚焦于他们的满意度是一个基本产品原理。这种心态是成功的关键，并且也在持续影响着我们如何管理项目。

虽然没有哪两家公司完全相同的，但是我们学到的许多经验教训和我们已经使用的方法依然适用于面临相同问题的其他组织。

为了打破这一点差异，我们进行了努力，使用了一种叫做“3P’s”的框架。

• 产品（Product）：用于管理 API 组合和基础服务实现组合的基础设施、标准以及工具。
• 组合（Portfolio ）：业务能力目录，以 API 和基础服务展现。
• 程序（Program）：在组织行为和技术投资中激励变化使用的指标、培训和杠杆。

本文是三篇文章的第一篇，深入探讨特点。

产品

一个小公司也许有几十个到 5,6 十个开发人员，对于关键的利益相关者来说，走进一个房间，在白板上做一个计划，划分责任，工作起来并不难。然后会有一个很好的结果，共同理解的计划和目标，并经过一些迭代和计划纠正，你可能会以一个很好的集成、有凝聚力的 API 和基础服务呈现在你的平台上作为结束。你的时间点可能是一个月，也可能是一个季度。

在一些大的组织里，情况又会有所不同。成百上千名开发人员覆盖了很多业务，甚至可能在很多国家工作，所有这些开发人员有不同的目标，通常还是用了不同技术。原因是多方面的，首要原因是 Dunbar’s number ，即你不会有所有人都举起手同意你的想法，并开始着手工作，这样的场景发生。你需要的是更分散、更可扩展的一些事物，在不依赖于社会约束或大型项目的协调性的情况下强化你的目标。在这种场景下，“产品”实质上是支撑转型（不是 API 本身）的基础设施。这是一个重大的自身投资。至少，需要包括以下几点：

• 针对 API 定义通用原则和标准剧本
• 开发 API 时确保符合度的对接过程
• 管理手段，包括明确和客观的度量方式
• 一些集中式门户巩固 API，管理过程和度量

原则和标准

在 Paypal，我们开始了思考共同的想法，这种想法会引导我们达到很好的封装服务，暴露的是精心设计的、可复用的 API。这些成为我们的核心原则，并为我们后续的标准文档设计了许多框架。

• 松散耦合：服务和消费者必须互相松散耦合
• 封装：一种域名服务，可以读取数据和功能，不允许通过其他服务访问
• 稳定性：服务调用必须是可预测生命周期的长连接
• 可复用：服务需要被开发为可复用，即针对多个上下文和多个消费者都可以复用
• 基于对接：功能和数据只能通过标准对接服务向外暴露
• 一致性：服务需要遵循一系列规则、交互方式、词汇表以及共享类型
• 易于使用：服务需要易于使用，并且易于消费者组合使用
• 可扩展：服务需要被设计，即提供的服务可以轻易地被外部扩展

基于上面这些，我们确定 REST/JSON 作为接口标准，并且开发了完整的指南，确保稳定地听过组织内部几百个可能构建服务的 Scrum 团队。这包括诸如 URI 结构、标题的使用、状态码、查询参数、版本控制、资源命名、安全、日志、错误处理、超媒体等等关键要素，我们发布我们的风格指南在这里。

其他我们需要解决的是API 文档使用的格式是什么？我们希望所有的服务开发人员使用相同的格式来记录他们的API，这样我们就可以利用普通的工具和基础设施。

当我们开始做这个事情的时候，API 市场还不太成熟，没有真正意义上的API 标准。最后，我们采用了 Google 的 Discovery Document（GDD），因为它看起来：（a）. 一个很好的选择。（b）. 比大多数都要好。来自社区的支持和吸收观点，这种情况立即就消失了。我们最终开发了相当多的工具，并且支持 GDD 直到 2015 年中期它变得很清晰，OpenAPI（fka Swagger）是我们很多开发人员都想要的。到 2015 年中期那个时间点，我们决定迁移我们所有的 API 到 OpenAPI 规范，并且加入了 OpenAPI 计划（OAI）。它已经开始产生红利，通过减少我们的基础设施投资，通常更强大，我们的开发人员更高兴与它一起工作。

对接过程

当你说“管理”这个词的时候，大多数人的第一反应是不是那么好。这种感觉就像大公司的术语，即“官僚主义”、“缓慢”的同义词。人们想要逃离这种情况。实际情况是，如果你正在尝试在大规模、高度分散的组织中实施标准化和一致性，那么某些过程是没有办法避免的。重要的是需要认识到，这不仅仅是一个技术问题。与真正困难的问题（改变人类行为）相比，这个相对比较容易。良好的意图固然是好的，但是非可选的过程的一些形式需要加强你想要的结果。也就是说，要使过程尽可能简单、轻巧、尽可能地快速，用以最大程序地减少摩擦，提供最大程度地满足，这真的很重要。

我们开发的基本对接过程是这样的：

这个过程开始于当团队构建一个 APII 提交一份提案，概述他们的计划，包括用例，通常也包含提出的设计方案。

• 对齐：一个中心团队，在和域架构师和产品经理协作过程中，决定名字、命名空间、资源等等。目标是在更大的组合的范围内适应 API，并确保从外部的角度来看它是“有意义的”（更多内容稍后介绍）。
• 评审：团队使用标准格式记录 API，并且跨领域的 API 设计专家提出反馈和意见，关于如何提高可用性、一致性以及如何达到预期的标准。这个过程通常需要经过几个细化周期。
• 评分：针对反映设计标准的一组规范标准，让指定的 API 设计提交者对 API 设计进行打分。
• 验证：API 所有者验证评审和 API 源代码，匹配其底层服务实现。他们使用 API 一致性工具比较请求 / 响应样本，从 CI 任务到缩小 API 版本，然后生成一个评分。

验证完成之后，底层 API 服务实现被部署，并且 API 的生命周期状态被相应地更新。客户现在知道哪个文档版本与他们的集成相关。

这里值得停下来一会，重申整个过程中客户满意度的重要性。这是一个我们开始时可能功亏一篑的领域。我们发现虽然我们在过程设计上做得很好，但是我们准备好规模化经营。我们从根本上低估了基础设施的需求，并且我们有太多的手工步骤。花费了很长时间，没有设置客户期望，每一个问题和每一次延迟都成为这个过程的错误。有太多的投诉，我们需要尽快扭转局势或者让危险危害我们的努力。

解决方案是多元化的，并且包含如下几点：

• 加倍执行自动化：许多步骤需要手动从一个状态移动事物到另一个状态，更新数据、发送通知。通过自动化和自服务方式，我们大大地减少了“猴子的工作”，提高响应速度，并且让客户更加开心。这可不是你能在电子表格里面管理的东西。
• 设定现实的目标：按照定义为开发人员引入新的流程，即新的工作。开发人员需要理解 API 审查是有必要的，需要融入他们的计划并占一定的比例。他们也需要去知道软件开发生命周期内什么时候去做（提示：尽可能早）。广泛的推广和培训有助于建立切合实际的期望和提升满意度。
• 倾听并快速反应：第一次一般不会是正确的，所以和你的客户沟通，通过快速修改让他们知道你很在意。这样可以建立互相的信任，以及下一次他们使用的时候加强他们对过程的参与度。如果他们了解整个想法，开发人员其实希望你能够成功。他们会支持你并保持耐心，但是你应该听从他们的意见并回报他们的信任。

度量

大公司容易被指标所驱动。每一个产品和程序容易被归结为仪表板上的一个或两个度量，或者一个状态。为了成功，你需要仔细考虑评测标准，如何与企业价值有关，以及如何在旅程中设置正确的里程碑。

在向 API 驱动的转型过程中，两个高优先级的商业价值是减少集成成本和增加业务灵活性。将业务能力重构为精心设计和记录的 API 会让集成更容易，内部和外部，与合作伙伴和客户。允许你以不同的创新方式重组功能。这样通过减少冗余投资和扩大可寻址市场方式提升上市时间，提高效率。不幸的是，这两个价值是很难直接达到和度量的。你最可能做的是找到一个间接的度量，通过协商一致，与利益产生联系。

我们达到这个目标的方式是建立一个成熟的模型，它代表一种质量分数，对于如何达到理想化的 API。在这个案例中，“理想化”是一个完全的封装服务，该服务遵循所有 API 的设计标准，并表现良好。我们的想法是，当大多数业务能力通过高成熟度的 API 服务暴露时，将得到最好的业务效益。

使用我们的标准为出发点，我们创建标准，并设置他们的规模从 1 到 5。我们也增加了标准，评测是否 API 适合广泛的商业能力组合，并且通过包含 SLA 合规标准、测试覆盖率等等方式鼓励某些操作属性。通过版本管理的成熟度模型和控制每个标准在刻度上的位置，我们已经能够逐步将 API 组合推向一个更加理想的状态。我们基于失败的最低评分标准评估每一个 API 的成熟度得分。这种方式让我们使用一种简单的成熟度量全面提升 API 组合的质量，让所有服务正常化。

上面这张图是我们积分卡的快照，显示了一个 API 的成熟度评估。每张图代表了一个我们想要强化的标准准则。开发人员使用这些图快速理解哪些标准通过了，哪些失败了。他们互相点击、转入深处研究、做出更正，并且更新分数，直到分数达到它们的成熟度目标。在过去的几年中，我们已经开发了模型和基础设施。我们现在支持成熟度模型的多个并发版本，这使得我们能够随着时间的推移不断改进和完善我们的标准，而不会打破已经存在的 API 的成熟度级别。API 可以升级到新的模型版本作为迭代和发布的新的接口版本。我们现在处于一个相对成熟的状态，为开发人员提供了他们所需要的反馈需求和规模，从而不断提高 API 的质量和一致性。

开发者门户

这一基础设施可能是最重要的。考虑到大型组织的规模，你真的需要一个中心节点去巩固所有的 API、所有的文档、参与的过程，以及整个程序的状态和进展。这最终成为内部开发人员门户，并在组织内部的行动沟通和协调上起关键作用。

当我们刚刚开始时在 PayPal 发生了一个有趣的事。在启用我们的站点之前，我们已经在内部 Wiki 开发了大量的标准和文档。没有人注意。迷失在无组织的和更新文档的大海，会容易发生在任何一个长远目标公司的 Wiki 里。

作为一个实验，我们决定启动一个简单的网站，网站内部大多数静态内容，和已经在 Wiki 上存在的内容有 95% 相似。我们给了它一个内部网络的一级 URL，以及很好的视觉设计。我们花费了 1 周时间构建这个网站。几乎一夜之间，事情发生了改变。高管开始指出这个网站，是“未来的 PayPal”。它出现在演讲文稿里，我们开始生成流量，并且人们开始认真地对待它。我们真正做的是改变了包装，但是观念发生了根本变化。我们认为这会有所不同，但是量级确实震惊了我们。突然间，我们有了新年和继续构建的动力。

这是一个转折点。这也是加强从一个产品的角度考虑程序的重要性的思考，而不是仅仅从技术角度考虑。最后，我们要做的事改变人们的行为。技术改造实际上只是一个副产品。要做到这一点，你需要专注于你的客户，并且从他们的角度思考。这是给我们上了一课，我们改进的网站和程序变得更加以客户为中心，并且更加灵活。这个网站现在是 PayPal 内部访问最多的应用程序。除了其他事情以外，门户网站提供了：

• 所有 API 的目录，包括接口、文档、示例、度量、所有者、反馈机制，以及成熟度评估细节。
• 所有标准文档、版本信息，以及指南。
• 多版本 API 接口的生命周期状态管理。
• 整个开发生命周期中提出并跟踪新的 API 状态的一个约定过程。
• 程序级别报告和仪表板上的成熟度等级和里程碑进展情况。

这笔投资并不是普通的，但它对于实施该计划目标是绝对必要的。

下一篇文章，我们会介绍如何使用基础设施帮助塑造自身的 API 组合。其中一个主要目标是在 API 之间建立清晰的边界。鼓励在可预测和可用方法下分解整体设计。

关于作者

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

查看原文地址： Untangling an API-first Transformation at Scale. Lessons Learnt at PayPal – Part 1

感谢刘志勇对本文的审校。

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