GraphQL 是 REST API 的一种非常流行的替代方案，目前正在席卷开发人员的世界！去年，PayPal 将 GraphQL 引入了技术堆栈，彻底改变了开发人员思考数据、获取数据和构建应用程序的方式。本文作者在一年前曾写过一篇 GraphQL 最佳实践的文章，当时受到了广大读者的欢迎。这篇文章同样也是一篇精彩的总结，可以当作公司部署 GraphQL 的指南。

图源：graphql.org

我们在PayPal构建GraphQL API时获得了一系列最佳实践和观察总结，这篇文章就是其中之一。

一年前，我们写了一篇《GraphQL：PayPal Checkout的成功案例》，内容涵盖了我们从REST到Batch REST再到GraphQL的发展历程。自那时以来很多事情都改变了！这篇文章涵盖了我们在PayPal扩展GraphQL时学到的所有知识，并可作为你在公司部署GraphQL的指南。

一年前，使用GraphQL的产品很少。虽然我们在PayPal Checkout上取得了成功，但那时还没有相关的基础架构、工具、培训或支持。尽管存在这些缺陷，但GraphQL的发展仍像火箭一般一飞冲天。在撰写本文时，我们已经有50多个不同的产品在使用GraphQL！

在短短2年内，PayPal使用GraphQL的产品从3种增加到52种。

这项新技术的应用速度很快，我们仍在努力跟上步伐。与其他技术变革一样，企业级扩展的重点并不在于水平扩展，或为服务器/云计算投入大量资金。扩展人员、工具链和流程是最具挑战性的。

了解自己

在部署GraphQL之前，重要的是要深入了解你所在的公司，理解你们的身份，你们在做些什么，以及你们的长处与不足。

在PayPal，我们的产品使用JavaScript构建。前端采用React，后端则是Node.js。技术栈中还有数百个Java REST服务和一些C++ SOAP之类的服务。

PayPal是最早使用Node的公司之一，并通过NodeDay之类的活动，以及与The Node Firm和NodeSource的合作，在业界打响了Node的品牌。

2014年，PayPal的首个NodeDay。

2013–2015年，PayPal迁移到了Node。Node改变了整个公司，改善了我们制造和运输产品的方式。过去，一项简单的内容更改需要数周时间才能部署为单个单体C++应用。如今，开发人员只需要几分钟时间就可以实验、迭代和推出新的产品功能。

https://vimeo.com/82577994

这不是一夜之间发生的转变，也不是偶然的结果。在Node融入PayPal之前，Bill Scott提出了使用LeanUX构建产品的愿景，其中迭代和学习是核心要素。在LeanUX中，UI数据是实验性、一次性的。如果实验效果不佳，那就不断迭代！Node.js是其成功的关键所在。

Kraken.js

2014年，我们推出了Kraken，这是Express上的一组库，旨在通过可配置的中间件、默认安全设置、一个dust.js渲染器和内容本地化来为你的应用“提供一些帮助”。自那以来，Kraken的大部分武器都消失了。我们仍使用可配置的中间件和默认安全设置，但与Web应用程序相关的所有内容自2014年以来发生了很多变化。现在，团队正在构建客户端React应用，应用程序是部署到CDN的静态文件包，而不是在服务器集群中运行的代码。

对于API而言，我们使用BFF Schema。尽管它们都是专用的，并且允许开发人员迭代，但是它们紧密耦合在一起，并且不能很好地复用。结果是我们有很多团队在反复迭代和构建相同的事物！构建BFF API也不是一件容易的事。它们往往包含许多编排逻辑，其中你需要从5、10、15个不同的服务中获取数据，规范化这些响应，丢弃其中95％的响应，然后将数据映射、过滤、分类为所需的样子🙄。编写这样的代码并不能充分提升开发人员的效率。这种紧密的耦合和缺乏复用对我们来说是一个问题。

GraphQL可以提供帮助吗？答案是肯定的！

在上一篇文章中，我们记录了从REST到Batch REST再到GraphQL的旅程。我们发现它做到了两全其美——开发人员可以快速迭代，API和UI松散耦合，并且代码复用也增加了。

推荐你的公司进行类似的练习。在跳上GraphQL这趟高速列车之前，花些时间了解你的过去，回顾自己的发展历程，评估自己的优缺点，并考察GraphQL可能带来的帮助。

重设期望

开发人员经验>性能

在查阅生产就绪的项目清单之前，我们应该重新设定期望值。当你初次接触GraphQL时，能想到的好处往往是：通过网络传输的数据变少了，从而可以实现更快、性能更强的应用。

大型公司会将GraphQL置于现有的REST服务之上。结果是，你的GraphQL查询速度将受限于最慢的REST服务。GraphQL允许你在一次往返中获取所需的一切。如果客户端和服务器之间存在空闲，则可以减少往返并降低延迟。但这并不是所有情况下都能做到的。一段时间后，你将意识到开发人员经验和灵活性的好处远比性能更重要。

GraphQL对人类很友好❤

GraphQL对人类很友好。使用GraphQL时，开发人员考虑的是字段，而不是端点、域或复杂的连接。开发人员可以遍历数据图（graph）来选出用户的名字、60x60的个人资料照片、主要送货地址和信用卡信息，而不必调用6-10种不同的服务。新员工都喜欢它。如果你知道JSON是什么样子，那么只要去掉双引号和逗号就能查询GraphQL API了。你的UI开发人员喜欢它，因为它以产品为中心，具有声明性，并有丰富的工具集支持，可以减少集成摩擦并提高信心。

当你将GraphQL推荐给公司的领导者和团队时，请重点谈论开发人员经验、生产力和灵活性。否则你可能会让他们失望。

位于技术栈边缘的GraphQL

在PayPal，我们的核心服务由独立的后端团队开发，产品团队则构建BFF API，以从这些基础核心服务中编排数据。最初，我们认为“GraphQL应该无处不在”！我们认为过度获取和获取不足的问题将会消失，你可以知道哪些用例使用哪些字段，并能一直追溯回数据库。架构师喜欢这个想法。但我们无法让整个公司停止将开发流程迁移到GraphQL上。

经过大量的实验和反思，我们发现GraphQL在我们技术栈的边缘最能发光发热。GraphQL以产品为中心，应该受到产品团队的影响（或经他们开发）。GraphQL Schema应该由产品团队先设计再开发。它们不应该由后端开发人员孤立地设计。GraphQL可以很好地处理编排工作。因此GraphQL最适合你的技术栈边缘位置，并且可以与REST协同工作。

我们的朋友（也是前PayPal员工）Trevor Livingston在Expedia使用GraphQL时也有类似的观察结果。

GraphQL的收益会随着你在技术栈中的应用深度增加而递减。我不认为它是微服务的通解。它的甜点在API的边缘表层领域。

在你的公司中引入GraphQL

好了，是时候实现这一目标了！这部分内容是你的公司引入GraphQL时要做的准备工作清单。

首先，你需要为产品团队奠定一个基础。GraphQL这项技术新奇且令人兴奋，有许多开放式问题和见解。几乎没有什么是一成不变的。你有很多选择！

你的API开发人员和消费者是什么样的？
谁负责主要工作？他们了解哪些语言？
他们现在是如何构建API的？它们是专用的还是通用的？
你要使用现有的框架和工具吗？具体是哪些？
你需要添加公司专属的内容吗？比如身份验证、授权、复查、断路器、自定义HTTP状态代码和错误处理？
你将如何执行标准？
你将如何处理错误？

奠定基础

在PayPal，为BFF API和UI做出贡献的产品团队已经让GraphQL流行了。我们为GraphQL API使用Node.js。与其他许多公司一样，我们使用Apollo的开源库和工具。Apollo有专门的团队来构建和维护这些工具，因此它们在文档编制方面是一流的。我们使用apollo-server，并分散应用在了PayPal专属的的生产就绪环境中，如日志记录和检测、身份验证、错误处理和速率限制等用途。

如果你有任何独特的要求，请创建可与开源库（如Apollo）共用的模块和插件。不要创建深层抽象或向开发人员隐藏复杂性。要保持简单，什么问题都能靠谷歌查询出来！

请记住，GraphQL仍然是一个API。你要确保有足够的日志记录、复查、断路器模式、速率限制和查询复杂性检查。

扩展知识

确保架构师和API设计人员都了解GraphQL，以帮助你扩展设计审查流程并执行标准。他们很可能已经用了很多年来设计REST API。GraphQL是不同的。起初你可能会遇到阻力，但要克服它。你需要花时间与他们一起找出差异，并让他们挑战自我，换一种API设计方式：

没有版本控制，使用数据图来代替ID以创建关系，没有HATEOAS链接。当架构师也了解这一技术后，这会给GraphQL的推广带来支持。

接下来要思考，如何在公司内推广GraphQL的学习？GraphQL正在快速变化。你创建的任何培训材料都将过时并需要维护成本。所以请依靠外部资源，并向Moon Moon这样的培训公司寻求帮助，获取优秀的GraphQL课程！

制定标准

架构师入门之后，你需要设定一些设计标准，创建一份文档并在所有地方都引用它，使用诸如graphql-schema-linter之类的工具来强制命名约定。

例如：

所有字段都必须有描述或注释；
类型名称，LikeThis。字段名称，likeThis。枚举值，LIKE_THIS；
尽可能使用枚举；
弃用的字段必须有原因；
没有集合或列表后缀（如：使用cards，而不是cardList）；
优先使用具有突变的输入类型。

然后你需要针对分页做出选择。在你的Schema中显示列表的首选方式是什么？基于游标的分页（Cursor-based pagination）吗？

你将如何发现错误？在撰写本文时，GraphQL的错误处理还不成体系，有很多选项可供选择：

使用默认errors数组；
使用自定义属性扩展errors；
Schema中的errors字段；
Union类型。

在PayPal，我们使用自定义属性扩展errors。它仍然符合规范，并允许我们在需要时向errors添加错误分类和其他元数据，这些我们很喜欢。我们认为其他选项是不可行的，会导致错误被忽略。

身份认证/授权

你将如何保护自己的Schema？

首先，我们保护了整个Schema，然后意识到我们拥有许多不同权限、不同类型的用户。然后我们创建了一个高阶auth函数，可以用来包装一个解析器。最后，我们意识到创建自定义auth指令是保护Schema的最佳方法。

Custom @auth directive

在上面的示例中，如果一个查询包含user字段，则必须登录该user，并且creditCards需要额外两项权限。因为这是一条指令，所以它在Schema中可见，而不是深埋在代码中。API设计人员和架构师可能不太了解JavaScript，但也可以在审查时提供帮助。

通过出色的工具链释放潜能

以前我们写过《GraphQL：检测API并释放潜能》，解释了GraphQL与REST相比有何独特优势：你可以更好地了解API的使用方式，并在客户集成你的API的过程中为他们带来额外的信心，同时避免重大更改的影响。

首先，你可以将延迟、错误和使用情况数据通过管道传输到公司的制图工具。下面是一个Grafana仪表板示例：

每解析器/字段的延迟示例

来自Marc-Andre Giroux的讨论

因为你知道哪些客户请求哪些字段，所以你可以在弃用某些字段时主动通知他们。在PayPal，我们发现产品团队变得积极主动，小规模交付更改后，更有可能提升迁移速度。大型程序和具有复杂计划流程的大型迁移可能会令人望而生畏，并破坏开发人员的工作流程。

我们推荐的其他工具包括：

graphql-playground，用于测试开发模式下的查询；
https://github.com/prisma-labs/graphql-playground

graphql-schema-linter，用于强制执行Schema命名约定；
https://github.com/cjoudrey/graphql-schema-linter

eslint-plugin-graphql，用于linting客户端查询；
https://github.com/apollographql/eslint-plugin-graphql

graphql-doctor，用于PR状态检查。
https://github.com/cap-collectif/graphql-doctor

购买与构建

在PayPal，我们最近开始使用Apollo Platform，产品团队的反馈非常好！Apollo Graph Manager提供的仪器工具可显示字段级别的深刻见解，提升对重大更改的信心，提供查询白名单，并为每个字段提供linting和内联SLA计时来简化客户集成工作。

https://www.apollographql.com/platform/

Apollo Graph Manager不是免费的。我们可以自己构建这种工具吗？也许可以，但不会那么完美。我们没有GraphQL基础架构团队。我们并不想等待12-18个月来构建同级别的事物，还要花精力维护它。我们现在就想兑现GraphQL的承诺！对比购买与构建的路线，购买Apollo Platform的决策明显胜出。我们建议你也考虑一下。

投资GraphQL

如果你的公司正在使用GraphQL，则应该参与GraphQL的发展，并为其进行投资。与其他公司建立联系，分享经验并将学习成果带回你的公司，这一点很重要。你应该加入GraphQL基金会，该基金会包括PayPal、Facebook、Twitter、AWS、Intuit和New York Times等公司成员。加入GraphQL贡献者日之类的小组或当地聚会，或加入GraphQL工作组，还可以提交规范提案。

https://foundation.graphql.org/

第一次GraphQL贡献者日

在企业中扩展GraphQL面临的挑战

GraphQL是很出色的工具，但我们要解决一些关于数据图的组装以及如何衡量成功的问题，才能充分享用它的好处。

许多仓库

在2012年之前，PayPal用的是C++单体仓库。从那时起，我们在许多领域和产品团队中产生了数千个GitHub仓库，构成了许多服务和应用程序层。对于使用单体仓库的Facebook和GitHub这样的公司来说，共享并不是什么大问题。

GraphQL在许多仓库中都很难用。如果没有诸如存根远程类型之类的自定义技巧，就无法引用或链接本地文件系统中不存在的远程类型。开发人员很难发现或复用其他服务中定义的类型。

数据图的组装

用户希望看到一个可以遍历的单一内聚图，而无需操心许多服务，无需动用许多服务来获取所需的数据。实际上，组装单个图是很困难的。

一种解决方案是Schema拼接，其中网关消费底层GraphQL API的Schema向开发人员显示单个Schema，还会将传入的查询委派给底层API。Marc-Andre Giroux写了一篇出色的文章介绍了Schema拼接遇到的挑战。通过Schema拼接，网关就有了粘合代码，负责维护类型之间的关系，并确保子查询正确执行。当网关所有者不知道这些类型之间的关系，并且产品团队无法控制这一基础架构时，粘合代码就会出现问题。

Apollo Platform的解决方案是一种联盟开发范式，使用自定义指令以声明方式将类型链接在一起。它消除了网关中对粘合代码的需求，合理地分离了关注点，并允许你扩展在本地开发中没有的类型。我们可以期待一下，看看业界是否会采用它，以及联盟将如何影响GraphQL规范。

如果构建单一数据图是不可行的话该怎么办？在Paypal，我们为快速迭代和持续学习进行了优化。许多开发人员认为，自己没有必要放慢脚步，与其他成员达成共识并融入更大的集体。这是我们文化的双刃剑。如果单张图是做不到的，我们还可以怎样复用工作成果呢？另一个选项是GraphQL Modules和graphql-component之类的本地模块。使用本地模块，你可以选择所需的类型和字段，所有代码都在同一进程中运行，于是Schema拼接和联盟遇到的许多问题就能解决了。但是，我们有许多相似的端点，并且服务器占用并未减少。你可以接受吗？

这是我们使用GraphQL时遇到的最困难的问题。

衡量成功

如前所述，GraphQL最亮眼的好处是开发人员经验、生产力和灵活性。有时，性能方面可能会有一些收益，但这并不是你可以兑现的承诺。

如何衡量开发人员的经验？如何做到客观而不是胡乱分析一通？如何衡量开发人员的生产力？比较使用GraphQL的项目与其他项目的完成时间呢？

这仍然是我们面临的一个挑战。我们与开发人员交流，他们告诉我们工作轻松了许多，但是我们如何量化这一点呢？

喜欢这些挑战吗？

我们中有人会在本月的GraphQL峰会上发言。我们很乐意分享有关GraphQL的想法和讨论！😊

原文链接：
https://medium.com/paypal-engineering/scaling-graphql-at-paypal-b5b5ac098810

创作场景

PayPal：如何在你的公司扩展 GraphQL？