使用 JavaScript API 状态练习 GraphQL 查询

学习如何构建 GraphQL API 可能非常具有挑战性。但是您可以在 10 分钟内学习如何使用 GraphQL API！碰巧我有一个完美的 API 可以做到这一点：全新的、刚从 VS Code 中诞生的 State of JavaScript GraphQL API。

State of JavaScript 调查是对 JavaScript 领域的年度调查。我们已经做了四年了，最新一期收到了超过 20,000 名开发人员的参与。

我们一直依靠 Gatsby 来构建我们的展示网站，但直到今年，我们才以静态 YAML 文件的形式将数据提供给 Gatsby，这些文件是通过某种凡人称为“ElasticSearch”的奥秘魔法生成的。

但由于 Gatsby 无论如何都会将所有数据源以 GraphQL 的形式输出，所以我们认为我们不妨跳过中间商，直接用 GraphQL 来提供数据！是的，我知道，这个比喻越来越糟糕了，我对此感到后悔。我的意思是：我们为我们的数据构建了一个内部 GraphQL API，现在我们将其提供给所有人，以便您也可以轻松利用我们的数据集！

“但是等等，”你说。“我一生都在学习刀刃，这让我没有时间学习 GraphQL！”不用担心：这就是本文的作用。

什么是 GraphQL？

从本质上讲，GraphQL 是一种语法，它允许您指定要从 API 中接收哪些数据。请注意，我说的是API，而不是数据库。与 SQL 不同，GraphQL 查询不会直接访问您的数据库，而是访问您的 GraphQL API 端点，该端点又可以连接到数据库或任何其他数据源。

与 REST 等旧范例相比，GraphQL 的最大优势在于它允许您请求所需的内容。例如

query {
  user(id: "foo123") {
    name
  }
}

将为您提供一个具有单个name字段的用户对象。还需要电子邮件？只需执行

query {
  user(id: "foo123") {
    name
    email
  }
}

如您所见，此示例中的 user 字段支持id参数。现在我们来看 GraphQL 最酷的功能，嵌套

query {
  user(id: "foo123") {
    name
    email
    posts { 
      title
      body
    }
  }
}

在这里，我们说我们想找到用户的posts，并加载它们的title和body。GraphQL 的好处在于，我们的 API 层可以完成弄清楚如何以特定格式获取这些额外信息的工作，因为我们没有直接与数据库对话，即使它没有以嵌套格式存储在我们的实际数据库中。

Sebastian Scholl 做了一项很棒的工作，解释了 GraphQL，就好像您第一次在鸡尾酒会上遇到它一样。

介绍 GraphiQL

GraphiQL（注意其中的“i”）是最常见的 GraphQL IDE，也是我们用来探索 State of JavaScript API 的工具。您现在可以立即在 graphiql.stateofjs.com 上启动它，它将自动连接到我们的端点（即 api.stateofjs.com/graphql）。该 UI 由三个主要元素组成：资源管理器面板、查询构建器和结果面板。我们稍后会将文档面板添加到其中，但现在让我们保持简单。

资源管理器选项卡是 GraphiQL 的一个涡轮增压版本的组成部分，该版本由 OneGraph 开发和维护。非常感谢他们帮助我们集成它。如果您想部署自己的 GraphiQL 实例，请务必查看他们的示例存储库。

别担心，我不会让你现在就编写任何代码。相反，让我们从现有的 GraphQL 查询开始，例如与过去四年中 React 的开发人员体验相对应的查询。

还记得我说过我们在内部使用 GraphQL 来构建我们的网站吗？我们不仅公开了 API，还公开了查询本身。单击小“导出”按钮，复制“GraphQL”选项卡中的查询，将其粘贴到 GraphiQL 的查询构建器窗口中，然后单击“播放”按钮。

如果一切按计划进行，您应该会看到数据出现在“结果”面板中。让我们花点时间分析一下查询。

query react_experienceQuery {
  survey(survey: js) {
    tool(id: react) {
      id
      entity {
        homepage
        name
        github {
          url
        }
      }
      experience {
        allYears {
          year
          total
          completion {
            count
            percentage
          }
          awarenessInterestSatisfaction {
            awareness
            interest
            satisfaction
          }
          buckets {
            id
            count
            percentage
          }
        }
      }
    }
  }
}

首先是query关键字，它定义了我们 GraphQL 查询的开始，以及查询的名称react_experienceQuery。查询名称在 GraphQL 中是可选的，但对于调试目的很有用。

然后是我们的第一个字段survey，它采用survey参数。（我们还有一个 State of CSS 调查，因此我们需要指定相关的调查。）然后是tool字段，它采用id参数。之后的所有内容都与该特定工具的 API 结果相关。entity为您提供有关所选特定工具（例如 React）的信息，而experience包含实际的统计数据。

现在，与其在这里继续遍历所有这些字段，不如我教你一个小技巧：在 GraphiQL 中Command + 单击（或Control + 单击）任何这些字段，它将调出“文档”面板。恭喜，您刚刚见证了 GraphQL 的另一个巧妙技巧，自文档！您可以在 API 定义中直接编写文档，GraphiQL 将依次将其提供给最终用户。

更改变量

让我们稍微调整一下：在查询构建器中，将“react”替换为“vuejs”，您应该会注意到另一件很酷的 GraphQL 事情：自动完成功能。这对于避免出错或节省时间非常有用！再次按下“播放”，您将获得相同的数据，但这次是针对 Vue 的。

使用资源管理器

我们现在将解锁另一个 GraphQL 强大工具：资源管理器。资源管理器基本上是整个 API 的树，它不仅允许您可视化其结构，还允许您在不编写任何代码的情况下构建查询！因此，让我们尝试使用资源管理器重新创建我们的 React 查询。

首先，让我们打开一个新的浏览器选项卡并在其中加载 graphiql.stateofjs.com 以全新开始。在资源管理器中单击survey节点，在其下单击tool节点，然后单击“播放”。工具的id字段应自动添加到结果中，顺便说一句，这是一个更改默认参数值（“typescript”）为“react”的好时机。

接下来，让我们继续深入。如果您添加entity而不添加任何子字段，您应该会看到其下方有一条红色波浪线，提示您还需要指定一个或多个子字段。因此，让我们至少添加id、name和homepage。另一个有用的技巧：您可以通过在资源管理器中按住 option+control 并单击它来自动告诉 GraphiQL 添加字段的所有子字段。

接下来是experience。继续添加字段和子字段，直到获得与您最初从 State of JavaScript 网站复制的查询接近的内容。您选择的任何项目都会立即反映在查询构建器面板中。就是这样，您刚刚编写了您的第一个 GraphQL 查询！

过滤数据

您可能已经注意到experience下有一个紫色filters项目。这实际上是您想要使用我们的 GraphQL API 而不是简单地浏览我们网站的关键原因：API 提供的任何聚合都可以通过许多因素进行过滤，例如受访者的性别、公司规模、薪资或国家/地区。

展开filters并选择companySize，然后选择eq和range_more_than_1000。您刚刚计算了大型公司中 React 的受欢迎程度！选择range_1，您现在可以将其与自由职业者和独立开发人员中的相同数据点进行比较。

需要注意的是，GraphQL 仅定义非常低级的基元，例如字段和参数，因此这些eq、in、nin等过滤器本身不是 GraphQL 的一部分，而只是我们在设置 API 时自己定义的参数。这最初可能需要大量工作，但它确实可以让您完全控制客户端如何查询您的 API。

结论

希望您已经看到查询 GraphQL API 并不是什么大不了的事，尤其是在像 GraphiQL 这样很棒的工具的帮助下。当然，将 GraphQL 数据实际集成到现实世界的应用程序中是另一回事，但这主要是因为处理客户端和服务器之间的数据传输的复杂性。GraphQL 本身实际上非常简单！

无论您是想开始使用 GraphQL，还是只是学习足够的知识来查询我们的数据并获得一些惊人的新见解，我都希望本指南对您有所帮助！

如果您有兴趣参加我们的下一次调查（应该是 State of CSS 2020），请务必注册我们的邮件列表，以便在我们启动调查时收到通知。

State of JavaScript API 参考

您可以在 api.stateofjs.com 找到有关 API 的更多信息（包括指向实际端点和 GitHub 存储库的链接）。

以下是 State of JS API 中使用的术语的简要词汇表。

顶级字段

人口统计：对所有人口统计信息进行分组，例如性别、公司规模、薪资等。
实体：提供有关特定“实体”（库、框架、编程语言等）的更多信息。
特性：特定 JavaScript 或 CSS 特性的使用数据。
特性：相同，但在多个特性中。
矩阵：提供用于填充我们的交叉引用热图的数据。
意见：特定问题的意见数据（例如，“您认为 JavaScript 正在朝着正确的方向发展吗？”）。
其他工具：“其他工具”部分的数据（文本编辑器、浏览器、打包程序等）。
资源：“资源”部分的数据（网站、博客、播客等）。
工具：特定工具（库、框架等）的使用体验数据。
工具：相同，但在多个工具中。
工具排名：多个工具的排名（知名度、兴趣度、满意度）。

常用字段

完成率：回答任何给定问题的调查受访者比例。
桶：包含实际数据的数组。
年份/所有年份：获取特定调查年份的数据；或包含所有年份的数组。