什么是 GraphQL?

Scrapeless Agent Browser 可以运行一个浏览器页面，该页面通过 GraphQL 请求加载数据，作为授权网络工作流的一部分。

GraphQL 是一种查询语言和执行模型，针对建立在类型化模式上的 API。客户端请求命名字段，服务器将这些字段解析为像选择那样的结果。这与每个 URL 返回一个固定表示的接口不同。这一区别在应用程序需要在不同屏幕上以不同细节层次获取相关数据时非常有用。

GraphQL 并没有指定基础数据存在哪儿，也不会仅仅因为有一个 schema 就使请求安全。服务仍然需要解析器、认证、授权、操作限制和传输协议。本指南跟踪从 schema 到结果的一个请求，然后检查 GraphQL 在集成中是如何提供帮助或增加复杂性的。

模式是API合同

GraphQL 模式定义了类型、字段、参数和操作入口点。字段可以根据类型系统返回一个标量、一个对象、一个列表或一个可为空的值。 官方架构指南 解释这些声明如何定义客户可以请求的内容。客户不能仅仅因为可以在查询中写入字段名就随意请求任意数据库列。

该模式使关系可见。一个项目类型可能会公开一个标题和一个卖方字段，而卖方类型则公开一个显示名称。如果模式允许，客户端可以在一个操作中选择标题和嵌套的卖方名称。服务器决定如何获取这些值。这个决定可能涉及数据库、另一个服务或缓存结果。

可空性是合同的一部分。它描述了字段是否可以在有效响应中缺失，而不是潜在来源失败的原因。客户端应该生成并针对架构进行测试，但他们仍然必须处理应用程序错误和数据质量。非空声明无法让不可靠的上游来源神奇地变得完整。

GraphQL 查询如何获得其形状

查询操作从查询根开始，并选择字段直到标量叶子。 官方查询指南 显示客户端确切指定它希望从特定模式中获取的字段。参数可以过滤或识别数据，变量允许客户端将值与查询文本分开提供。响应数据反映所选字段结构。

此选择可以减少仅需要摘要的屏幕的不必要字段。它还可以结合相关字段，这些字段在其他情况下将需要多个资源请求。两种结果都不是自动的。服务器可能仍会对嵌套字段执行昂贵的工作，而客户端可能请求的内容远超过屏幕所需。字段选择提供了灵活性，但需要成本控制。

一个有用的心理模型是一个有明确选择的餐厅菜单，但结果比类比要严格：名称和类型在执行之前会根据模式进行验证。拼写错误的字段会产生验证错误，而不是一个空属性。这个早期检查帮助开发者在解释混淆的部分结果之前发现合同不匹配。

变异、订阅和传输

查询读取数据。变更表示可能更改服务器端状态的操作，而订阅表示在服务支持时接收更新的一种方式。这些是GraphQL操作类别，而不是对特定部署的保证。 GraphQL 操作参考 描述它们的语法和选择行为。

许多 GraphQL 服务使用 HTTP 进行查询和变更，但 GraphQL 语言与 HTTP 是不同的。请求可以携带文档、变量和操作名称；服务决定如何公开该交换。订阅需要支持的流传输和生命周期。不要仅仅因为 GraphQL 语言定义了订阅，就假设服务器支持订阅。

GraphQL 响应可以包含数据和错误。当某些字段解析成功而其他字段失败时，部分数据是可能的。 官方执行指南 解释所选字段背后的解析路径。应用程序代码应检查两个响应部分，而不是将数据的存在视为完全成功。已部署传输的状态和错误约定也很重要。

GraphQL 与 REST 导向接口的比较

一个面向REST的API围绕资源和表示在统一接口下组织交互。GraphQL围绕模式字段和操作组织客户端请求。这两种风格都可以良好或糟糕地实现。选择会影响客户端如何发现数据，服务器如何限制工作，以及如何管理缓存或版本变化；它并不决定基础数据是否准确。

当许多客户端想要相同的表示时，资源端点可以很容易被缓存和推理。GraphQL 字段选择在客户端需要不同组合的相关数据时非常有帮助。它可能会使共享 HTTP 缓存变得不那么直接，因为不同的查询文档可以针对相同的端点。团队通常添加操作级控制和应用缓存来管理这种权衡。

GraphQL 并没有消除对分页、过滤规则或授权的需求。即使是一个 HTTP 请求，查询请求许多嵌套对象也可能是昂贵的。评估客户端体验和服务器成本时，要考虑实际操作，包括故意的大型或格式错误的选择。计算基础工作，而不仅仅是网络往返次数。

为什么浏览器页面可能使用 GraphQL

现代页面可以加载一个HTML外壳，然后请求可见界面的结构化数据。它的网络流量可能包括GraphQL操作，其响应字段用于提供卡片或仪表盘。 无刮擦代理浏览器 运行页面及其JavaScript，通过浏览器自动化使渲染状态可观察。 代理浏览器文档 涵盖了该浏览器执行角色。

在开发者工具中观察到的GraphQL请求不一定是受支持的公共API。它可能依赖于cookie、私人帐户数据或没有通知即改变的前端合同。相关的 浏览器网络检查指南 将观察与权限区分。当存在文档API时，优先选择，并将分析限制在公共或明确授权的数据上。

当任务是验证用户所见时，渲染的浏览器输出和底层网络数据回答不同的问题。一个GraphQL响应可能包含页面从未显示的字段；页面可能会转换或省略它们。决定您的用例需要哪种表示，并记录足够的上下文以解释为什么该表示是正确的。

安全设计和使用GraphQL

在服务器上，在敏感数据可以解决的字段或资源边界应用授权。一个模式字段的存在并不意味着每个用户都可以读取其值。用服务器支持的复杂度、分页或深度控制来限制昂贵的操作。观察实际的解析器工作，以便一个看似紧凑的查询不会默默扩展成大型后端工作负载。

在客户端，将查询文档保持在接近使用它们的屏幕或操作的地方。只请求需要的字段，给变量明确的类型，并处理可空值和部分错误。模式的更改应针对实际客户端操作进行审查；添加字段可能是安全的，而更改已建立字段的含义可能会破坏客户端，即使语法仍然有效。

对于您未操作的服务，阅读其公共文档，而不是反向工程特权操作。测试窄授权查询并检查其响应结构。如果服务发生变化，模式错误或意外的null应导致合同审查，而不是假设浏览器页面或其内部流量授予更广泛的数据权利。

结论

GraphQL允许客户端从一个类型化API模式中选择字段，并根据这些选择接收结果。模式改善了可发现性和验证，而服务仍然拥有执行成本、授权和数据质量。使用实际客户端查询和实际服务器合同评估GraphQL。