GraphQL 简介

GraphQL 术语

GitHub GraphQL API 表示与 GitHub REST API 的体系结构和概念转变。你可能会在 GraphQL API 参考文档中遇到一些新术语。

架构

架构可定义 GraphQL API 的类型系统。它描述了客户端可以access的完整数据集（对象、字段、关系、所有内容）。客户端的调用会针对架构进行验证和执行。客户端可通过内省找到有关架构的信息。架构位于 GraphQL API 服务器上。有关详细信息，请参阅发现 GraphQL API。

字段

字段是一种可从对象检索的数据单元。正如官方 GraphQL 文档所述：“GraphQL 查询语言主要关于选择对象的字段。”。

          [官方规范](https://spec.graphql.org/June2018/#sec-Language.Fields)还提到了字段：

所有 GraphQL 操作都必须将其选项指定为可返回标量值的字段，以确保得到明确响应。

这意味着，如果您尝试返回的字段不是标量，架构验证将出现错误。必须添加嵌套子字段，直到所有字段都返回标量。

参数

参数是指一组附加至特定字段的键值对。某些字段需要一个参数。 Mutations需要输入对象作为参数。

实现

GraphQL 架构可以使用术语“实现”来定义对象如何从_接口_继承。

下面是定义接口 X 和对象 Y 的架构的设计示例：

interface X {
  some_field: String!
  other_field: String!
}

type Y implements X {
  some_field: String!
  other_field: String!
  new_field: String!
}

这意味着，对象 Y 需要与接口 X 相同的字段/参数/返回类型，同时添加特定于对象 Y 的新字段。（! 表示该字段为必填项。）

在参考文档中，您将发现：

每个对象在_实现_下列出了它从中继承的接口。
每个接口在“实现”下列出了继承自它的对象。

连接

连接可用于查询作为同一个调用的一部分的相关对象。通过连接，可以使用单个 GraphQL 调用，其中，必须对 REST API 使用多个调用。有关详细信息，请参阅从 REST 迁移到 GraphQL。

想象一幅图：点之间用线相连。点是节点，线是边缘。连接可定义节点之间的关系。

Edge

边缘表示节点之间的连接。查询连接时，可以遍历边缘获取节点。每个 edges 字段都有一个 node 字段和 cursor 一个字段。游标用于分页。有关详细信息，请参阅在 GraphQL API 中实现分页。

Node

Node 是对象的通用术语。可以直接查找节点，也可以通过连接访问相关节点。如果您指定的node不返回标量，则必须包含子字段，直到所有字段都返回标量。有关通过 REST API 访问节点 ID 并在 GraphQL 查询中使用它们的信息，请参阅使用全局节点 ID。

探索 GraphQL API

GraphQL 是内省的。这意味着，您可以查询 GraphQL 架构，了解关于其自身的详细信息。

查询 __schema 以列出架构中定义的所有类型并获取关于每个类型的详细信息：

query {
  __schema {
    types {
      name
      kind
      description
      fields {
        name
      }
    }
  }
}

查询 __type 以获取有关任何类型的详细信息：

query {
  __type(name: "Repository") {
    name
    kind
    description
    fields {
      name
    }
  }
}

你也可以通过 __ 请求运行架构的GET：
```
curl -H "Authorization: bearer TOKEN" https://api.github.com/graphql
```
注意

如果收到响应 "message": "Bad credentials" 或 401 Unauthorized，请检查你所使用的令牌是否有效。如果收到具有 403 的 Resource not accessible by personal access token 错误，请确保 fine-grained personal access token 将正确的资源所有者作为目标。例如，它必须以拥有你要尝试访问的存储库的组织为目标。

结果出现在 JSON 中，因此，我们建议整洁打印，以便阅读和搜索。为此，可以使用命令行工具（如 jq）将结果管道传递到 python -m json.tool。

或者，也可以传递 idl 媒体类型，以返回 IDL 格式的结果，这是架构的压缩版本：
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
https://api.github.com/graphql
```
注意

自省查询可能是你在 GraphQL 中唯一会运行的 GET 请求。如果要传递正文，则无论是查询还是突变，GraphQL 请求方法都为 POST。

有关执行查询的详细信息，请参阅使用 GraphQL 建立调用。

在本文中