GraphQL 简介

GraphQL 术语

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

模式

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

字段

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

官方规范也对字段进行了说明

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

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

参数

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

实现

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”。

将图示化很有帮助：用线连接的点。点是节点，线是边。连接定义了节点之间的关系。

边

边表示节点之间的连接。当您查询连接时，您会遍历其边以到达其节点。每个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，请检查您是否使用了有效的令牌。如果您收到带有Resource not accessible by personal access token的403错误，请确保您的细粒度个人访问令牌已针对正确的资源所有者。例如，它必须针对拥有您尝试访问的存储库的组织。

结果为 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 进行表单调用”。

本文内容