Книга «GraphQL: язык запросов для современных веб-приложений»

Привет, Хаброжители! У нас вышла книга по языку запросов GraphQL. Мы решили поделиться переводом главы «Анатомия запросов GraphQL»

«Снежный клык» (Snowtooth) — выдуманный горнолыжный курорт. Ради примеров в данной главе мы сделаем вид, что это настоящая гора и мы там работаем. Мы рассмотрим, как веб-команда «Снежного клыка» использует GraphQL для предоставления информации в режиме реального времени: сведений о состоянии подъемников и лыжных трасс. Лыжный патруль «Снежного клыка» может открывать и закрывать подъемники и трассы непосредственно со смартфона. Чтобы следовать примерам в этой главе, обратитесь к интерфейсу «Снежного клыка» на платформе GraphQL Playground (snowtooth.moonhighway.com/).


Вы можете использовать операцию query для запроса данных из API. Запрос описывает данные, которые вы хотите получить от сервера GraphQL. Когда вы отправляете запрос, вы запрашиваете единицы данных по полям. Эти поля отображаются в том же поле в ответе данных в формате JSON, который вы получаете с сервера. Например, если вы отправляете запрос allLifts и запрашиваете поля name и status, вы должны получить ответ в формате JSON, содержащий массив allLifts и строки name и status каждого подъемника, как показано здесь:

query {
    allLifts {
       name
       status
    }
}

Обработка ошибок
Успешные запросы возвращают JSON-документ, содержащий ключ «данные». Неудачные запросы возвращают JSON-документ, содержащий ключ «ошибки». Детали того, что пошло не так, передаются в виде данных в формате JSON под этим ключом. Ответ JSON может содержать как «данные», так и «ошибки».

Вы можете добавить несколько запросов к документу запроса, но одновременно можно инициировать только одну операцию. Например, вы можете разместить две операции запроса в документе запроса:

query lifts {
    allLifts {
      name
      status
    }
}

query trails {
    allTrails {
      name
      difficulty
     }
}

Когда вы нажмете кнопку воспроизведения, среда GraphQL Playground предложит вам выбрать одну из этих двух операций.

Если требуется отправить один запрос всех указанных данных, вам нужно поместить все в один и тот же запрос:

query liftsAndTrails {
    liftCount(status: OPEN)
    allLifts {
      name
      status
    }
    allTrails {
       name
       difficulty
    }
}

Здесь налицо преимущества GraphQL. Мы можем получать разные типы данных в одном запросе. Мы запрашиваем liftCount по статусу, который позволяет нам узнать количество подъемников, имеющих в настоящее время этот статус. Мы также запрашиваем name и status каждого подъемника. Наконец, мы запрашиваем name и status каждой трассы.

query — это тип GraphQL. Мы называем его корневым типом, потому что это тип, который сопоставляется с операцией, а операции представляют собой корни нашего документа запроса. Поля, доступные для запроса в API GraphQL, определены в данной схеме API. В документации указывается, какие поля доступны для выбора в типе query.

Документация указывает нам, что мы можем выбирать поля liftCount, allLifts и allTrails при запросе этого API. Она также определяет больше полей, которые доступны для выбора, но весь смысл запроса заключается в том, что мы можем выбрать, какие поля нам нужны, а какие необходимо опустить.

Когда мы пишем запросы, мы выбираем поля, которые нам нужны, заключая их в фигурные скобки. Эти блоки называются выборками. Поля, которые мы определяем в выборке, напрямую связаны с типами GraphQL. Поля liftCount, allLifts и allTrails определены в типе query.

Вы можете встраивать множество выборок одну в другую. Поскольку поле allLifts возвращает список Lift, нам нужно использовать фигурные скобки для создания новой выборки для этого типа. Есть все виды данных, которые мы можем запросить о подъемнике, но в указанном примере нам нужны только name и status подъемника. Аналогично запрос allTrails будет возвращать типы Trail.

Ответ в формате JSON содержит все данные, которые мы запросили. Эти данные форматируются как JSON и поставляются в том же виде, что и наш запрос. Каждому полю JSON выдается то же имя, что и поле в нашей выборке. Мы можем изменить имена полей в объекте ответа в запросе, указав псевдонимы, как показано ниже:

query liftsAndTrails {
    open: liftCount(status: OPEN)
    chairlifts: allLifts {
        liftName: name
        status
    }
    skiSlopes: allTrails {
       name
       difficulty
    }
}

Ниже приводится ответ:

{
   "data": {
       "open": 5,
       "chairlifts": [
         {
             "liftName": "Astra Express",
             "status": "open"
          }
       ],
       "skiSlopes": [
          {
             "name": "Ditch of Doom",
             "difficulty": "intermediate"
           }
        ]
    }
}

Теперь мы возвращаем данные в одну и ту же форму, но в нашем ответе мы переименовали несколько полей. Способ фильтрации результатов GraphQL-запроса состоит в передаче аргументов запроса. Аргументы — это пара значений ключа (или пары), связанная с полем запроса. Если требуются только имена закрытых подъемников, мы можем отправить аргумент, который будет фильтровать наш ответ:

query closedLifts {
       allLifts(status: "CLOSED" sortBy: "name") {
         name
         status
       }
}

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

query jazzCatStatus {
       Lift(id: "jazz-cat") {
         name
         status
         night
         elevationGain
       }
}

Здесь мы видим, что ответ содержит name, status, night и elevationGain для канатной дороги Jazz Cat.

» Более подробно с книгой можно ознакомиться на сайте издательства
» Оглавление
» Отрывок

Для Хаброжителей скидка 25% по купону — GraphQL

По факту оплаты бумажной версии книги на e-mail высылается электронная версия книги.