GraphQL 的入门指南

阿里云最近在作活动，低至2折，有兴趣能够看看：
https://promotion.aliyun.com/...

---

为了保证的可读性，本文采用意译而非直译。

想阅读更多优质文章请猛戳GitHub博客,一年百来篇优质文章等着你！

今天最常讨论的术语之一是 API，不少人不知道 API 究竟是什么，API 是 Application Programming Interface(应用程序编程接口)。顾名思义，它是一些预先定义的函数，目的是提供应用程序与开发人员基于某软件或硬件得以访问一组例程的能力，而又无需访问源码，或理解内部工做机制的细节。

你能够将 API 想象成一个酒保。你向酒保要一杯酒，他们会给你想要的。简单，可是传统的 REST API 有什么问题的呢？

自从现代 Web 出现以来，构建 Api 并不像听起来那么困难，可是学习和理解 Api 才是比较难。开发人员是大多数据使用你的 API 来构建某些内容或仅使用数据。因此你的 API 应该尽量的简洁和直观， 好的 API 是很是容易使用和学习的。直观，在开始设计 API 时常要记住的一点。

咱们已经使用 REST 构建 Api 很长时间了。随之而来的也有一些问题，在使用 REST 设计构建 API 时，你会遇到如下问题:

• 涉及不少端
• 于开发人员来讲，学习和理解你的 API 要困可贵多

*　信息的获取有多有少

为了解决这些问题，Facebook 建立了 GraphQL。如今，做者认为 GraphQL 是构建 Api 的最佳方式。这篇文章将告诉你为何要学习了解一下 GraphQL。

什么是 GraphQL

GraphQL 是 Facebook 开发的一种开源查询语言。它为咱们提供了一种更有效的设计、建立和使用 Api的方法。从根本上说，它是 REST 的替代品。

GraphQL有不少特性，好比:

1. GraphQL查询老是能准确得到你想要的数据，很少很多，因此返回的结果是可预测的， 再也不像你使用 REST 那样过分获取信息。
2. 它为咱们提供了同一个端，对于同一个 API，没有版本2或版本3。给 GraphQL API 添加字段和类型而无需影响现有查询，老旧字段能够废弃，从工具中隐藏。
3. GraphQL是强类型的，经过它，能够在执行以前验证 GraphQL 类型系统中的查询， 它帮助咱们构建更强大的 Api。

这是对 GraphQL 的基本介绍——为何它这么强大，为何它如今这么流行。若是你想了解更多关于它的信息，能够访问 GraphQL网站 学习。

开始

本文的主要目的不是学习如何设置 GraphQL服务器，因此咱们如今尚未深刻研究。 文本的目标是了解 GraphQL 在实践中的工做原理，所以这里使用简约的零配置 GraphQL 服务器的 Graphpack。

开始项目前，首先咱们建立一个新文件名为 graphql-server， 在 mac 终端执行

mkdir graphql-server

接着进入该文件，执行

npm init -y

或者执行

yarn init

npm 将建立一个包 package.json 文件，这个包是你安装的全部依赖项和命令。

如今，咱们要安装惟一的依赖项。

Graphpack 容许建立零配置的 GraphQL 服务器。因为刚刚开始使用 GraphQL，这将帮助咱们继续学习GraphQL 更多的内容，而没必要担忧服务器配置，执行如下命令：

npm install --save-dev graphpack

或者使用 yarn 安装：

yarn add --dev graphpack

安装 Graphpack 以后，转到 package.json文件中的脚本，并在其中输入如下代码：

"scripts": {
    "dev": "graphpack",
    "build": "graphpack build"
}

接着建立一个名为 src 的文件夹，它将是整个服务器中惟一的文件夹。

在 src 文件夹中建立一个名为 schema.graphql 的文件，并写入如下代码：

type Query {
  hello: String
}

在 schema.graphql 文件将是咱们的整个 GraphQL的模式(Schema)。

接着在 src 下建立文件 resolvers.js，并写入如下代码：

import { users } from "./db";

const resolvers = {
  Query: {
    hello: () => "Hello World!"
  }
};

export default resolvers;

这个 resolvers.js 文件是咱们提供 GraphQL 操做转换为数据的指令的方式。

接着在 src 下建立一个 db.js 文件并写入如下代码：

export let users = [
  { id: 1, name: "John Doe", email: "john@gmail.com", age: 22 },
  { id: 2, name: "Jane Doe", email: "jane@gmail.com", age: 23 }
];

在本教程中，不使用真实的数据库，因此这个 db.js 文件将模拟一个数据库，只是为了学习的目的。

如今 src 的结构以下：

src
  |--db.js
  |--resolvers.js
  |--schema.graphql

接着运行 npm run dev 或者 yarn dev 启动服务

在浏览器打开 localhost：4000。这里就实现咱们在 GraphQL 中的第一个查询，更改和订阅，打开界面以下：

你能够看到 GraphQL Playground，这是一个功能强大的 GraphQL IDE，可用于更好的开发工做流程。 若是你想了解有关 GraphQL Playground的更多信息，请单击此处。

模式（Schema）

GraphQL 有本身的语言类型，用于编写模式。 这是一种人类可读的模式语法，称为规范与描述语言（SDL）。不管使用何种技术，SDL 都是相同的 - 你能够将其用于你想要的任何语言或框架。

这种模式语言很是有用，由于它更直观的看出 API 具备哪些类型，一看到 API 就知道怎么使用。

类型（Type）

类型是 GraphQL 最重要的特性之一。类型是表示 API 外观的自定义对象。例如，若是你正在构建一个社交媒体应用程序，那么你的 API 应该具备诸如文章、用户、赞、组等类型。

类型具备字段，这些字段返回特定类型的数据。 例如，咱们要建立一个 User 类型，咱们应该有一些 name，email 和 age 字段。 类型字段能够是任何类型，并始终返回一种数据类型，如 Int，Float，String，Boolean，ID，对象类型列表或自定义对象类型。

如今编写的第一个 Type，在 schema.graphql 文件中用如下内容替换已存在的 Query 类型：

type User {
  id: ID!
  name: String!
  email: String!
  age: Int
}

每一个用户都将拥有一个 ID，所以为其提供了 ID 类型。 用户也会有一个 name 和 email，因此给它一个字符串类型和一个 Int 类型。

可是，在每一行的结尾的 ！呢？ 感叹号表示字段不可为空，这意味着每一个字段必须在每一个查询中返回一些数据。 User 中惟一能够为空的字段是 age。

在GraphQL中，有三个主要概念:

1. query (查询) — 从服务器获取数据的方式。
2. mutation (更改) — 修改服务器上的数据并获取更新数据的方法(建立、更新、删除)。
3. subscription (订阅) — 当但愿数据更改时，能够进行消息推送，使用 subscription 类型（针对当前的日趋流行的 real-time 应用提出的）。

query (查询)

为了简单地解释这一点，GraphQL 中的查询是获取数据的方式。关于 GraphQL 中的查询，最吸引人的地方之一就是你将得到所需的确切数据，很少很多。这对咱们的 API 产生了巨大的积极影响——再也不像 REST API 那样获取过多或不足的信息。

咱们将在 GraphQL 中建立第一个类型的 Query。 咱们全部的查询都将以此类型结束。 首先，在文件 schema.graphql 编写一个名为Query 的新类型：

type Query {
  users: [User!]!
}

这很简单：用户查询将返回给咱们一个或多个用户的数组。 它不会返回 null，由于咱们放入了 ! ，这意味着它是一个不可为空的查询, 它总会返回一些数据。

但咱们也能够返回特定用户。 为此，建立一个名为 user 的新查询。 在咱们的 Query 类型中，写如下代码：

user(id: ID!): User!

如今 Query 类型应该是这样的:

type Query {
  users: [User!]!
  user(id: ID!): User!
}

如上所见，使用 GraphQL 中的查询，还能够传递参数。在本例中，要查询特定用户，因此要传递其用户的 ID。

可是，你可能想知道: GraphQL 如何知道从哪里获取数据? 这就是为何咱们应该有一个 resolvers.js 文件。该文件告诉 GraphQL 它将如何以及在何处获取数据。

首先，看看咱们的 resolvers.js 文件并里该文件里导入 db.js 文件。咱们刚才建立的 resolvers.js 文件内容以下：

import { users } from "./db";

const resolvers = {
  Query: {
    hello: () => "Hello World!"
  }
};

export default resolvers;

如今，咱们将建立第一个 Query，在 resolvers.js 文件并替换 hello 函数。 如今 resolvers.js 内容以下 ：

import { users } from "./db";

const resolvers = {
  Query: {
    user: (parent, { id }, context, info) => {
      return users.find(user => user.id == id);
    },
    users: (parent, args, context, info) => {
      return users;
    }
  }
};

export default resolvers;

如今，解释它是如何工做的：

每一个查询解析器都有四个参数。 在 user 函数中，咱们将 id 做为参数传递，而后返回与传递的 id 匹配的特定 user，这很简单。

在 users 函数中，咱们只是返回已存在的 users 数组，这个数组存放的是全部的用户。

如今，咱们将测试查询是否工做正常，转到 localhost:4000，输入如下代码:

query {
  users {
    id
    name
    email
    age
  }
}

它应该返回给你咱们全部的用户。

若是想返回特定的用户:

query {
  user(id: 1) {
    id
    name
    email
    age
  }
}

mutation (更改)

在 GraphQL 中，更改是修改服务器上的数据并获取更新数据的方式， 你能够像 REST 的CUD（建立，更新，删除）同样思考。

在 GraphQL 中建立咱们的第一个类型修改，这里全部的修改都将在这个类型中结束。 首先，在 schema.graphql文件中编写一个名为mutation 的新类型：

type Mutation {
  createUser(id: ID!, name: String!, email: String!, age: Int): User!
  updateUser(id: ID!, name: String, email: String, age: Int): User!
  deleteUser(id: ID!): User!
}

这里主要定义三个修改数据的方法：

• createUser：传入须要建立用户的 ID，name，email 和 age，它会返回一个新用户给咱们。
• updateUser：传入须要修改用户的 ID，name，email 和 age(非必传)，它会返回一个新用户给咱们。
• deleteUser: 传入须要删除用户的 ID，它会返回一个新用户给咱们。

如今，在 resolvers.js 文件并在 Query 对象下面，建立一个新的 mutation 对象，以下所示：

Mutation: {
    createUser: (parent, { id, name, email, age }, context, info) => {
      const newUser = { id, name, email, age };

      users.push(newUser);

      return newUser;
    },
    updateUser: (parent, { id, name, email, age }, context, info) => {
      let newUser = users.find(user => user.id === id);

      newUser.name = name;
      newUser.email = email;
      newUser.age = age;

      return newUser;
    },
    deleteUser: (parent, { id }, context, info) => {
      const userIndex = users.findIndex(user => user.id === id);

      if (userIndex === -1) throw new Error("User not found.");

      const deletedUsers = users.splice(userIndex, 1);

      return deletedUsers[0];
    }
  }

如今 resolvers.js 文件内容以下：

import { users } from "./db";

const resolvers = {
  Query: {
    user: (parent, { id }, context, info) => {
      return users.find(user => user.id == id);
    },
    users: (parent, args, context, info) => {
      return users;
    }
  },
  Mutation: {
    createUser: (parent, { id, name, email, age }, context, info) => {
      const newUser = { id, name, email, age };

      users.push(newUser);

      return newUser;
    },
    updateUser: (parent, { id, name, email, age }, context, info) => {
      let newUser = users.find(user => user.id === id);

      newUser.name = name;
      newUser.email = email;
      newUser.age = age;

      return newUser;
    },
    deleteUser: (parent, { id }, context, info) => {
      const userIndex = users.findIndex(user => user.id === id);

      if (userIndex === -1) throw new Error("User not found.");

      const deletedUsers = users.splice(userIndex, 1);

      return deletedUsers[0];
    }
  }
};

export default resolvers;

如今，咱们要测试咱们的 mutations 是否正常。转到localhost:4000，输入如下代码:

mutation {
  createUser(id: 3, name: "Robert", email: "robert@gmail.com", age: 21) {
    id
    name
    email
    age
  }
}

subscription (订阅)

如我以前所说，订阅是你与服务器保持实时链接的方式。这意味着不管什么时候在服务器中发生事件，而且每当调用该事件时，服务器都会将相应的数据发送到客户端。

经过订阅，你可让你的应用在不一样的用户之间保持更新。

基本订阅是这样的:（sample.graphql ）

subscription {
  users {
    id
    name
    email
    age
  }
}

你会说它很是相似于查询，是的， 但它的工做方式不一样。

当服务器中发生更新时，服务器将运行订阅中指定的 GraphQL 查询，并向客户机发送一个新更新的结果。

在这篇文章中，咱们不打算讨论订阅，可是若是你想阅读更多关于订阅的信息，请单击这里。

总结

如你所见，GraphQL 是一项很是强大的新技术。 它为咱们提供了构建更好和精心设计的API的真正能力。 这就是为何做者建议你如今开始学习它，从本文本做者的角度来讲，它最终将取代 REST。

原文：

https://medium.freecodecamp.o...

你的点赞是我持续分享好东西的动力，欢迎点赞！

交流

干货系列文章汇总以下，以为不错点个Star，欢迎 加群 互相学习。

https://github.com/qq44924588...

我是小智，公众号「大迁世界」做者，对前端技术保持学习爱好者。我会常常分享本身所学所看的干货，在进阶的路上，共勉！

关注公众号，后台回复福利，便可看到福利，你懂的。