GitHub GraphQL使用指南

首先要学习Graphql定义,先看一遍Graphql官方文档,初步了解一下Graphql是个啥东西,然后再来看这篇文档。 虽然这个时候,你仍然会看不懂..... 一遍不行,就看两遍。 文档读百遍,其义必自见。

首先Github Graphql官方定义在https://developer.github.com 这里。 Github将Graphql的Query类型定义为了三类: * Connections * Nodes * Edges​

Node

每个单纯的数据对象, 独立的数据点。 每个Node表示一个Schema,例如Users。如果你指明的node不是返回标量,你必须在其中包含内部field直至所有的field都返回标量。 原文如下:

Node is a generic term for an object.  
You can look up a node directly, or you can access related nodes via a connection.  
If you specify a node that does not return a scalar, you must include subfields until all fields return scalars.  
For information on accessing node IDs in the REST API v3, see "GraphQL Global Relay IDs."  

Edges

每个Edges至少链接两个node. 通过Edges可以追溯到链接的node。 每个Edges都包含一个Node属性和Cursor属性。原文如下:

Edges represent connections between nodes. When you query a connection, you traverse its edges to get to its nodes. Every edges field has a node field and a cursor field.  
Cursors are used for pagination.  

Connects

Node是孤立的点,通过Edges就链接成线。 Connects就是这些点和线所组成的关系。

下面先从最简单的查询操作入手,来看看如何使用Graphql。

假设,我们要查询一个指定仓库的所有分支。应该如何操作呢?

先看看Github给我们提供了哪些可以使用的Fields,在https://developer.github.com/v4/query/#connections最下面可以发现repository属性。

点击repository(https://developer.github.com/v4/object/repository/)之后,可以看到其有refs属性.

refs属性正好就是: Fetch a list of refs from the repository

此时,我们可以写出下面的查询语句:

{
  repository(owner:"andy-zhangtao",name:"DDog"){
    refs(refPrefix:"refs/heads/",first:100){
      xxxx
    }
  }
}

owner是准备要查询的github用户, name是指定的仓库名称。 查阅文档,refs属性的refPrefix属性是必填项,因此我们设置一个搜索前缀:refs/heads/。

refs返回的是RefConnection(https://developer.github.com/v4/object/refconnection/)。 由最上面的介绍可以得知,connect表示的是node和Edges直接的关系,因此需要通过Edges找到所有关联的node。

{
  repository(owner:"andy-zhangtao",name:"DDog"){
    refs(refPrefix:"refs/heads/",first:100){
      edges{
        node{
          xxxx
        }
      }
    }
  }
}

因为我已知分支不会有太多,因此就不再获取Cursour,直接读取node属性。 此时的node表示的是Ref节点(https://developer.github.com/v4/object/ref/ )。在ref节点中,可以看到有name属性, prefix属性。 这里,我们只需要读取name属性就足够了。因此最终的Query语句如下:

{
  repository(owner:"andy-zhangtao",name:"DDog"){
    refs(refPrefix:"refs/heads/",first:100){
      edges{
        node{
          name
        }
      }
    }
  }
}

运行后的结果如下:

{
  "data": {
    "repository": {
      "refs": {
        "edges": [
          {
            "node": {
              "name": "develop"
            }
          },
          {
            "node": {
              "name": "master"
            }
          },
          {
            "node": {
              "name": "svc-schedule"
            }
          }
        ]
      }
    }
  }
}

与实际结果相吻合。