Введение в GraphQL

GraphQL - это язык запросов для нашего API и среда выполнения на стороне сервера для выполнения запросов с использованием системы типов для наших данных.

В этой статье мы рассмотрим, как делать простые запросы к GraphQL API.

Определение API

Мы определяем API, определяя типы и поля для этих типов, и предоставляем функции для каждого поля каждого типа.

Например, если у нас есть следующий тип:

type Query {
  person: Person
}

Затем мы должны создать функцию для соответствующего типа, чтобы возвращать данные:

function Query_person(request) {
  return request.person;
}

Выполнение запросов

После запуска службы GraphQL мы можем отправлять запросы GraphQL для проверки и выполнения на сервере.

Например, мы можем сделать следующий запрос:

{
  person {
    firstName
  }
}

Тогда мы можем получить такой JSON:

{
  "person": {
    "firstName": "Joe"
  }
}

Запросы и мутации

Запросы предназначены для получения данных с сервера GraphQL, а мутации используются для управления данными, хранящимися на сервере.

Например, следующий запрос на получение имени человека:

{
  person {
    name
  }
}

Тогда мы можем получить с сервера следующий JSON:

{
  "data": {
    "person": {
      "name": "Joe"
    }
  }
}

Поле name возвращает тип String.

Мы можем изменить запрос по своему усмотрению, если хотим получить больше данных. Например, если мы напишем такой запрос:

{
  person {
    name
    friends {
      name
    }
  }
}

Тогда в ответ мы можем получить что-то вроде следующего:

{
  "data": {
    "person": {
      "name": "Joe",
      "friends": [
        {
          "name": "Jane"
        },
        {
          "name": "John"
        }
      ]
    }
  }
}

В приведенном выше примере friends является массивом. С точки зрения запроса они выглядят одинаково, но сервер знает, что вернуть, в зависимости от указанного типа.

Аргументы

Мы можем передавать аргументы запросам и изменениям. Мы можем сделать намного больше с запросами, если передадим ему аргументы.

Например, мы можем передать аргумент следующим образом:

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

Тогда получаем что-то вроде:

{
  "data": {
    "person": {
      "name": "Luke"
    }
  }
}

с сервера.

С GraphQL мы можем передавать аргументы вложенным объектам. Например, мы можем написать:

{
  person(id: "1000") {
    name
    height(unit: METER)
  }
}

Тогда мы можем получить такой ответ:

{
  "data": {
    "person": {
      "name": "Luke",
      "height": 1.9
    }
  }
}

В этом примере поле height имеет unit, который является типом перечисления, представляющим конечный набор значений.

unit может быть МЕТРА или НОГА.

Фрагменты

Мы можем определять фрагменты, чтобы мы могли повторно использовать сложные запросы.

Например, мы можем определить фрагмент и использовать его следующим образом:

{
  leftComparison: person(episode: FOO) {
    ...comparisonFields
  }
  rightComparison: person(episode: BAR) {
    ...comparisonFields
  }
}
​
fragment comparisonFields on Character {
  name
  appearsIn
  friends {
    name
  }
}

В приведенном выше коде мы определили фрагмент comparisonFields, содержащий список полей, которые мы хотим включить в каждый запрос.

Затем у нас есть запросы leftComparison и rightComparison, которые включают поля фрагмента comparisonFields с помощью оператора ....

Тогда получаем что-то вроде:

{
  "data": {
    "leftComparison": {
      "name": "Luke",
      "appearsIn": [
        "FOO",
        "BAR"
      ],
      "friends": [
        {
          "name": "Jane"
        },
        {
          "name": "John"
        }
      ]
    },
    "rightComparison": {
      "name": "Mary",
      "appearsIn": [
        "FOO",
        "BAR"
      ],
      "friends": [
        {
          "name": "Mary"
        },
        {
          "name": "Alex"
        }
      ]
    }
  }
}

Использование переменных внутри фрагментов

Мы можем передавать переменные во фрагменты следующим образом:

query PersonComparison($first: Int = 3){
  leftComparison: person(episode: FOO) {
    ...comparisonFields
  }
  rightComparison: person(episode: BAR) {
    ...comparisonFields
  }
}
​
fragment comparisonFields on Character {
  name
  appearsIn
  friends(first: $first) {
    name
  }
}

Тогда мы можем получить что-то вроде:

{
  "data": {
    "leftComparison": {
      "name": "Luke",
      "appearsIn": [
        "FOO",
        "BAR"
      ],
      "friends": [
        {
          "name": "Jane"
        },
        {
          "name": "John"
        }
      ]
    },
    "rightComparison": {
      "name": "Mary",
      "appearsIn": [
        "FOO",
        "BAR"
      ],
      "friends": [
        {
          "name": "Mary"
        },
        {
          "name": "Alex"
        }
      ]
    }
  }
}

как ответ.

Тип операции может быть запросом, изменением или подпиской и описывает, какой оператор мы собираемся делать. Это необходимо, если мы не используем сокращенный синтаксис запроса. В этом случае мы не можем предоставить имя или определение переменной для нашей операции.

Имя операции - это понятное и явное имя для нашей операции. Это требуется в многооперационных документах. Но его использование приветствуется, поскольку оно полезно для отладки и ведения журналов на стороне сервера.

Операцию легко идентифицировать по имени.

Заключение

GraphQL - это язык запросов, который позволяет нам отправлять запросы на сервер в понятной форме. Он работает, отправляя на сервер вложенные объекты с типом и именем операции вместе с любыми переменными.

Затем сервер вернет нам ответ, который мы ищем.

Типы операций включают запросы на получение данных и изменения для внесения изменений в данные на сервере.