graphql

by Luis Aguilar

路易斯·阿吉拉爾(Luis Aguilar)

普通英語GraphQL指南 (A Guide to GraphQL in Plain English)

您需要了解的最新流行語正在席卷API開發領域。 (All you need to know about the latest buzzword that’s taking the API development scene by storm.)

TL; DR (TL;DR)

GraphQL is a query language and runtime that we can use to build and expose APIs as a strongly-typed schema instead of hundreds of REST endpoints. Your clients see the schema. They write a query for what they want. They send it over and get back exactly the data they asked for and nothing more.

GraphQL是一種查詢語言和運行時，我們可以使用它來構建API并將其顯示為強類型架構，而不是數百個REST端點。 您的客戶看到架構。 他們編寫查詢以查找所需內容。 他們將其發送出去，并準確地取回他們所要求的數據，僅此而已。

A schema looks like:

模式如下所示：

So, if a client wants a user with an ID of 2, instead of doing a GET /api/v1/users/2, they would rather send a query like this:

因此，如果客戶端希望一個ID為2的用戶，而不是執行GET /api/v1/users/2 ，他們寧愿發送如下查詢：

… and get a response like this:

……并得到這樣的回應：

Why should REST watch its back, and why should you care?

為什么應該休息看它的后面，為什么你要在乎？

1. The schema is strongly-typed. The schema dictates that the id parameter must be an integer. If a client sends user(id: “2”) instead, the GraphQL engine will reject the whole query.

   模式是強類型的。 該模式要求id參數必須為整數。 如果客戶端改為發送user(id: “2”) ，則GraphQL引擎將拒絕整個查詢。

2. Clients pick what they need. See those braces after the query parameters? That’s how our clients tell which fields they want. Fewer fields = leaner and faster responses.

   客戶選擇他們需要的東西。 查詢參數后看到那些花括號？ 這就是我們的客戶告訴他們想要哪些字段的方式。 更少的字段=更精簡和更快的響應。

3. It’s fast. Fields not picked won’t be processed, meaning less stress on the server.

   它很快。 未選擇的字段將不被處理，這將減輕服務器的壓力。

4. And most importantly, it’s flexible. If a client needs fewer fields from an endpoint, we don’t create a new endpoint or version our whole API exclusively for that need. They can pick whichever fields they need, and that’s free for us.

   最重要的是，它很靈活。 如果客戶端從端點需要的字段較少，我們不會專門為此創建新的端點或為整個API版本。 他們可以選擇所需的任何字段，這對我們來說是免費的。

And that’s all there is to it, really. No magic is going on. Just a more convenient, flexible, and natural way of building your API.

真的，這就是全部。 沒有魔術在繼續。 這是構建API的更方便，靈活，自然的方法。

But what is life without those juicy core concepts and sweet, sweet code examples?

但是，如果沒有那些多汁的核心概念和甜美，甜美的代碼示例，生活將會怎樣？

五巨頭 (The Big Five)

Before moving onto the actual fun, there are some concepts we need to have in mind, otherwise everything else won’t make any sense.

在開始實際樂趣之前，我們需要牢記一些概念，否則其他所有內容都將毫無意義。

Don’t worry—I’ll keep it short.

不用擔心，我會盡量簡短。

詢問 (Query)

A member of the schema that reads data.

讀取數據的架構成員。

突變 (Mutation)

A member of the schema that modifies data (as in create, edit, or delete.)

修改數據(如創建，編輯或刪除)的架構成員。

架構圖 (Schema)

A single-rooted tree with two primary nodes: one for queries, and another for mutations.

具有兩個主節點的單根樹：一個用于查詢，另一個用于突變。

類型 (Type)

The shape of everything composing the schema. The data returned by a query, the fields of that data, the parameters taken by a mutation, queries, and mutations themselves—everything has a type.

組成架構的所有事物的形狀。 查詢返回的數據，該數據的字段，突變所采用的參數，查詢以及突變本身—每種類型都有。

Types are composed of fields which also have a type.

類型由也具有類型的字段組成。

Both the query and mutation initial nodes are of type Query and Mutation respectively. These have more fields, users and user, and their type can also have more fields! That’s how you structure your API data into a queryable tree.

query和mutation初始節點的類型分別為Query和Mutation 。 這些具有更多字段， users和user ，并且它們的類型也可以具有更多字段！ 這就是您將API數據構造為可查詢樹的方式。

解析器 (Resolver)

The actual piece that connects your code to your schema. Resolvers are actual functions that resolve the value of a single field in a type. The following is a very, very barebones pseudo example of how it works—don’t mind it too much.

將代碼連接到架構的實際部分。 解析器是用于解析類型中單個字段值的實際函數。 以下是其工作方式的非常非常準的偽示例—不必太在意。

Easy, right? Well, that’s it for theory, time for some code!

容易吧？ 好了，理論上就是這樣，花些時間編寫代碼！

完全原始且未過度使用的代碼示例 (A Totally Original and Not Overused Code Example)

Tired of the classic user model code example? Me neither! Okay, it might be dull and uninteresting, but it serves well to illustrate the previous concepts, so let’s stick to it. By the end, we’ll have an API clients will be able to query for users, roles, and create new users.

厭倦了經典的用戶模型代碼示例？ 我也不！ 好的，它可能很枯燥和無趣，但是可以很好地說明以前的概念，所以讓我們堅持下去。 到最后，我們將擁有一個API客戶端，這些客戶端將能夠查詢用戶，角色并創建新用戶。

1.創建服務器 (1. Create a Server)

As already mentioned, GraphQL is a language, and a runtime—we still have to put it somewhere. For this example, it will live in an Express server.

如前所述，GraphQL是一種語言， 也是一種運行時，我們仍然必須將其放在某個地方。 對于此示例，它將駐留在Express服務器中。

So let’s get started:

因此，讓我們開始吧：

• Create a new folder.

  新建一個文件夾。

• Open a terminal and cd to your folder.

  打開一個終端并cd到您的文件夾。

• Run npm init && touch server.js

  運行npm init && touch server.js

• Run npm i express --save to, well, install ExpressJS.

  運行npm i express --save到ExpressJS。

• Throw this into server.js:

  扔到server.js ：

• Run the server with node server.js

  使用node server.js運行服務器

And so we have a home for our GraphQL API.

因此，我們有了GraphQL API的家。

2.添加一小撮GraphQL (2. Add a Pinch of GraphQL)

As simple as:

簡單如：

• Run npm i graphql graphql-express --save

  運行npm i graphql graphql-express --save

• Edit server.js like this:

  像這樣編輯server.js ：

And this is why it was essential to review the concepts before moving onto the code. This simple Hello World app already has a lot going on, but we can at least get an idea.

這就是為什么在移入代碼之前必須先復習這些概念的原因。 這個簡單的Hello World應用程序已經進行了很多工作，但是我們至少可以了解一下。

Don’t worry, here’s the annotated version:

別擔心，這是帶注釋的版本：

Wait, are we hardcoding our schema using a huge magic string? Don’t panic— we’ll get to that later.

等等，我們是否使用巨大的魔術字符串對模式進行硬編碼？ 不要驚慌，我們稍后再討論。

Okay, time to fire up Postman and send some queries to our GraphQL API!

好的，是時候啟動Postman并將一些查詢發送到我們的GraphQL API了！

Heh, just kidding…

嘿，開玩笑...

At line 46 we enabled GraphiQL (pronounced “graphical,”) a built-in fully-featured IDE for writing queries. Now, close Postman and go to localhost:4000/graphql in your browser of preference.

在第46行，我們啟用了GraphiQL(發音為“ graphical” )，這是一個內置的功能齊全的IDE，用于編寫查詢。 現在，關閉Postman并在您偏好的瀏覽器中轉到localhost:4000/graphql 。

What can you do with this? Well, here are some things you can try:

你能做什么呢？ 好了，您可以嘗試以下操作：

• View schema. To the right, select the Query root type to see its fields, return types, documentation, etc.

  查看架構。 在右側，選擇Query根類型以查看其字段，返回類型，文檔等。

• Write queries. To the left, type the following query, and notice how the editor shows autocompletion and documentation as you go:

  編寫查詢。 在左側，鍵入以下查詢，并注意編輯器在顯示過程中如何顯示自動完成和文檔：

• Test queries. If your query is valid, hit that play button at the top and see the results in the middle pane.

  測試查詢。 如果查詢有效，請點擊頂部的播放按鈕，然后在中間窗格中查看結果。

But what about clients? They can use GraphiQL (or a similar tool—there are tons) to build and test their queries. Then send them over using a GraphQL client like Apollo Boost—as easy as copying and pasting!

但是客戶呢？ 他們可以使用Graph i QL(或類似的工具-有很多)來構建和測試他們的查詢。 然后使用像Apollo Boost這樣的GraphQL客戶端將它們發送過來，就像復制和粘貼一樣簡單！

3.添加查詢以列出用戶 (3. Add a Query to List Users)

All right, Hello World is fine and all, but we want to do more than greeting people. Let’s add a new User type, and replace hello with users which will return all users from a dummy repository.

好的，Hello World很好，但是，我們要做的不僅僅是問候別人。 讓我們添加一個新的User類型，然后用users替換hello ，這將返回虛擬存儲庫中的所有用戶。

• Edit server.js like this:

  像這樣編輯server.js ：

• Grab the user-repository.js file from here and put it in your local directory.

  從此處獲取user-repository.js文件，并將其放在您的本地目錄中。

• Restart your server and refresh the GraphiQL editor.

  重新啟動服務器并刷新Graph i QL編輯器。

• In your query, replace hello for users { id, login } and hit play.

  在您的查詢中，為users { id, login }替換hello users { id, login }然后點擊播放。

• Profit.

  利潤。

Annotated:

注釋：

4.添加查詢以按ID獲取單個用戶 (4. Add a Query to Get a Single User By ID)

By now, you might be asking: if queries are also fields of a type, why not call them fields? What makes them different?

現在，您可能會問：如果查詢也是一種類型的字段，為什么不將它們稱為字段？ 是什么使它們與眾不同？

Queries can take parameters and use a resolver.

查詢可以采用參數并使用解析器。

The easiest way to see it is to compare it to OOP classes. While classes have fields and functions, GraphQL types have fields and queries.

最簡單的查看方法是將其與OOP類進行比較。 雖然類具有字段和函數，但是GraphQL類型具有字段和查詢。

• Edit server.js with:

  使用以下命令編輯server.js ：

Again, no magic.

再次，沒有魔術。

We’re saying the user query takes an id parameter, and that’s what its resolver function will take. Oh, also notice the ! sign meaning the parameter is required—GraphQL will make sure it is provided.

我們說的是user查詢使用id參數，這就是它的解析器函數所采用的參數。 呵呵，還注意了! 符號表示該參數是必需的-GraphQL將確保已提供該參數。

5.用手動定義替換Schema Builder (5. Replace Schema Builder with Manual Definitions)

Remember how we called out that huge magic string we used to define our schema? Well, it’s time to fix that.

還記得我們如何調出用來定義架構的巨大魔術字符串嗎？ 好了，是時候解決這個問題了。

Okay, in a real-world app, you would put your schema in separate *.graphql files. Then you can add syntax highlighting and code completion plugins to your code editor. However, manual definitions offers a better integration with the rest of our code. Check out this article for more info.

好的，在真實世界的應用程序中，您可以將架構放在單獨的*.graphql文件中。 然后，您可以將語法高亮和代碼完成插件添加到代碼編輯器中。 但是，手動定義可以與我們的其余代碼更好地集成。 查看這篇文章以獲取更多信息。

For this step, we’ll use the specialized classes and helpers provided by GraphQL:

在此步驟中，我們將使用GraphQL提供的專用類和幫助器：

Done? Okay, now annotated:

做完了嗎 好的，現在注釋：

This way we can put our type definitions in separate files to better organize our server code!

這樣，我們可以將類型定義放在單獨的文件中，以更好地組織服務器代碼！

As pointed out in the example, in this notation, the resolver function takes the following parameters:

如示例中指出的那樣，在這種表示法中，resolver函數采用以下參數：

• root—the resolved parent object, in this case the user.

  root -解析的父對象，在這種情況下，用戶。

• args—arguments passed by the query.

  args -參數被查詢過。

• context, info—out of the scope of this guide.

  context ， info －在本指南的范圍之外。

6.添加用于獲取用戶角色的子查詢 (6. Add a Sub-query for Fetching User Roles)

So far, we’ve learned to define basic queries. Time to turn it up a notch! Let’s add a new field to the User type for its assigned roles. In a traditional architecture, we’d be tempted to create a new query like userRoles(userId: Int!): Role and call it a day. But that’s not how things work in GraphQL!

到目前為止，我們已經學會了定義基本查詢。 是時候提高它了！ 讓我們在“ User類型”中為其分配的角色添加一個新字段。 在傳統的體系結構中，我們很想創建一個新的查詢，例如userRoles(userId: Int!): Role并稱之為一天。 但這不是GraphQL的工作原理！

We have to think in graphs.

我們必須考慮圖表 。

In the language of graphs, to get the roles of a user we’d send a query like this:

用圖的語言，要獲得用戶的角色，我們將發送如下查詢：

… and get a JSON result like this:

…并獲得如下的JSON結果：

Makes sense, right? Let’s go ahead and modify the schema.

有道理吧？ 讓我們繼續修改模式。

• Edit server.js with:

  使用以下命令編輯server.js ：

There—we can fetch user roles now. Notice how we used the User instance passed as the first parameter to the resolver to get the ID from the parent resolved user.

在那里-我們現在可以獲取用戶角色。 請注意，我們如何使用作為第一個參數傳遞給解析器的User實例從父解析用戶獲取ID。

The advantage of subqueries? GraphQL won’t resolve the roles field unless it’s selected in the query.

子查詢的優勢？ 除非在查詢中選擇GraphQL，否則GraphQL不會解析roles字段。

Did you spot the pitfall with the last bit of code?

您是否發現了最后一部分代碼的隱患？

If we query 100 users and their roles, the roles resolver function will execute a hundred times. Then, let’s say each user has 10 roles and each role has a sub-query field. That query will execute 100 * 10 times.

如果我們查詢100個用戶及其角色，則roles解析器功能將執行一百次。 然后，假設每個用戶有10個角色，每個角色都有一個子查詢字段。 該查詢將執行100 * 10次。

This is called The N + 1 Problem.

這稱為N + 1問題 。

Finding out how to fix that is your homework! But it’s dangerous to go alone, so take this:

找出解決方法，這是您的作業！ 但是獨自一人走是危險的，因此請采取以下措施：

Avoiding n+1 requests in GraphQL, including within subscriptionsNote: this article will not make much sense unless you know the basics of GraphQL, an awesome technology we use at…medium.com

避免在GraphQL中出現n + 1個請求，包括在訂閱中。 注意：除非您了解GraphQL的基礎知識，否則本文將沒有多大意義，GraphQL是我們在… medium.com上使用的一種很棒的技術

7.添加一個變體來創建一個新用戶 (7. Add a Mutation to Create a New User)

As mentioned before, mutations are how we change data in our schema. If we want to create, edit, or delete a user account, we’ll need a mutation for that.

如前所述， 變異是我們更改架構數據的方式。 如果我們要創建，編輯或刪除用戶帳戶，則需要對其進行更改。

Mutations are defined almost exactly the same as a query, and often return the affected data. So the only difference between them is merely logical?

定義的突變與查詢幾乎完全相同，并且通常返回受影響的數據。 因此，它們之間的唯一區別僅僅是合乎邏輯的嗎？

Exactly.

究竟。

As mentioned before, queries can also take parameters. They only return data.

如前所述，查詢也可以采用參數。 它們僅返回數據。

• Edit server.js with:

  使用以下命令編輯server.js ：

• Send the following query from GraphiQL:

  從Graph i QL發送以下查詢：

• Profit.

  利潤。

結論 (Conclusion)

So, hopefully, the basics of GraphQL are clear: setting up a server, creating a schema (in plain and complex notation) with types, queries, and mutations. I used quite a basic example. Hopefully it served well for illustrating every concept unobtrusively.

因此，希望GraphQL的基本知識很清楚：設置服務器，使用類型，查詢和變異創建模式(以簡單和復雜的符號表示)。 我用了一個很基本的例子。 希望它能很好地說明每個概念。

From this point onwards, it’s up to you to expand the example with more stuff. Or you can create a completely new codebase for another use case.

從現在開始，由您自己來擴展更多內容的示例。 或者，您可以為另一個用例創建一個全新的代碼庫。

To get you going, here are a few things you can try out:

為了助您一臂之力，您可以嘗試以下一些操作：

• Solving the N+1 problem by implementing data loaders.

  通過實現數據加載器解決N + 1問題。

• Create mutations for validating user credentials, managing user roles, and more.

  創建用于驗證用戶憑據，管理用戶角色等的變體。

• Add an actual database to feed your resolvers (MySQL, SQLite, etc.)

  添加實際的數據庫以供解析器使用(MySQL，SQLite等)

• Use an authentication backend like OAuth to validate users.

  使用OAuth之類的身份驗證后端來驗證用戶。

• Create a simple client app that uses the Apollo Boost client to connect to your server.

  創建一個使用Apollo Boost客戶端連接到服務器的簡單客戶端應用程序。

• Rebuild the example with TypeScript.

  用TypeScript重建示例。

Possibilities are endless!

可能性是無止境的！

獲取源代碼 (Get the Source Code)

The entire example is hosted in GitHub. Browse through the tags to see a gradual progression of the code.

整個示例托管在GitHub中。 瀏覽標簽以查看代碼的逐步進展。

ldiego08/workshops-graphqlGitHub is where people build software. More than 28 million people use GitHub to discover, fork, and contribute to over…github.com

ldiego08 / workshops-graphql 人們可以在GitHub上構建軟件。 超過2千8百萬的人使用GitHub來發現，發掘和貢獻超過 github.com

Got questions, comments, or anything you’d like to share? Find me on Twitter as @ldiego08. Also, don’t forget to ?, share, and follow if this post was helpful!

有問題，評論或您想分享的任何內容？ 在Twitter上以@ ldiego08找到我。 此外，如果這篇文章對您有幫助，請不要忘記分享，關注！

Luis Aguilar (@ldiego08) | TwitterSan José, Costa Rica — Writer of sci-fi, software dev @skillshare. twitter.com

路易斯·阿吉拉(Luis Aguilar)(@ ldiego08)| Twitter 哥斯達黎加的SanJosé，科幻作家，軟件開發人員@skillshare。 twitter.com

翻譯自: https://www.freecodecamp.org/news/a-beginners-guide-to-graphql-60e43b0a41f5/

graphql

總結

以上是生活随笔為你收集整理的graphql_普通英语GraphQL指南的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。