GraphQL簡介

GraphQL是API的查詢語言,是一組服務器端運行時(以各種後端語言實現),用於執行查詢

什麼是GraphQL

GraphQL是API的新領域(應用程序編程接口)設計,以及我們如何構建和使用它們。

它是一種查詢語言,還有一組用於執行查詢的服務器端運行時(以各種後端語言實現)。它與特定技術無關,但是您可以使用任何語言來實現它。

這是一種方法與REST直接競爭代表性國家轉移)API,就像REST一樣肥皂首先。

正如我們將看到的,它與REST有很大的不同。它為API設計創建了一個全新的維度。

GraphQL原為在Facebook開發,就像最近震動JavaScript世界的許多技術一樣,反應和React Native,這是公開的launched in 2015-儘管Facebook幾年前已在內部使用它。

許多大公司正在Facebook旁邊採用GraphQL,包括GitHub,Pinterest,Twitter,Sky,《紐約時報》,Shopify,Yelp等數千種。

當GitHub決定使用該技術實現其API的v4時,我第一次與GraphQL聯繫,然後加入了他們的beta程序。從那時起,我發現它在許多方面都改變了遊戲規則。

怎麼運行的

GraphQL公開單個端點從您的服務器。

向該端點發送查詢通過使用特殊的查詢語言語法。該查詢是只是一個字符串

服務器通過提供JSON對象來響應查詢。

讓我們看看這種查詢的第一個例子。該查詢獲取具有以下名稱的人的姓名:id=1

GET /graphql?query={ person(id: "1") { name } }

or:

{
  person(id: "1") {
    name
  }
}

We’ll get this JSON response back:

{
  "name": "Tony"
}

Let’s add a bit more complexity: we get the name of the person, and the city where the person lives, by extracting it from the address object. We don’t care about other details of the address, and the server does not return them back to us because we didn’t ask for them:

GET /graphql?query={ person(id: "1") { name, address { city } } }

or

{
  person(id: "1") {
    name
    address {
      city
    }
  }
}

This is what we get back:

{
  "name": "Tony",
  "address": {
    "city": "York"
  }
}

As you can see the data we get is basically the same structure of the request we sent, filled with values that were fetched.

GraphQL Queries

In this section you’ll learn how is a GraphQL query composed.

The concepts I’ll introduce are

  • fields and arguments
  • aliases
  • fragments

Fields and arguments

Take this simple GraphQL query:

{
  person(id: "1") {
    name
  }
}

In this query you see 2 fields, person and name, and 1 argument.

The field person returns an Object which has another field in it, a String.

The argument allows us to specify which person we want to reference. We pass an id, but we could as well pass a name argument, if the API we talk to has the option to find a person by name.

Arguments are not limited to any particular field. We could have a friends field in person that lists the friends of that person, and it could have a limit argument, to specify how many we want the API to return:

{
  person(id: "1") {
    name
    friends(limit: 100)
  }
}

Aliases

You can ask the API to return a field with a different name. For example here you request the name field, but you want it returned as fullname:

{
  owner: person(id: "1") {
    fullname: name
  }
}

will return

{
  "data": {
    "owner": {
      "fullname": "Tony"
    }
  }
}

This feature, beside creating more ad-hoc naming for your client code, in case you need, is the only thing that can make the query work if you need to reference the same endpoint 2 times in the same query:

{
  owner: person(id: "1") {
    fullname: name
  }
  first_employee: person(id: "2") {
    fullname: name
  }
}

Fragments

In the above query we replicated the person structure. Fragments allow us to specify the structure just once (a very useful thing when you have many similar fields):

{
  owner: person(id: "1") {
    ...personFields
  }
  first_employee: person(id: "2") {
    ...personFields
  }
}

fragment personFields on person { fullname: name }

GraphQL Variables

More complex GraphQL queries need to use variables, a way to dynamically specify a value that is used inside a query.

In this case we added the person id as a string inside the query:

{
  owner: person(id: "1") {
    fullname: name
  }
}

The id will most probably change dynamically in our program, so we need a way to pass it, and not with string interpolation.

With variables, the same query can be written as this:

query GetOwner($id: String) {
  owner: person(id: $id) {
    fullname: name
  }
}

{ “id”: “1” }

In this snippet we have assigned the GetOwner name to our query. Think of it as named functions, while previously you had an anonymous function. Named queries are useful when you have lots of queries in your application.

The query definition with the variables looks like a function definition, and it works in an equivalent way.

Making variables required

Appending a ! to the type:

query GetOwner($id: String!)

instead of $id: String will make the $id variable required.

Specifying a default value for a variable

You can specify a default value using this syntax:

query GetOwner($id: String = "1")

GraphQL Directives

Directives let you include or exclude a field if a variable is true or false.

query GetPerson($id: String) {
  person(id: $id) {
    fullname: name,
    address: @include(if: $getAddress) {
      city
      street
      country
    }
  }
}

{ “id”: “1”, “getAddress”: false }

In this case if getAddress variable we pass is true, we also get the address field, otherwise not.

We have 2 directives available: include, which we have just seen (includes if true), and skip, which is the opposite (skips if true)

@include(if: Boolean)

query GetPerson($id: String) {
  person(id: $id) {
    fullname: name,
    address: @include(if: $getAddress) {
      city
      street
      country
    }
  }
}

{ “id”: “1”, “getAddress”: false }

@skip(if: Boolean)

query GetPerson($id: String) {
  person(id: $id) {
    fullname: name,
    address: @skip(if: $excludeAddress) {
      city
      street
      country
    }
  }
}

{ “id”: “1”, “excludeAddress”: false }


More graphql tutorials: