GraphQL 简介

GraphQL 术语

GitHub GraphQL API 代表了从 GitHub REST API 的架构和概念上的转变。您可能会在 GraphQL API 参考文档中遇到一些新的术语。

模式

模式定义了 GraphQL API 的类型系统。它描述了客户端可以访问的完整数据集（对象、字段、关系，所有内容）。来自客户端的调用将根据模式进行验证和执行。客户端可以通过内省找到有关模式的信息。模式驻留在 GraphQL API 服务器上。有关更多信息，请参阅“探索 GraphQL API”。

字段

字段是您可以从对象中检索的数据单元。正如官方 GraphQL 文档所说：“GraphQL 查询语言基本上是关于选择对象上的字段。”

官方规范也关于字段说

所有 GraphQL 操作都必须将它们的选定内容指定到返回标量值的字段，以确保响应的形状明确无误。

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

参数

参数是附加到特定字段的一组键值对。某些字段需要参数。变异需要输入对象作为参数。

实现

GraphQL 模式可以使用术语 implements 来定义对象如何从接口继承。

这是一个关于定义接口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”。

将它想象成一个图：点由线连接。点是节点，线是边。连接定义了节点之间的关系。

边

边表示节点之间的连接。当您查询连接时，您会遍历其边以到达其节点。每个edges字段都有一个node字段和一个cursor字段。游标用于分页。有关更多信息，请参阅“在 GraphQL API 中使用分页”。

节点

节点是对象的通用术语。您可以直接查找节点，也可以通过连接访问相关节点。如果您指定一个不返回标量的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，请确保您的细粒度个人访问令牌已针对正确的资源所有者。例如，它必须针对拥有您尝试访问的存储库的组织。

结果以 JSON 格式显示，因此我们建议您将它们美化以方便阅读和搜索。您可以为此目的使用像 jq 这样的命令行工具，或者将结果管道到 python -m json.tool 中。

或者，您可以传递 idl 媒体类型以以 IDL 格式返回结果，IDL 格式是模式的简化版本
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
https://api.github.com/graphql
```
注意：内省查询可能是您在 GraphQL 中运行的唯一 GET 请求。如果您正在传递主体，则 GraphQL 请求方法为 POST，无论是查询还是变异。

有关执行查询的更多信息，请参阅“使用 GraphQL 形成调用”。

本文介绍