什么是GraphQL？模式、查询和API执行
无抓取抓取API提供任务特定接口，返回应用程序工作流的结构化公共网络数据。
简而言之
- GraphQL是一种用于API的查询语言和执行系统。 客户端根据类型模式选择字段，服务解析该选择。
- 模式是共享的合同。 它定义对象类型、字段、参数、关系、入口点和可空性。
- 一个端点并不意味着一个数据源。 解析器可以读取数据库、服务、缓存或图后面的现有API。
- 客户端定制的响应减少了一些多余拉取。 它们还需要对查询深度、广度、成本、授权和解析器效率进行控制。
- GraphQL和REST可以共存。 许多系统在其操作和客户端特征最适合的地方使用各自。
GraphQL定义
GraphQL是一种开放的查询语言和执行模型，用于描述和满足客户端与服务器之间的数据需求。服务发布一个类型化模式。客户端提交一个操作，该操作命名该模式中的字段，响应反映请求的选择。GraphQL不是数据库、存储引擎或传输要求；它可以位于现有的应用程序代码和数据源之上。
官方的 GraphQL规范 定义语言、类型系统、验证和执行行为。当模式支持时，顶级操作类型是查询、变更和订阅。查询读取数据，变更请求更改，订阅表示后续结果的流。服务决定哪些字段和操作存在。
GraphQL请求如何执行
将什么是GraphQL视为一系列定义的操作，而不是一个单一的黑箱。该序列揭示了每个输入、输出和失败由哪个组件拥有。
解析和验证
服务器解析文档，选择请求的操作，应用变量值，并验证字段名称、参数、类型和选择规则与模式的匹配。无效操作在字段执行之前失败。这给客户端提供了精确的反馈，并防止在发布图之外任意访问字段。
解析字段
执行从根字段开始，并通过选择树继续。解析函数从应用代码、数据库、服务、缓存或父对象中获取值。执行引擎可以并行解析独立字段，同时保留规范定义的变更顺序规则。
组装数据和错误
当执行产生结果时，响应包含数据条目，并可能包含错误条目。字段错误可以与部分数据共存，受可空性传播的影响。客户端必须故意处理这种形状，而不是将每个响应视为完全成功或完全失败。
GraphQL模式的构建块
以下概念确定什么是GraphQL在实际系统中的行为。分别阅读可以防止格式选择被误认为是架构或安全保证。
| 概念 | 含义 | 实际信号 |
|---|---|---|
| 对象和字段 | 描述实体和可选择值。 | 具有名称、价格和卖方字段的产品类型。 |
| 标量和枚举 | 表示叶值。 | 字符串、数字、布尔值、标识符、日期通过自定义标量或固定选择。 |
| 参数和变量 | 对字段选择进行参数化。 | 过滤、标识符、分页边界和操作输入。 |
| 接口和联合 | 表达抽象或替代结果类型。 | 由多个具体对象类型实现的可搜索节点。 |
| 指令 | 在定义的位置增加声明性行为。 | 条件包含、弃用或特定实现的模式行为。 |
GraphQL复杂性的来源
什么是 GraphQL 仅通过具体操作影响产品行为。以下案例展示了哪些能力重要，以及为什么相邻的方法可能表现不同。
复合接口
一个屏幕可以在一个声明的选择中请求多个相关对象形状，而不是协调许多特定于客户端的调用。
多个客户端产品
网络、移动、合作伙伴和内部客户端可以在共享一个类型化域图的同时选择不同的字段。
以模式为中心的工具
类型信息支持验证、文档浏览器、编辑器完成功能、代码生成和更改分析。
后端聚合
解析器可以在一个图后组合现有服务，该图以客户端导向的术语呈现关系。
GraphQL API 的生产关注点
围绕稳定的域概念建模架构，而不是当前的数据库表或一个屏幕。可空性是一个兼容性决策：将可空字段更改为非空可能会在解析器无法生成值时破坏客户端。分页应使用文档化的连接或续接模型，该模型在记录更改时保持稳定。
在执行之前控制查询工作。深度本身并不是完整的成本模型，因为一个浅字段可能返回大量集合，而一个深路径可能很便宜。适当使用有界分页、字段级成本或复杂性规则、操作白名单、执行时间限制，以及将工作归因于操作和调用者的可观察性。
防止解析器放大。一个字段解析器为每个父对象发出一个下游查询，可能会将紧凑的客户端查询变成许多后端调用。批量和缓存请求中的读取，在语义允许的情况下，仪器化解析器计时，并在字段和对象边界评估授权。官方 GraphQL 安全指南 涵盖可信文件、需求控制、分页和模式保护。
GraphQL 误解和失败模式
- 假设一个请求意味着低后端成本。 一个紧凑的文档可以触发昂贵的解析器树和大规模分发。
- 直接暴露存储模型。 数据库形状的模式将客户端与实现细节绑定在一起，使得域的演变更加困难。
- 仅将 HTTP 状态视为结果。 执行错误可能出现在部分数据旁边，因此客户端需要 GraphQL-aware 的处理。
- 跳过操作可观察性。 一个单一的端点隐藏了工作负载差异，除非度量指标识别操作名称、字段、调用者和成本。
- 将内省用作授权模型。 模式可发现性和访问字段的权限是不同的控制。
GraphQL 在数据和自动化工作流中
一个 GraphQL 收集器应该从服务许可的模式发现和文档化操作开始。它应该发送命名操作，使用变量而不是构造带有不可信值的文本，仅请求所需的字段，并遵循服务的分页模型。持久化稳定标识符，并明确处理部分数据。
架构更改应受到自动化审查。附加字段通常是安全的，因为客户端明确选择字段，但删除字段、缩小类型、改变可空性或改变参数行为可能会破坏消费者。在删除之前跟踪已弃用字段的使用，并对候选模式测试存储的操作。
GraphQL 可能位于网络获取管道的下游。公共页面数据可以由专用层收集和规范化，然后通过类型化图暴露给内部客户端。该图应描述规范化域及其来源，而不是泄漏选择器、页面布局或浏览器会话详情。
什么是 GraphQL 审查清单
使用这些检查将“什么是 GraphQL”的定义转化为开发人员、运营商或审阅者可以重现的实施证据。
- 重述边界。 对于“什么是 GraphQL”，识别调用者、提供者、路径以及标志完整结果的确切事件。
- 验证中心声明。 用实施及其文档确认此声明：GraphQL 是一门查询语言和 API 的执行系统。客户端根据一个类型化架构选择字段，而服务解析该选择。
- 追踪机制。 观察解析和验证，解析字段，组装数据和错误，并记录每个阶段的组件所有者。
- 检查最近的区别。 记录为什么在这个系统中，Object 和 field 意味着“描述实体和可选择的值”。
- 测试一个代表性的用例。 使用与真实数据、位置、数量和权限边界相符的复合接口。
- 防范已知错误。 审查“假设一个请求意味着低后端成本。”并添加一个捕获它的验收检查。
- 限制工作负载。 为 What Is GraphQL 设定适当的主题限制，包括有效负载、并发、执行时间和适用的存储输出。
- 记录决策。 解释为什么 What Is GraphQL 符合这个边界，并列出可以证明后续不同方法的证据。
结论
What Is GraphQL 应该描述设计中的可测试部分，而不是作为相邻行为的松散标签。审查应保留这一核心决策：GraphQL 是一个用于 API 的查询语言和执行系统。客户根据类型架构选择字段，服务解析该选择。同时应防止假设一个请求意味着低后端成本，并保持 What Is GraphQL 的访问在接口或网络的文档政策范围内。
准备构建您的网络数据工作流了吗？
将一个可测量的 What Is GraphQL 获取或集成步骤与上述的验证和存储实践相连接。
今天注册并获得 $5 的免费信用 — 无需信用卡.
领取您的 $5 信用 →常见问题
GraphQL 是数据库吗？
不。GraphQL 是一个用于 API 的查询语言和执行系统。解析器可以从数据库、服务、缓存、文件或其他 API 获取值，但 GraphQL 并不规定存储引擎。
GraphQL 是否总是使用一个端点？
GraphQL 服务通常在一个 HTTP 端点接受操作，但规范并不要求单一的 URL 或 HTTP 本身。定义合同是架构和执行语义。
GraphQL 仅用于读取吗？
不。GraphQL 定义了用于读取的查询操作、用于请求更改的变更操作，以及当服务支持时用于流的订阅操作。架构确定可用字段。
GraphQL 是否取代 REST？
不。GraphQL 和 REST 以不同的方式解决接口设计。GraphQL 适用于类型客户端选择的图，而 REST 适合资源导向的 HTTP 交互和缓存语义。一个系统可以同时暴露两者。