GraphQL API：概述与应用场景 | Cellenza博客

由于现代信息系统的不断发展、API化项目的推进以及现代集成架构的实施，企业对稀疏数据管理的需求日益增长。这些数据可能分布在不同的存储位置，但需要快速且便捷地进行汇总和查看。

面对这些需求，传统的 GraphQL API** 提供了一种全新的 API 设计方法，成为解决这些问题的潜在方案。特别是，微软的 API 管理工具现已支持添加和管理 GraphQL API。

本文旨在为您概述这种“新型”API的特点。我们将从 GraphQL API 的定义 开始，接着探讨使用 GraphQL API 替代 REST API 的 优劣势，最后通过一个 实际案例 展示其应用场景，并分享对 API 集成的相关见解。

什么是 GraphQL API？

需要明确的是，Microsoft Graph API 是一个基于 REST 的 Web API，它通过单一端点（https://graph.microsoft.com）以及 Azure Active Directory 的共享身份验证进行操作，这超出了本文讨论范围。

GraphQL 是一种开源的数据查询和操作语言，由 Facebook 和 Lee Byron 于 2012 年创建。它允许客户端指定所需的数据结构以及返回的属性（即便数据是分布式存储的）。服务器会根据该结构生成并返回响应。这种强类型的方法旨在解决 REST API 返回数据不足或冗余的问题。

2015 年，Facebook 将 GraphQL 开源。2019 年，GraphQL Foundation 成立，成员包括 AWS、微软和 Twitter 等公司，以推动 GraphQL 的发展。为了简化 GraphQL 服务的创建和管理，微软计划在 2021 年 11 月将其支持集成到 Azure API 管理中。

GraphQL 的核心概念包括：

客户端定义需求，服务器按相同结构响应（即“请求所需，精确返回”）。
强类型 API，避免数据不足或冗余问题。
单一查询即可跨多个资源获取数据。

GraphQL API 模型概述及与其他 API 的差异

GraphQL API 的设计初衷是解决 REST API 的灵活性不足问题。通过实体图建模，GraphQL 能够在不增加查询数量的情况下满足多样化需求。

GraphQL API 架构示例

端点/URL

GraphQL API 仅需一个端点，例如：myApi/GraphQL。客户端可以通过该端点查询实体。

GraphQL API 端点示例

GraphQL 的灵活性

GraphQL 提供了比 REST API 更高的灵活性，允许用户选择需要查询的内容。为了实现这一点，实体图和可能的查询必须在系统中记录。

以下是一个简单的实体图示例，仅包含两种实体类型：

GraphQL 实体示例

GraphQL 查询类型

GraphQL 支持两种查询类型：

突变（Mutation）：用于更改数据状态，例如修改或新增数据。
查询（Query）：用于检索数据，不会对数据进行任何更改。

使用 GraphQL 的 HTTP GET 和 POST 请求

GraphQL 支持 GET 和 POST 请求：

如果请求中包含查询参数，则视为 GET 请求，例如：
```
myApi/graphql?query=myquery
```
如果请求的 Content-Type 为 application/GraphQL，则视为 POST 请求。

GraphQL API 的响应始终以 JSON 格式返回，包括：

data：包含所有请求的数据。
errors：列出查询返回的所有错误。

GraphQL 的局限性与解决方案

尽管 GraphQL 提供了诸多优势，但也存在一些局限性：

NULL 值处理：GraphQL 将 NULL 视为 undefined，这可能导致无法正确处理值的重新初始化。
文件管理：GraphQL 不支持文件上传或下载。
性能控制缺失：由于属性一旦暴露即可被查询，可能导致请求规模失控。因此，在对外开放此类 API 时需格外谨慎。

GraphQL 与 REST API 的共存

为克服上述局限性，可以在同一 API 中同时使用 GraphQL 和 REST 端点。例如，文件管理可以交由 REST 端点处理。

GraphQL API 的实际应用示例

以下通过一个简单的 GraphQL API 示例，展示其核心概念。假设我们有两个实体：Book 和 Author，它们通过一对多关系关联（一个作者对应 0 到 n 本书）。

GraphQL 示例架构

示例场景

场景 1：仅获取作者的姓名

如果客户端应用只需要显示作者的名字和姓氏，而不需要技术标识符或关联的书籍信息，可以使用以下查询：

GraphQL 查询示例 1

响应结果：

GraphQL 响应示例 1

场景 2：获取作者姓名及其书籍标题

如果需要获取作者的姓名及其书籍标题，可以使用以下查询：

GraphQL 查询示例 2

响应结果：

GraphQL 响应示例 2

相比之下，若使用 REST API 实现相同的精确度，则需要多个端点来处理不同的对象，导致请求数量增加且数据冗余。

对 GraphQL API 的思考与建议

GraphQL API 为 API 设计带来了全新的思路。它并非完全取代 REST API，而是作为补充。根据 API 的复杂性和需求，可以选择单一方法或结合两者的架构。

在需要暴露复杂但丰富的对象模型时，GraphQL 是一个值得考虑的选项。它允许客户端选择所需的数据及其格式，从而提高效率。

此外，在现代集成平台中，GraphQL API 可用于暴露“超级模型”（由多个简单对象聚合而成的对象模型），或通过 GraphQL 覆盖层简化 API 的使用。

进一步阅读

如果您对 GraphQL 感兴趣，可以访问 GraphQL Foundation 的学习资源：https://graphql.org/learn/

原文链接: https://blog.cellenza.com/en/cloud/graphql-api-an-overview-and-use-cases/