Руководство по GraphQL

    В этой статье мы расскажем, что такое GraphQL простыми словами, рассмотрим плюсы и минусы GraphQL, как выглядят запросы и зачем нужна схема GraphQL.

    Что такое GraphQL

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

    GraphQL

    GraphQL разработали в 2012 году как альтернативу REST. Напомним, что REST — это архитектурный стиль, который описывает правила взаимодействия между клиентом и сервером. При этом используются HTTP-запросы, стандарт построения URL, форматы данных JSON и XML. REST API выдает ответ на запрос в формате JSON. Затем ответ нужно проанализировать, выбрать конкретные данные и извлечь их. GraphQL же позволяет передать в приложение сразу нужные данные за один запрос, даже если они находятся в нескольких источниках. Благодаря этому технология извлечения данных GraphQL удобнее и практичнее, чем REST.

    Итак, перечислим основные преимущества GraphQL:

    • Не нужно создавать несколько REST-запросов. Чтобы извлечь данные, достаточно ввести один запрос.
    • Не привязан к конкретной базе данных или механизму хранения.
    • Используется целая система типов данных.

    GraphQL API построен на двух основных блоках: запросах (queries) и схеме (schema).

    Ключевые особенности GraphQL

    • 1. Запросы по требованию. GraphQL позволяет клиентам запрашивать только те данные, которые им нужны. Например, если приложению нужно только имя пользователя и его электронная почта, запрос GraphQL сможет вернуть только эти два поля, избегая лишней информации.
    • 2. Единая точка доступа (endpoint). В отличие от REST, где каждая сущность имеет свой endpoint (например, для пользователей — /users, для товаров — /products), GraphQL использует единый endpoint для всех запросов. Это упрощает организацию кода и его поддержку.
    • 3. Типизированная схема. GraphQL использует систему типов для описания данных, доступных через API. Схема GraphQL, определяемая на сервере, содержит информацию о доступных типах данных, полях, их связях и возможностях. Это упрощает разработку и позволяет обеспечить более высокий уровень безопасности.
    • 4. Обработка ошибок. В GraphQL ошибки обрабатываются на уровне сервера и возвращаются клиенту в едином формате. При этом, даже если в запросе содержится ошибка, GraphQL может вернуть частичные данные вместе с информацией об ошибках.
    • 5. Интерактивные запросы. GraphQL позволяет отправлять как простые запросы (queries), так и мутации (mutations) для изменения данных. Также он поддерживает подписки (subscriptions), что дает возможность обновлять данные в реальном времени.

    Преимущества GraphQL

    • 1. Гибкость запросов. Основное преимущество GraphQL заключается в гибкости. Клиенту не нужно запрашивать всю информацию, как это требуется в REST API — он получает только те данные, которые ему нужны.
    • 2. Оптимизация сетевого трафика. Благодаря возможности запрашивать конкретные поля, GraphQL помогает снизить количество данных, передаваемых по сети.
    • 3. Документирование API. В GraphQL любое изменение в API автоматически документируется за счет того, что API-интерфейс тесно связан с кодом. Это позволяет разработчикам значительно экономить время на создании документации, при этом сохраняя доступ к истории изменений.
    • 4. Совместимость с разными источниками данных. GraphQL может получать данные из различных источников, объединяя их в один запрос. Например, для получения данных о пользователе можно интегрировать несколько микросервисов или баз данных, чтобы собрать всю нужную информацию.
    • 5. Удобная отладка и тестирование. GraphQL имеет множество инструментов для отладки и тестирования, например, GraphiQL или Insomnia. Эти инструменты позволяют интерактивно выполнять запросы, экспериментировать с мутациями и видеть возвращаемые данные сразу.

    Недостатки GraphQL

    • 1. Проблемы с кэшированием. Из-за единой точки доступа и гибких запросов кэширование данных в GraphQL может вызвать сложности. В отличие от REST, где каждый endpoint кэшируется отдельно, в GraphQL динамические запросы усложняют использование стандартных кэширующих механизмов.
    • 2. Перегрузка запросов. GraphQL предоставляет клиенту большую свободу в выборе данных, что может привести к перегрузке запросов, когда клиент запрашивает слишком много данных одновременно. Это может увеличить потребление ресурсов и нагрузку на сервер.
    • 3. Безопасность. Хотя типизация помогает снизить вероятность ошибок, однако при неправильной настройке GraphQL может стать уязвимым к атакам. Потребуется внедрить дополнительные меры безопасности.
    • 4. Проблемы с поддержкой сложных систем. Для больших и сложных систем настройка и управление схемой GraphQL могут потребовать значительных ресурсов и времени. Это особенно актуально для проектов, где уже есть сложные REST API, которые нужно адаптировать.

    GraphQL: запросы

    Сначала запросы в GraphQL (query) отправляют на сервер. Затем они возвращаются как ответ клиенту (приложению) в формате JSON. Неважно, откуда поступают данные, их можно запросить конкретной командой.

    Простейший запрос GraphQL может выглядеть так:

    query {


  friends {
    name
    others {
      name
    }
  }
}

    Такой запрос выдаст следующий ответ в формате JSON:

    {

   "data": {
     "friends": {
       "name": "Alex",
       "others": [
         {
           "name": "Mike"
         },
         {
           "name": "Jason"
         },
         {
           "name": "Jack"
         }
       ]
     }
   }
 }

    Как видно выше, ответ имеет такую же форму, как и запрос. Поэтому в GraphQL ответ всегда ожидаем.

    Самый распространенный способ работы с API GraphQL — графический инструмент GraphiQL. Когда вы подключаете GraphiQL к конечной точке (endpoint) GraphQL, он запрашивает у сервера свою схему GraphQL и предоставляет вам пользовательский интерфейс для просмотра и тестирования запросов. GraphiQL отправляет строку запроса GraphQL на сервер в заданной конечной точке с заголовками HTTP. Затем сервер отправляет ответ, который получает пользователь.

    Подробнее о схемах ниже.

    GraphQL: схема

    В целом, язык запросов GraphQL — это выбор полей в объектах. Так, в примере GraphQL-запроса ниже мы:

    • выбираем поле friend,
    • для объекта, который возвращен в friend, выбираем поля name и address:
    query {

  friend {
    name
    address
  }
}

    Запрос GraphQL совпадает с результатом, и мы можем предсказать, какой получим ответ, без знаний о сервере. Однако удобнее иметь точное описание данных для запроса: какие поля можно выбрать, и какие типы объектов будут возвращены в ответе. Как раз для этого и нужна схема GraphQL.

    Любой сервис GraphQL определяет набор типов данных, которые можно запросить. Каждый ответ на запрос проверяется и выполняется только в соответствии со схемой.

    Самые простые компоненты схемы GraphQL — типы объектов. Каждый тип содержит вид объекта и поля для этого объекта. В GraphQL schema language мы можем отобразить это следующим образом:

    type Character {

  name: String

  address: [City]
}
    • Character — это тип объекта GraphQL: тип и некоторые поля.
    • name и address — это поля в Character. Эти поля могут появиться в ответе на запрос GraphQL.
    • String — тип данных (в данном случае это строка). Также здесь могут быть и другие типы — Int (целое число), Float (число с плавающей точкой), Boolean (true или false), ID (уникальный идентификатор).
    • [City] — массив объектов City.

    Часто задаваемые вопросы про GraphQL

    Каковы основные преимущества использования GraphQL?
    GraphQL дает клиентам полный контроль над данными, которые они запрашивают, помогая избежать перегрузки и недостатка данных (over-fetching и under-fetching). Он поддерживает строгую типизацию и автоматическое документирование API, что упрощает разработку и интеграцию. Благодаря возможностям объединения данных из разных источников, GraphQL позволяет делать запросы к нескольким системам одновременно через один API.
    Чем GraphQL лучше REST?
    GraphQL позволяет выполнять запросы из одного endpoint и получать только нужные данные, тогда как REST часто приводит к получению избыточной информации из нескольких endpoint. В REST API также трудно управлять сложными структурами данных, что делает GraphQL более удобным для сложных приложений.
    Какие типы операций существуют в GraphQL?
    GraphQL поддерживает 3 типа операций: query (запрос), mutation (мутация) и subscription (подписка). Запросы используются для получения данных, а мутации — для их изменения. Например, запрос может возвращать информацию о пользователях, а мутация — обновлять или добавлять данные. Подписки используются для обновления данных в реальном времени.
    Как обрабатывать ошибки в GraphQL?
    Ошибки в GraphQL возвращаются в стандартном формате errors, где каждая ошибка содержит сообщение и, как правило, путь к ошибочному полю. Это позволяет понять, где произошла ошибка, и принять необходимые меры.
    Как работает типизация в GraphQL?
    GraphQL использует систему типов, которая описывает доступные данные и структуру API. Схема GraphQL включает типы данных, такие как скаляры (Int, String, Boolean и другие), объекты и их поля, что позволяет клиенту видеть, какие данные доступны для запроса.
    Насколько безопасен GraphQL?
    GraphQL API требует внедрения дополнительных мер безопасности, таких как ограничения на глубину и сложность запросов, чтобы избежать атак, перегружающих сервер. Это связано с тем, что в GraphQL клиент может запрашивать большое количество данных одним запросом.
    Какие инструменты поддерживают GraphQL?
    GraphQL поддерживается многими популярными инструментами и библиотеками, например, Apollo и Relay для работы на стороне клиента, GraphiQL и Insomnia для отладки и тестирования запросов. Также платформа GitLab имеет встроенный GraphQL API, что делает его удобным для интеграций и автоматизации на уровне репозиториев и задач.
    Как начать использовать GraphQL?
    Для начала работы с GraphQL нужно настроить сервер GraphQL и описать схему API с типами данных. Затем можно подключить клиент, например, Apollo Client, чтобы отправлять запросы к серверу.

    Помогла ли вам статья?

    Спасибо за оценку. Рады помочь 😊

     👍
    Специальные предложения