GraphQL 简介

GraphQL 术语

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

模式

模式定义了 GraphQL API 的类型系统。它描述了客户端可以访问的全部可能数据（对象、字段、关系等）。客户端的调用会针对模式进行验证并执行。客户端可以通过自省获取模式信息。模式驻留在 GraphQL API 服务器上。欲了解更多信息，请参见发现 GraphQL API。

字段

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

官方规范也对字段作了说明

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

这意味着如果尝试返回非标量字段，模式验证会抛出错误。您必须添加嵌套的子字段，直至所有字段均返回标量。

参数

参数是一组附加在特定字段上的键值对。某些字段需要参数。变更（Mutations）需要将输入对象作为参数。

实现

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 特有的新字段。（! 表示该字段为必填。）

在参考文档中，您会发现

每个对象在 Implements 下列出它 继承自 的接口。
每个接口在 Implementations 下列出 继承自该接口的对象。

连接

连接让您在同一次调用中查询相关对象。使用连接，您可以用一次 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 格式返回结果，这是一种精简版的模式表示。
```
$ curl -H "Authorization: bearer TOKEN" -H "Accept: application/vnd.github.v4.idl" \
https://api.github.com/graphql
```
注意

自省查询可能是您在 GraphQL 中唯一会使用的 GET 请求。如果您发送请求体，则 GraphQL 请求方法为 POST，无论是查询还是变更（mutation）。

有关执行查询的更多信息，请参见使用 GraphQL 进行调用。

本文内容