通过GitHub API了解下一代API实现方式GraphQL

1 年 ago

雅, 悟

2 minutes

最近，GitHub公开了支持GraphQL格式的API。未来，这将成为主流，并提供了从现有的REST API迁移到GraphQL的迁移指南。

我想通过实际调用GitHub的API来解释一下GraphQL的机制。

GraphQL 是什么？

历史

据说，GraphQL从2012年左右开始在Facebook中开始使用。后来在2015年的React.js Conf上进行了介绍，引起了轰动，并在同年以“技术预览”的状态作为开源项目公开发布。随后，规范得到了进一步的完善，并在2016年9月正式作为官方实现发布，摆脱了“预览”的状态。与此同时，GitHub也发布了GraphQL版本的API。关于这些经过的详细信息可以在以下的博客中找到。

退出技术预览

GraphQL的优点

以下是GraphQL的三个优点（来自官方）：

例えばIssueのタイトルだけが欲しい場合、REST APIだとIssueのAPIを叩いたらIssueの情報がドバッと返ってきます。GraphQLは必要なデータ構造とフィールドをリクエストで送ることができ、その情報だけを受け取れることができます。一言で言うとエコです。

関連するオブジェクトを1クエリで処理できる

例えば「Issueを投稿したユーザーの画像」を取ろうとした場合、REST APIだとIssueをまず取ってきてその中の投稿ユーザーのIDを使って今度はユーザーのAPIを叩いて・・・とやらなくてはなりません。GraphQLではデータ構造を記述する際関連オブジェクトの構造もネストすることができるため、1クエリで関連に基づくデータを一度に取得することができます。一言でいうと省エネです。

クエリの検証が容易

上記で述べた通り、GraphQLではデータ構造をクエリとして送ることから始まります。このデータ構造は当然事前に定義が可能なため、クエリとして送られた構造のチェックは容易ですし、クライアント側はどんな型のデータが返ってくるか事前に想定することができます。一言でいうと型ってます。

让我们通过亲自去体验一下，来证实所听所闻不如亲眼所见的道理。GitHub提供了一个用于实际测试和调试GraphQL的接口。请在这里亲自执行并体验GraphQL。

GitHub的GraphQL API

只请求必要的数据并接收

那么，我们马上用GraphQL来“请求并接收所需数据”。我想通过GraphQL获取最近创建的用于检测错字的存储库的信息。

左侧的查询如下所示。

query { 
  repository(owner: "chakki-works", name: "typot") { 
    name,
    description,
    license
  }
}

GraphQL从操作的声明开始。具体来说，声明可以是获取数据（query）或更新数据（mutation）。由于本次操作是获取信息，所以使用query。

接下来，声明执行查询的目标字段（Field）。可以在Field中传递参数（arguments）作为条件，这里使用owner和name来指定条件。有关可用的Field和可以传递的条件，都在文档中有详细说明。

GraphQL API v4/查询/字段

从这个文档中可以得知，通过查询(query)可以访问到名为repository的字段(Field)，该字段需要owner和name作为参数(Argument)。这些参数的类型是字符串(String)，并且是必填的(有感叹号表示必填参数)。
另外，可以得出repository字段返回的是一个Repository对象(虽然括号会让人误以为这个字段是参数，实际上它是返回值)。我认为GraphQL是为了支持嵌套结构而存在的，如果把文档中的括号()在脑海中替换成{}，就会更容易理解。

在中国，以下是该问题的一个选项的中文释义：

要知道Repository对象包含哪些属性，你可以在链接页面上的文档中确认。

GraphQL API v4/Repository 可以翻译成：GraphQL API 第4版/代码仓库。

这次我们只从这里获取名称、描述和许可证。这是一个”仅获取必要数据”的请求。其执行结果如下所示。

{
  "data": {
    "repository": {
      "name": "typot",
      "description": "Detect typo automatically, Adopt fix just by checking",
      "license": "Apache License 2.0"
    }
  }
}

我想您能够理解，我们会返回您要求的相应数据！这很环保呢。

能够在一个查询中处理相关对象的功能

GraphQL的魅力之一就是能够在一个查询中处理相关的对象。现在让我们编辑之前的查询，尝试获取“存储库的问题”。

query { 
  repository(owner: "chakki-works", name: "typot") { 
    name,
    description,
    license,
    issues(first: 10, states: OPEN){
      totalCount,
      edges{
        node {
          title
        }
      }
    }
  }
}

我们正在添加一个名为”issues”的新连接。这个连接表示相关性，通过”issues”，我们可以从存储库获取与问题相关的问题连接”IssueConnection”。

GraphQL API v4/IssueConnection 的原生中文解释翻译：GraphQL API v4/问题连接。

根据问题(issue)可获得 IssueConnection，即连接到每个问题(issue)的内容，通过传递 edges 可以访问问题(issue)的信息(其实直接使用 nodes 也可以)。在这里，我们展示了问题(issue)的标题。通过这样可以获得以下类似的响应。

{
  "data": {
    "repository": {
      "name": "typot",
      "description": "Detect typo automatically, Adopt fix just by checking",
      "license": "Apache License 2.0",
      "issues": {
        "totalCount": 3,
        "edges": [
          {
            "node": {
              "title": "Support comments in source code"
            }
          },
          {
            "node": {
              "title": "Exclude word list (white list) for repository"
            }
          },
          {
            "node": {
              "title": "False positives reported"
            }
          }
        ]
      }
    }
  }
}

通过向包含 Connection 的数据结构发送请求，您可以在一个查询中获取相关数据。这是 GraphQL 的一个强大功能之一。

如果你认为node的类型像Object一样很讨厌，你可以写明类型。

query { 
  repository(owner: "chakki-works", name: "typot") { 
    name,
    description,
    license,
    issues(first: 10, states: OPEN){
      totalCount,
      edges{
        node {
          ... on Issue {
            title
          }
        }
      }
    }
  }
}

在Issue上，当节点的类型为Issue时，我们将显示标题。关于类型的表示方式，请查看GraphQL的官方文档。

模式和类型

查询验证很容易

当你实际尝试使用Explorer时，你会发现它能够提供相当智能的补全和错误提示信息。

这是一个由于数据类型的定义，使得在查询和响应中都以此为中心进行操作的规格的产物。

注意，这个GitHub上提供的Explorer是基于开源的graphiql开发的。
也就是说，只要有实现API的类型（模式）文件，就可以通过将这个定义导入到这个工具中，从而为用户提供API的执行环境（您可以在示例中确认执行方式）。通过使用GraphQL进行API定义，我认为这不仅能提供基于类型的验证，还可以提供试验环境，这是采用GraphQL的重要优点。

除了上述介绍的内容之外，GraphQL还具有许多其他功能。我希望您能以GitHub API为起点尝试一下。

请参考以下内容

GraphQL