graphql入门

by Leonardo Maldonado

莱昂纳多·马尔多纳多(Leonardo Maldonado)

GraphQL入门指南 (A Beginner’s Guide to GraphQL)

One of the most commonly discussed terms today is the API. A lot of people don’t know exactly what an API is. Basically, API stands for Application Programming Interface. It is, as the name says, an interface with which people — developers, users, consumers — can interact with data.

API是当今最常用的术语之一。很多人不确切知道什么是API。 API基本上代表应用程序编程接口。 顾名思义，它是人们(开发人员，用户，消费者)可以与数据进行交互的接口。

You can think of an API as a bartender. You ask the bartender for a drink, and they give you what you wanted. Simple. So why is that a problem?

您可以将API视为调酒师。您要求酒保喝一杯，他们会给您您想要的。简单。那为什么会有问题呢？

Since the start of the modern web, building APIs has not been as hard as it sounds. But learning and understanding APIs was. Developers form the majority of the people that will use your API to build something or just consume data. So your API should be as clean and as intuitive as possible. A well-designed API is very easy to use and learn. It’s also intuitive, a good point to keep in mind when you’re starting to design your API.

自从现代网络开始以来，构建API并不像听起来那样困难。但是学习和理解API却是。开发人员构成将使用您的API来构建某些东西或仅使用数据的大多数人。因此，您的API应该尽可能简洁明了。精心设计的API非常易于使用和学习。它也很直观，这是在开始设计API时要牢记的一个好点。

We’ve been using REST to build APIs for a long time. Along with that comes some problems. When building an API using REST design, you’ll face some problems like:

长期以来，我们一直在使用REST来构建API。随之而来的是一些问题。使用REST设计构建API时，您会遇到一些问题，例如：

1) you’ll have a lot of endpoints

1)您将有很多端点

2) it’ll be much harder for developers to learn and understand your API

2)开发人员将很难学习和理解您的API

3) there is over- and under-fetching of information

3)信息获取过多和不足

To solve these problems, Facebook created GraphQL. Today, I think GraphQL is the best way to build APIs. This article will tell you why you should start to learn it today.

为了解决这些问题，Facebook创建了GraphQL。今天，我认为GraphQL是构建API的最佳方法。本文将告诉您为什么今天应该开始学习它。

In this article, you’re going to learn how GraphQL works. I’m going to show you how to create a very well-designed, efficient, powerful API using GraphQL.

在本文中，您将学习GraphQL的工作方式。我将向您展示如何使用GraphQL创建一个设计良好，高效，强大的API。

You’ve probably already heard about GraphQL, as a lot of people and companies are using it. Since GraphQL is open-source, its community has grown huge.

您可能已经听说过GraphQL，因为许多人和公司正在使用它。由于GraphQL是开源的，因此其社区已经变得庞大。

Now, it’s time for you start to learn in practice how GraphQL works and all about its magic.

现在，是时候开始在实践中学习GraphQL的工作原理以及其神奇之处了。

什么是GraphQL？ (What is GraphQL?)

GraphQL is an open-source query language developed by Facebook. It provides us with a more efficient way design, create, and consume our APIs. Basically, it’s the replacement for REST.

GraphQL是Facebook开发的一种开源查询语言。它为我们提供了一种更有效的方式来设计，创建和使用我们的API。基本上，它是REST的替代品。

GraphQL has a lot of features, like:

GraphQL具有很多功能，例如：

You write the data that you want, and you get exactly the data that you want. No more over-fetching of information as we are used to with REST.

您写入所需的数据，并且您将确切获得所需的数据。不再像过去使用REST那样过度获取信息 。
It gives us a single endpoint, no more version 2 or version 3 for the same API.

它为我们提供了一个终结点 ，对于同一API，不再有版本2或版本3。
GraphQL is strongly-typed, and with that you can validate a query within the GraphQL type system before execution. It helps us build more powerful APIs.

GraphQL是强类型的 ，使用它可以在执行之前在GraphQL类型系统内验证查询。它可以帮助我们构建更强大的API。

This is a basic introduction to GraphQL — why it’s so powerful and why it’s gaining a lot of popularity these days. If you want to learn more about it, I recommend you to go the GraphQL website and check it out.

这是对GraphQL的基本介绍-为什么它如此强大，以及为什么它如今越来越受欢迎。如果您想了解更多信息，建议您访问GraphQL网站并进行检查。

入门 (Getting started)

The main objective in this article is not to learn how to set up a GraphQL server, so we’re not getting deep into that for now. The objective is to learn how GraphQL works in practice, so we’re gonna use a zero-configuration GraphQL server called ☄️ Graphpack.

本文的主要目的不是学习如何设置GraphQL服务器，因此我们暂时不对此进行深入研究。我们的目标是学习GraphQL如何在实践中，所以我们要使用一种叫做☄️零配置GraphQL服务器Graphpack 。

To start our project, we’re going to create a new folder and you can name it whatever you want. I’m going to name it graphql-server:

要开始我们的项目，我们将创建一个新文件夹，您可以根据需要命名它。我将其命名为graphql-server ：

Open your terminal and type:

打开您的终端并输入：

mkdir graphql-server

Now, you should have npm or yarn installed in your machine. If you don’t know what these are, npm and yarn are package managers for the JavaScript programming language. For Node.js, the default package manager is npm.

现在，您应该在机器中安装了npm或yarn 。如果您不知道这些是什么，则npm和yarn是JavaScript编程语言的包管理器。对于Node.js，默认的软件包管理器是npm 。

Inside your created folder type the following command:

在创建的文件夹中，键入以下命令：

npm init -y

Or if you use yarn:

或者，如果您使用纱线：

yarn init

npm will create a package.json file for you, and all the dependencies that you installed and your commands will be there.

npm将为您创建一个package.json文件，所有已安装的依赖项和命令都将存在。

So now, we’re going to install the only dependency that we’re going to use.

因此，现在，我们将安装将要使用的唯一依赖项 。

☄️Graphpack lets you create a GraphQL server with zero configuration. Since we’re just starting with GraphQL, this will help us a lot to go on and learn more without getting worried about a server configuration.

☄️ Graphpack可以让你创建一个GraphQL 服务器零配置 。由于我们只是从GraphQL开始，因此这将帮助我们继续学习并了解更多信息，而不必担心服务器配置。

In your terminal, inside your root folder, install it like this:

在终端的根文件夹中，按以下方式安装：

npm install --save-dev graphpack

Or, if you use yarn, you should go like this:

或者，如果您使用毛线，则应如下所示：

yarn add --dev graphpack

After Graphpack is installed, go to our scripts in package.json file, and put the following code there:

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

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

We’re going to create a folder called src, and it’s going to be the only folder in our entire server.

我们将创建一个名为src的文件夹，它将是整个服务器中唯一的文件夹。

Create a folder called src, after that, inside our folder, we’re going to create three files only.

创建一个名为src的文件夹，然后在我们的文件夹内，仅创建三个文件。

Inside our src folder create a file called schema.graphql. Inside this first file, put the following code:

在我们的src文件夹中，创建一个名为schema.graphql的文件。在第一个文件中，放入以下代码：

type Query {hello: String
}

In this schema.graphql file is going to be our entire GraphQL schema. If you don’t know what it is, I’ll explain later — don't worry.

在这个schema.graphql文件schema.graphql成为我们的整个GraphQL模式。如果您不知道它是什么，我待会儿解释-不用担心。

Now, inside our src folder, create a second file. Call it resolvers.js and, inside this second file, put the following code:

现在，在我们的src文件夹中，创建另一个文件。将其resolvers.js并在第二个文件中放入以下代码：

import { users } from "./db";const resolvers = {Query: {hello: () => "Hello World!"}
};export default resolvers;

This resolvers.js file is going to be the way we provide the instructions for turning a GraphQL operation into data.

此resolvers.js文件将成为我们提供的将GraphQL操作转换为数据的说明的方式。

And finally, inside your src folder, create a third file. Call this db.js and, inside this third file, put the following code:

最后，在您的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 }
];

In this tutorial we’re not using a real-world database. So this db.js file is going to simulate a database, just for learning purposes.

在本教程中，我们不使用真实数据库。因此，此db.js文件将用于模拟数据库，仅用于学习目的。

Now our src folder should look like this:

现在，我们的src文件夹应如下所示：

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

Now, if you run the command npm run dev or, if you’re using yarn, yarn dev, you should see this output in your terminal:

现在，如果您运行命令npm run dev或者如果您使用的是yarn， yarn dev ，那么您应该在终端中看到以下输出：

You can now go to localhost:4000 . This means that we’re ready to go and start writing our first queries, mutations, and subscriptions in GraphQL.

您现在可以转到localhost:4000 。这意味着我们已经准备好开始在GraphQL中编写我们的第一个查询，变异和订阅。

You see the GraphQL Playground, a powerful GraphQL IDE for better development workflows. If you want to learn more about GraphQL Playground, click here.

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

架构图 (Schema)

GraphQL has its own type of language that’s used to write schemas. This is a human-readable schema syntax called Schema Definition Language (SDL). The SDL will be the same, no matter what technology you’re using — you can use this with any language or framework that you want.

GraphQL有自己的语言类型，用于编写模式。这是一种人类可读的架构语法，称为架构定义语言(SDL)。无论您使用哪种技术，SDL都是相同的-您可以将其与所需的任何语言或框架一起使用。

This schema language its very helpful because it’s simple to understand what types your API is going to have. You can understand it just by looking right it.

这种模式语言非常有用，因为它很容易理解您的API将要具有的类型。您可以通过正确查看它来理解它。

种类 (Types)

Types are one of the most important features of GraphQL. Types are custom objects that represent how your API is going to look. For example, if you’re building a social media application, your API should have types such as Posts, Users, Likes, Groups.

类型是GraphQL的最重要功能之一。类型是自定义对象，代表您的API外观。例如，如果您正在构建社交媒体应用程序，则您的API应该具有诸如Posts ， Users ， Likes ， Groups类的类型。

Types have fields, and these fields return a specific type of data. For example, we’re going to create a User type, we should have some name, email, and age fields. Type fields can be anything, and always return a type of data as Int, Float, String, Boolean, ID, a List of Object Types, or Custom Objects Types.

类型具有字段，并且这些字段返回特定类型的数据。例如，我们要创建一个User类型，我们应该有一些name ， email和age字段。类型字段可以是任何内容，并且总是返回数据类型，例如Int，Float，String，Boolean，ID，Object Types列表或Custom Objects Types 。

So now to write our first Type, go to your schema.graphql file and replace the type Query that is already there with the following:

因此，现在要编写我们的第一个Type，请转到您的schema.graphql文件，并用以下内容替换已经存在的Query类型：

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

Each User is going to have an ID, so we gave it an ID type. User is also going to have a name and email, so we gave it a String type, and an age, which we gave an Int type. Pretty simple, right?

每个User都有一个ID ，因此我们给了它一个ID类型。 User还将具有name和email ，因此我们给了它一个String类型，一个age ，我们给了一个Int类型。很简单，对吧？

But, what about those ! at the end of every line? The exclamation point means that the fields are non-nullable, which means that every field must return some data in each query. The only nullable field that we’re going to have in our User type will be age.

但是，那些! 在每一行的末尾？感叹号表示字段不可为空 ，这意味着每个字段必须在每个查询中返回一些数据。我们将在User类型中唯一拥有的null字段将是age 。

In GraphQL, you will deal with three main concepts:

在GraphQL中，您将处理三个主要概念：

queries — the way you’re going to get data from the server.

查询 -您将从服务器获取数据的方式。
mutations — the way you’re going to modify data on the server and get updated data back (create, update, delete).

突变 -修改服务器上的数据并取回更新的数据(创建，更新，删除)的方式。
subscriptions — the way you’re going to maintain a real-time connection with the server.

订阅 -与服务器保持实时连接的方式。

I’m going to explain all of them to you. Let’s start with Queries.

我将向您解释所有这些内容。让我们从查询开始。

查询 (Queries)

To explain this in a simple way, queries in GraphQL are how you’re going to get data. One of the most beautiful things about queries in GraphQL is that you are just going to get the exact data that you want. No more, no less. This has a huge positive impact in our API — no more over-fetching or under-fetching information as we had with REST APIs.

为了以一种简单的方式说明这一点，GraphQL中的查询是您如何获取数据的方式。 GraphQL中关于查询的最美丽的事情之一就是您将获得所需的确切数据。不多不少。这对我们的API产生了巨大的积极影响-不再像我们使用REST API那样过度获取或不足获取信息。

We’re going to create our first type Query in GraphQL. All our queries will end up inside this type. So to start, we’ll go to our schema.graphql and write a new type called Query:

我们将在GraphQL中创建第一个类型的查询。我们所有的查询都将以这种类型结束。首先，我们将转到schema.graphql并编写一个名为Query的新类型：

type Query {users: [User!]!
}

It’s very simple: the users query will return to us an array of one or more Users. It will not return null, because we put in the ! , which means it’s a non-nullable query. It should always return something.

很简单： users 查询将返回给我们一个包含一个或多个Users的数组。它不会返回null，因为我们输入了! ，这意味着它是一个不可为空的查询。它应该总是返回一些东西。

But we could also return a specific user. For that we’re going to create a new query called user. Inside our Query type, put the following code:

但是我们也可以返回特定的用户。为此，我们将创建一个名为user的新查询。在我们的Query类型中，放入以下代码：

user(id: ID!): User!

Now our Query type should look like this:

现在，我们的Query类型应如下所示：

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

As you see, with queries in GraphQL we can also pass arguments. In this case, to query for a specific user, we’re going to pass its ID.

如您所见，通过GraphQL中的查询，我们还可以传递参数。在这种情况下，要查询特定user ，我们将传递其ID 。

But, you may be wondering: how does GraphQL know where get the data? That’s why we should have a resolvers.js file. That file tells GraphQL how and where it's going to fetch the data.

但是，您可能想知道：GraphQL如何知道从何处获取数据？这就是为什么我们应该有一个resolvers.js文件的原因。该文件告诉GraphQL如何以及在何处获取数据。

First, go to our resolvers.js file and import the db.js that we just created a few moments ago. Your resolvers.js file should look like this:

首先，转到我们的resolvers.js文件，并导入我们刚才创建的db.js 您的resolvers.js文件应如下所示：

import { users } from "./db";const resolvers = {Query: {hello: () => "Hello World!"}
};export default resolvers;

Now, we’re going to create our first Query. Go to your resolvers.js file and replace the hello function. Now your Query type should look like this:

现在，我们将创建第一个查询。转到您的resolvers.js文件，并替换hello函数。现在，您的查询类型应如下所示：

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;

Now, to explain how is it going to work:

现在，解释一下它是如何工作的：

Each query resolver has four arguments. In the user function, we’re going to pass id as an argument, and then return the specific user that matches the passed id. Pretty simple.

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

In the users function, we’re just going to return the users array that already exists. It’ll always return to us all of our users.

在users函数中，我们将返回已经存在的users数组。它将始终返回给我们所有用户。

Now, we’re going to test if our queries are working fine. Go to localhost:4000 and put in the following code:

现在，我们将测试查询是否工作正常。转到localhost:4000并输入以下代码：

query {users {idnameemailage}
}

It should return to you all of our users.

它应该返回给我们所有的用户。

Or, if you want to return a specific user:

或者，如果您想返回特定用户：

query {user(id: 1) {idnameemailage}
}

Now, we’re going to start learning about mutations, one of the most important features in GraphQL.

现在，我们将开始学习有关突变的知识 ，这是GraphQL中最重要的功能之一。

变异 (Mutations)

In GraphQL, mutations are the way you’re going to modify data on the server and get updated data back. You can think like the CUD (Create, Update, Delete) of REST.

在GraphQL中，变异是您将要修改服务器上的数据并取回更新的数据的方式。您可以想到REST的CUD(创建，更新，删除)。

We’re going to create our first type mutation in GraphQL, and all our mutations will end up inside this type. So, to start, go to our schema.graphql and write a new type called mutation:

我们将在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!
}

As you can see, we’re going to have three mutations:

如您所见，我们将进行三个突变：

createUser: we should pass an ID, name, email, and age. It should return a new user to us.

createUser ：我们应该传递一个ID ， name ， email和age 。它应该将一个新用户返回给我们。

updateUser: we should pass an ID, and a new name, email, or age. It should return a new user to us.

updateUser ：我们应该传递一个ID ，以及一个新name ， email或age 。它应该将一个新用户返回给我们。

deleteUser: we should pass an ID. It should return a new user to us.

deleteUser ：我们应该传递一个ID. 它应该将一个新用户返回给我们。

Now, go to our resolvers.js file and below the Query object, create a new mutation object like this:

现在，转到我们的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];}}

Now, our resolvers.js file should look like this:

现在，我们的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;

Now, we’re going to test if our mutations are working fine. Go to localhost:4000 and put in the following code:

现在，我们将测试我们的突变是否工作正常。转到localhost:4000并输入以下代码：

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

It should return a new user to you. If you want to try making new mutations, I recommend you to try for yourself! Try to delete this same user that you created to see if it’s working fine.

它应该返回一个新用户。如果您想尝试进行新的突变，建议您自己尝试！尝试删除与您创建的同一用户，以查看其是否正常运行。

Finally, we’re going to start learning about subscriptions, and why they are so powerful.

最后，我们将开始学习订阅，以及订阅为何如此强大。

订阅内容 (Subscriptions)

As I said before, subscriptions are the way you’re going to maintain a real-time connection with a server. That means that whenever an event occurs in the server and whenever that event is called, the server will send the corresponding data to the client.

如前所述，订阅是您与服务器保持实时连接的方式。这意味着，每当服务器中发生事件并调用该事件时，服务器便会将相应的数据发送到客户端。

By working with subscriptions, you can keep your app updated to the latest changes between different users.

通过使用订阅，您可以使您的应用程序更新为不同用户之间的最新更改。

A basic subscription is like this:

基本订阅是这样的：

subscription {users {idnameemailage}
}

You will say it’s very similar to a query, and yes it is. But it works differently.

您会说它与查询非常相似，是的。但是它的工作方式不同。

When something is updated in the server, the server will run the GraphQL query specified in the subscription, and send a newly updated result to the client.

服务器中的某些内容更新后，服务器将运行订阅中指定的GraphQL查询，并将新更新的结果发送给客户端。

We’re not going to work with subscriptions in this specific article, but if you want to read more about them click here.

在此特定文章中，我们将不使用订阅，但是，如果您想了解有关订阅的更多信息，请单击此处。

结论 (Conclusion)

As you have seen, GraphQL is a new technology that is really powerful. It gives us real power to build better and well-designed APIs. That’s why I recommend you start to learn it now. For me, it will eventually replace REST.

如您所见，GraphQL是一项非常强大的新技术。它为我们提供了构建更好的和精心设计的API的真正能力。因此，我建议您立即开始学习。对我来说，它将最终取代REST。

Thanks for reading the article.

感谢您阅读本文。

Follow me on Twitter! Follow me on GitHub!

在推特上关注我！ 在GitHub上关注我！

I’m looking for a remote opportunity, so if have any I’d love to hear about it, so please contact me at my Twitter!

我正在寻找机会，因此，如果有任何我想听到的机会，请通过Twitter与我联系！

翻译自: https://www.freecodecamp.org/news/a-beginners-guide-to-graphql-86f849ce1bec/