GraphQL 与 GitHub - 开发属于你的 GitHub 应用

Posted 2021-04-30 SwiftCafe

这次咱们聊的话题和 GitHub 有关。 毫无疑问的，GitHub 已经成为开发者不可缺少的一个平台。 尤其是这里的读者们，一定对它很熟悉了。 我们在开发项目的时候或多或少会用到各种开源库，来提高我们的效率，而 Github 几乎成为了寻找开源库的第一去处。 

下面要和大家说的，不是怎么去使用 GitHub 平台，相信屏幕前的大多数朋友都已经对这个很熟悉了。 而是和大家说另外一个话题， 就是 GitHub 的开放平台。 通过开放平台，我们其实能做很多有意思的事情，之前微信群里就有不少朋友开发出了很多好玩的 GitHub 应用。 所以我相信，作为开发者的各位，一定都很有兴趣创造各种新鲜事物，今天就和大家聊聊这个话题。

GitHub 开放平台

GitHub 开放平台由来已久，https://developer.github.com 是它的开发者平台主页：

从图中上面的菜单上，大家可以看到，当前 GitHub 提供了两套 API。 一个是 v3 的 REST API， 另外一个就是最新的 v4 GraphQL API。 这次给大家介绍的也是最新的 GraphQL API。 

GraphQL 本身是一种全新的数据通信格式，它的官网 http://graphql.org/ 里面有详细的说明。 这里我们暂时不多赘述，只需要知道它是一种通过 HTTP 发送的数据通信协议，并且 GitHub 最新的开放接口中使用它作为通信格式。 了解这个基本关系背景即可。

使用 GraphQL

关于 GraphQL 是什么，先给大家建立一个感官的认识。简单来说，它就是通过 HTTP 协议发送的一组特殊的数据，服务端得到这个数据后，可以按照相应的规则把结果返回。 从原理上来说，它和普通的请求参数没什么两样，但它的好处是更加灵活，至于怎么个灵活呢？ 咱们看一个实例就明白了。

GitHub 的 GraphQL API 只有一个接口： https://api.github.com/graphql

我们只需要向这个接口发送我们指定的查询条件，就可以得到我们需要的各种数据：

query {
  viewer {  
    login  
  }
}

上面这段代码，就是 GraphQL 的查询条件。 这段查询的含义是，获取当前 GitHub 登录用户的名称。我们直接以 HTTP 方式把这段字符串发送给 https://api.github.com/graphql 这个接口，就完成了一次 GraphQL 查询：

curl -H "Authorization: bearer token" -X POST -d " \
 { \   
   \"query\": \"query { viewer { login }}\" \ 
 } \
" https://api.github.com/graphql

curl 是通过命令行发送 HTTP 请求的工具， 上面这个命令就是把刚才那段 GraphQL 查询，通过 HTTP POST 方式发送给 GitHub 服务器。 仔细看一下这条命令，其中包含一段这样的内容：

-H "Authorization: bearer token"

这段是验证信息，其中包含一个 token 字段。 这个字段是你访问 GitHub API 的用户标识。在调用 GraphQL 接口之前，你需要申请一个属于你的 token。 这些都就绪后，这个 GraphQL 请求就跑通了。

关于如何申请 token， 稍后会给大家讲解。 咱们先来看一个更有用的。

也就是除了通过 curl 这种命令行方式直接发送 HTTP 请求之外。 你还可以通过应用程序直接发送，比如你用 Swift 写的 ios APP，通过网络库直接请求。 但需要注意，GraphQL 的 HTTP 请求，一定要是 POST 方式的，否则会被服务器拒绝。

另外，除了以上方式外， GitHub 还提供了一个调试利器，GraphQL Explorer  https://developer.github.com/v4/explorer/:

从图中可以看到， 我们在左边输入 GraphQL 的查询条件，点击运行后，在右边就会显示出结果：

{  
  "data": {    
    "viewer": {      
       "login": "swiftcafex"    }  } }

仔细的朋友后应该会发现， 返回结果的数据结构和我们 GraphQL 查询的结构基本一样， 只是返回结果中带上了查询后的返回值。 比如这里的 login， 后面带上了我当前登录的用户名。

获取用户 Token

我们刚才说过，在访问 GitHub GraphQL 接口之前，你需要得到一个你的用户 Token。 首先进入你的用户设置：

然后进入开发者设置：

找到 Personal access tokens 选项， 然后点击右上角的生成按钮：

在生成页面中，选择你需要的权限，比如访问仓库，创建 Gist 等等，按需选择：

有了 Token 后，就可以用它来访问 GraphQL API 了。

一个有趣的查询

下面咱们来看这样一个 GraphQL 查询：

query {  search(type: REPOSITORY, query: "swift", first: 5) {    edges{      node {        ... on Repository {          nameWithOwner          homepageUrl          primaryLanguage {            name          }          url          }      }    }  } }

query 是查询根节点， 紧接着是一个 search， 代表搜索 GitHub 代码库， 关键词为 swift 的前 5 条记录。 然后在内层嵌套中， 输出搜索到的代码库一些属性，比如 url，仓库名称等。

这段查询运行的结果如下图所示：

关于 GraphQL 的完整语义文档，大家可以参看 GitHub 官方的说明： (https://developer.github.com/v4/reference)[https://developer.github.com/v4/reference]。

里面的定义非常多，足够你使用，请按需查询，这里不详细介绍了。 

GraphQL 不止于 GitHub

正如前面和大家说的 GraphQL 和 GitHub 是两个独立的东西。 也就是说 GraphQL 本身是独立于 GitHub 的一套体系。 GitHub 只是用它来作为新的 API 的数据协议。

如果你的产品需要设计接口，也可以使用 GraphQL 作为你的方案。 

结语

今天和大家聊了 GraphQL 和 Github 的一些基本使用方法。 也只是做了一个抛砖引玉的作用。 也是因为之前在我们的技术交流群中看到不少朋友开发过一些有趣的东西，所以才想到写了这篇内容。 

如今的 GitHub 几乎已经成为了每个程序员的必备品。 利用开放平台，再加上合理的产品运营，其实能产生不少好的产品。 不知道有多少朋友知道 Mac 平台的以及各叫做 DASH 的软件，一个技术文档浏览工具，据说这个软件在 Mac 商店上取得了很不错的收入。所以任何产品，如果能把细节做得足够好，都是会有一定市场的。

就聊这么多，感谢大家花费宝贵时间的阅读，欢迎留言，加群，讨论。