GraphQL 与 REST：完整指南

API 是现代网页和移动应用的支柱。几乎您手机上的每个应用以及您访问的每个网站都使用 API 来获取并与屏幕上显示的数据进行交互。

REST 和 GraphQL 是最常见的两种 API 设计范式。本指南将探讨二者的根本差异、优势以及最佳使用场景，帮助您为自己的项目选择更合适的方法。

等等，什么是 API？
如果您对 API（应用程序编程接口）的概念完全陌生，不妨先学习我们的Streamlined Data Ingestion with Pandas 课程。该课程将教您应用如何利用 API 与其他程序进行通信，反之亦然，而双方无需了解彼此内部工作的细节。您还将熟练掌握应用用来请求与交换信息的规则与协议。

什么是 REST？

REST（表述性状态转移，Representational State Transfer）是一种自 2000 年代初用于开发 Web 服务的架构风格。它通过一组约束与原则来构建可扩展、无状态的 API。REST API（也称 RESTful API）被设计为轻量，并可用于任何支持 HTTP 的语言或平台。

如果您刚接触 REST API，建议先熟悉如何与它们交互，再动手开发自己的 API。这样有助于您体会其工作方式与最佳实践。可以先看看 Intermediate Importing Data in Python 或 Intermediate Importing Data in R。这两门课程都包含关于发起 HTTP 请求、抓取网页等内容的章节。

REST API 的关键概念

我们来理解一下 REST 的核心概念。

无状态

客户端与服务器之间的每次交互都是独立的。服务器不会在请求之间存储与客户端相关的会话数据，这意味着客户端发送给服务器的每个请求都必须包含理解和处理该请求所需的全部信息。

以资源为中心

每一份数据或功能都被视为一种资源，可通过唯一标识符（通常为 URI，统一资源标识符）来识别与操作。

例如，在电商应用中，资源可能包括客户、商品、订单等。每个资源都由唯一的 URI 标识，它就像访问该资源的地址。例如：

/products 可能表示所有商品的集合。
/products/123 可能表示 ID 为 123 的特定商品。

HTTP 方法

RESTful API 通常使用标准 HTTP 方法对资源执行操作：

GET：从服务器检索数据（例如，获取商品列表）。
POST：向服务器提交数据（例如，创建新商品）。
PUT：更新现有资源（例如，修改商品详情）。
DELETE：删除资源（例如，删除某个商品）。

一个标准的 GET 请求看起来如下：

REST 请求与响应示例。图片作者自制。

REST API 还使用标准的 HTTP 状态码来传达错误、成功与其他响应。没错，状态码 418 我是一个茶壶 的确存在！

数据格式

RESTful API 可使用多种格式来表示与交换数据，包括 JSON、XML、HTML、纯文本、YAML 和 CSV。

什么是 GraphQL？

GraphQL 是一种开源的 API 查询语言与运行时，它允许客户端只请求所需的数据，不多也不少。它最初由 Meta（前 Facebook）在 2012 年内部开发，用于优化其移动应用的数据获取，并于 2015 年向公众开源。

GraphQL API 的关键概念

我们来看看 GraphQL 的主要理念。

面向客户端的查询

在 GraphQL 中，客户端通过在查询中指定所需字段来定义响应的结构。也就是说，客户端可以只请求自己需要的特定数据，从而避免过度获取（拿到太多数据）与获取不足（拿到的数据不够）。

在 GraphQL 中，获取用户详情的查询可能如下所示：

GraphQL 请求与响应示例。图片作者自制。

查询与变更

查询用于读取数据，而变更（mutation）用于写入或修改数据。GraphQL 中的变更相当于 REST 中的 POST、PUT 与 DELETE 操作。

单一端点

与可能为不同资源提供多个端点的 REST API 不同，GraphQL API 通常只暴露一个端点。该端点处理所有查询与变更，使客户端与 API 的交互更为简单。

强类型模式

GraphQL API 由模式（schema）定义，它以强类型方式描述可用的数据模型及其相互关系。该模式充当客户端与服务器之间的契约，确保返回的数据与客户端请求相匹配且类型符合预期。

自省能力

GraphQL 模式具备自文档化特性。客户端可以使用自省功能查询模式本身，发现可用的类型、查询、变更与订阅，从而更容易探索与理解 API。

实时数据

GraphQL 通过订阅（subscription）支持实时数据更新。订阅允许当相关数据发生变化时，客户端接收更新，这对聊天应用或信息流等实时场景非常有用。

GraphQL 与 REST 的关键差异

下表总结了 GraphQL 与 REST API 的主要差异。

方面	REST	GraphQL
本质	架构风格	查询语言
数据获取	为不同资源提供多个端点（/products/123、/users/userA 等）	单一端点，查询灵活。
版本管理	通常通过 URL 进行版本化（例如 /api/v1/）。	无需版本化；通过演进模式并保持兼容来管理变更。
数据类型	无严格定义；客户端可能收到不同的数据格式。	强类型模式，明确规定数据结构与类型。
错误处理	使用 HTTP 状态码指示错误。	错误包含在响应体中，同时仍使用 HTTP 状态码。

GraphQL 与 REST 的优缺点

就像生活中的大多数选择一样，每种方案都有其优势与不足。

API 类型	优点	缺点
REST	- 上手容易：对有 Web 经验的开发者很熟悉。 - 工具有成熟生态：文档丰富，安全实践完善（OAuth、API 密钥）。	- 过度/不足获取：可能导致数据检索低效。 - 版本管理：需要维护多个 API 版本。 - 无原生实时更新：需要借助 WebSocket 等额外技术。
GraphQL	- 高效数据获取：单次请求仅取所需数据。 - 自文档化：模式可作为始终更新的文档。 - 实时更新：支持订阅实现即时同步。	- 学习曲线陡峭：较为复杂。 - 缓存复杂：标准 HTTP 缓存效果不佳，需要自定义策略。 - 安全风险：查询灵活度高，可能导致意外数据暴露。

如何在 GraphQL 与 REST 之间做选择

在 REST 与 GraphQL 之间的选择完全取决于项目需求。您或许已从上一节得出直觉，但经验法则是：当满足以下情况时，优先使用 REST：

数据模型简单
应用需要大量缓存
团队熟悉 REST 约定
需要可预测、标准化的响应

而当您需要应对以下情况时，使用 GraphQL：

具有嵌套关系的复杂数据模型
需要灵活、动态查询的应用
快速迭代并减少后端改动
实时更新

REST 和 GraphQL 也可以在混合方案中共存，让您的项目既能受益于简单、定义清晰的 REST 端点，又能在复杂数据检索方面享受 GraphQL 的灵活性。比如，在电商应用中，您可以用 REST 处理认证和用户注册，以利用 OAuth 等标准安全实践；而用 GraphQL 拉取更为嵌套和复杂的信息，如商品详情、分类与用户评价。

结论

总之，GraphQL 与 REST 各有长处与短板，适用于不同情境。二者的选择应由项目需求与数据复杂度来决定。

话说回来，这两种工具都很有趣，也能教会您许多关于数据的知识。如果有机会，强烈建议您都去尝试一下！

如果读到这里，您已经知道要用哪种工具，那么恭喜迈入下一步！前往我们的博文 Mastering API Design: Essential Strategies for Developing High-Performance APIs，学习如何设计您自己的 API。

作者

Marie Fayard

我是一名具有产品思维的技术负责人，专注于帮助早期初创公司从首个原型成长到实现产品与市场匹配，并持续向前发展。我对人们如何使用技术充满好奇，热爱与创始人及跨职能团队紧密合作，将大胆的想法变为现实。不在打造产品的时候，我会在世界的新角落寻找灵感，或在瑜伽馆放松减压。

常见问题

我可以轻松地在 REST 与 GraphQL 之间迁移吗？

很遗憾，这个问题没有简单答案。它确实取决于您项目的具体需求，可能很直接，也可能非常复杂。从 REST 迁移到 GraphQL：您需要设计 GraphQL 模式，将 REST 端点转换为 GraphQL 查询与变更，并调整后端逻辑。从 GraphQL 迁移到 REST： 这需要创建多个 REST 端点，调整数据获取方式，并实施版本管理与缓存策略。

在使用 GraphQL 与 REST 时，有哪些工具与库可用？

对于 REST，有众多成熟的库与框架，例如 Express.js、Django REST framework、Flask-RESTful 和 Spring Boot。它们为构建与使用 RESTful API 提供了广泛支持。对于 GraphQL，常用的库与工具包括 Apollo Server、GraphQL.js、Relay 以及（Python 的）Graphene。这些库用于模式定义、查询执行以及客户端与服务器的通信。

除了 REST 和 GraphQL，还有其他 API 设计范式吗？

是的，除 REST 与 GraphQL 外，还有其他 API 设计范式，包括 SOAP（简单对象访问协议）和 gRPC（gRPC 远程过程调用）。SOAP 是一种使用 XML 进行消息格式化并高度依赖 Web 服务标准的协议，适用于对安全性与事务可靠性要求很高的企业级应用。gRPC（由 Google 开发）使用 HTTP/2 作为传输层、Protocol Buffers 作为序列化格式，并通过多路复用、双向流和内置代码生成等功能提供性能优势。

REST 和 GraphQL 能在同一应用中一起使用吗？

可以，REST 与 GraphQL 可以在同一应用中以混合方式使用。比如，REST 可以处理更简单、定义清晰的端点，如认证与用户注册，并采用成熟的安全实践；GraphQL 则可负责更复杂的数据检索任务，如获取嵌套或关联信息。

GraphQL 的实时数据更新通常用于哪些场景？

GraphQL 的实时数据更新特别适用于需要即时同步的应用，例如聊天应用、体育赛事比分直播、股市行情推送、协作文档编辑，以及任何需要将实时数据变动立即推送给客户端的场景。

主题

数据工程 Python

主题

技术