В мире веб-разработки технологии меняются с молниеносной скоростью. Еще недавно REST казался универсальным ответом на все вопросы, однако сегодня компании ищут более эффективные решения, позволяющие обрабатывать огромные объемы данных и обеспечивать максимальную производительность.

Сегодня мы разберём GraphQL — что это за инструмент, как он работает, какие задачи решает, где оказывается удобнее REST и почему многие компании выбирают его для новых проектов.

Что такое GraphQL и зачем он появился?

GraphQL — это язык запросов для API и среда выполнения на стороне сервера для обработки этих запросов.

GraphQL не следует путать с SQL – он не используется для прямых запросов к таблицам базы данных. GraphQL – это, скорее, формат или структура, которая задает контракт между клиентом и сервером. Его можно рассматривать как спецификацию или новый стандарт API, похожий на REST, но более эффективный и гибкий.

GraphQL изначально был разработан как внутренний проект Facebook* в 2012 году. Тогда команда разработчиков столкнулась с серьезными ограничениями традиционных REST API при создании мобильного приложения новостной ленты для iOS. Основными проблемами REST стали:
Over-fetching — когда API возвращает гораздо больше данных, чем действительно нужно клиенту. Например, для отображения списка постов в ленте требовались только заголовки и авторы, но сервер отдавал полное содержимое каждого поста.
Under-fetching — ситуация, когда одного запроса недостаточно для получения всех необходимых данных, что приводило к каскаду дополнительных запросов.

Особенно критичными эти проблемы становились в условиях мобильных соединений с ограниченной пропускной способностью и длительными задержками при передаче данных. Множественные endpoint‘ы REST API требовали многочисленных HTTP-запросов, что делало приложения медлительными и неэффективными.

В 2015 году GraphQL стал open-source проектом, а позже перешел под управление Linux Foundation. Основная цель GraphQL — предоставить клиентам возможность запрашивать только те данные, которые им действительно нужны, и ничего лишнего. В отличие от REST GraphQL обычно использует одну точку входа (endpoint - обычно /graphql). Клиент отправляет на этот эндпоинт запрос, в котором точно описывает структуру и поля необходимых данных.

Принцип работы GraphQL

GraphQL функционирует по принципу «запрос — ответ» между клиентом и сервером:

• На сервере создаётся схема, описывающая все доступные типы данных, поля и операции, которые можно выполнить через API.

• Клиент формирует запрос, точно указывая необходимые данные.

• Клиент отправляет запрос на сервер через HTTP-метод POST.

• Сервер анализирует запрос, проверяет его соответствие схеме и выполняет нужные операции для получения данных.

• Сервер отправляет клиенту ответ, содержащий только запрашиваемую информацию.

• Клиент получает данные и использует их для обновления интерфейса или других операций.

  

Схема (Schema)

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

Основные типы данных в Schema:

1. Скалярные типы представляют примитивные значения: String, Int, Float, Boolean и ID.

2. Объектные типы описывают сложные структуры с набором полей. Например, тип User может содержать поля name, email и posts.

3. Типы списков позволяют работать с массивами данных — [Post] означает список постов.

4. Nullable и Non-nullable типы определяют, может ли поле быть пустым. Восклицательный знак ! указывает на обязательность поля.

Схема написана в SDL (Schema Definition Language). На её основе сервер проверяет корректность запросов и выбирает нужные резолверы.

В Schema задаются три специальных корневых типа, которые определяют точки входа в API: Query (для запросов на чтение данных), Mutation (для операций изменения данных) и Subscription (для подписки на обновления в реальном времени).

Чем отличается Schema в GraphQL от Swagger в REST?

Schema в GraphQL — это обязательный рабочий контракт API, а Swagger в REST — это внешняя документация, которая только описывает эндпоинты, но не управляет их работой. Наличие схемы позволяет автоматически генерировать документацию и предоставляет клиентам возможность интроспекции — запроса информации о самой схеме.

Резолвер GraphQL

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

Существуют два типа резолверов:

• Корневые резолверы: Обрабатывают поля верхнего уровня в схеме, такие как Query, Mutation и Subscription.

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

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

Операции GraphQL

Взаимодействие с GraphQL API происходит через отправку запросов, которые соответствуют определенной в схеме структуре. Существует три основных типа операций, которые клиент может выполнить. Каждый из них предназначен для решения своей задачи и является точкой входа, определенной в схеме. Эти операции обеспечивают полный цикл работы с данными: чтение, изменение и получение обновлений в реальном времени. 

Запросы (Queries)

Это основной способ получения данных из GraphQL API. Запрос имеет ту же структуру, что и JSON-объект, который клиент ожидает получить в ответ. Клиент указывает, какой объект он хочет получить и какие поля этого объекта ему нужны. Сервер обработает запрос и вернет JSON-ответ, точно соответствующий запрошенной структуре.

Для построения запросов GraphQL используются шесть основных компонентов: поля (fields), аргументы (arguments), фрагменты (fragments), псевдонимы (aliases), переменные (variables) и директивы (directives).

Мутации (Mutations)

Если запросы используются для чтения данных, то мутации — для их изменения (создания, обновления, удаления). Синтаксически мутации похожи на запросы, но они должны начинаться с ключевого слова mutation. Как и запросы, мутации также могут возвращать данные — например, состояние измененного объекта.

Подписки (Subscriptions)

Это механизм для работы с данными в реальном времени. Вместо того чтобы периодически опрашивать сервер на наличие обновлений, клиент может оформить подписку. Когда на сервере произойдет определенное событие (например, будет создана новая запись), сервер отправит обновленные данные клиенту по долгоживущему соединению, обычно через WebSockets.

Эти три операции делают GraphQL мощным и гибким инструментом для создания современных интерактивных приложений.

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

1. Гибкость и точность запросов. Клиенты получают именно те данные, которые им нужны, без избыточной информации. Это особенно критично для мобильных приложений, где каждый килобайт трафика влияет на производительность и расход батареи.

2. Типизация и автоматическая валидация позволяет клиентам легко понять, какие данные и типы доступны в API, и точно формулировать запросы.

3. Экономия сетевого трафика. Исследования показывают, что GraphQL может сократить объем передаваемых данных на 30-80% по сравнению с REST. GitHub, например, сообщил о снижении количества запросов на 80% для некоторых страниц после его внедрения.

4. Самодокументируемость (Self-documentation). Схема служит живой документацией API. Инструменты разработки автоматически генерируют описание доступных типов, полей и операций, что существенно упрощает работу команды.

5. Быстрое развитие без версионирования. Добавление новых полей в схему не нарушает работу существующих клиентов. Это позволяет командам быстро итерировать и развивать API без создания новых версий или breaking changes.

6. Удобство для frontend-разработчиков. GraphQL позволяет frontend-команде работать независимо от backend’а, используя mock-данные на основе схемы.

7. Современные фронтенд-фреймворки (React, Vue, Angular) часто требуют сложных и вложенных данных. GraphQL позволяет получать все необходимые данные для компонента в одном запросе.

8. Если бэкенд состоит из множества микросервисов, GraphQL может выступать в роли единого шлюза (gateway). Он агрегирует данные из разных источников и предоставляет клиенту единый и консистентный API.

Недостатки GraphQL

1. Отсутствие встроенного кэширования. В отличие от REST, который эффективно использует HTTP-кэши, GraphQL требует разработки собственных механизмов кэширования. Каждый запрос уникален по структуре, что делает невозможным применение стандартных HTTP-заголовков для кэширования. Это может существенно увеличить нагрузку на сервер и усложнить архитектуру.

2. Проблемы производительности при глубоких запросах. GraphQL позволяет создавать сложные вложенные запросы, которые могут привести к экспоненциальному росту нагрузки на сервер. Запрос типа users { posts { comments { author { posts } } } } может вызвать тысячи обращений к базе данных. Необходимо внедрять лимиты глубины запросов и механизмы защиты от злоупотреблений.

3. Вопросы безопасности и необходимость лимитов. Открытая природа делает API уязвимым для DoS-атак через сложные запросы. Требуется тщательная настройка rate limiting’а, анализа сложности запросов и мониторинга производительности.

4. Переусложнение для простых проектов. Для небольших приложений с простой структурой данных накладные расходы на настройку схемы, резолверов и инструментария могут оказаться неоправданными. В таких случаях традиционный REST может быть более прагматичным решением.

5. Сложность отладки и мониторинга. Единый endpoint затрудняет анализ производительности и выявление проблемных запросов. Стандартные инструменты мониторинга HTTP-трафика требуют адаптации для работы с GraphQL.

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

7. Работа с файлами, например, загрузка или выгрузка больших файлов, в GraphQL не так проста, как в REST API, и требует дополнительных обходных путей или библиотек.

Несмотря на быстрое развитие экосистемы, GraphQL все еще остается относительно новой технологией по сравнению с REST, и соответствующие инструментальные средства и библиотеки не всегда доступны или не так развиты, как для REST API.

Когда лучше выбрать REST, а когда GraphQL?

Выбор между REST и GraphQL не является вопросом "что лучше", а скорее "что лучше подходит для конкретного проекта и его задач". Обе технологии имеют свои сильные стороны и оптимальные сценарии использования.

Выбирайте REST, если:

1. Простота и стандартизация — ваш приоритет:
   Проект несложный, с относительно простой и стабильной структурой данных.
   Вам нужна быстрая разработка без глубокого погружения в новые концепции.
   Команда уже хорошо знакома с REST и стандартными HTTP-методами.

2. Эффективное кэширование является критичным:
   Ваши данные часто запрашиваются повторно, и вы хотите использовать встроенное HTTP-кэширование для уменьшения нагрузки на сервер.

3. Вам нужен контроль доступа на уровне эндпоинтов:
   Проще управлять разрешениями на уровне URL-адресов.

4. Работа с файлами является важной частью API:
   Загрузка и выгрузка файлов в REST более стандартизирована и прямолинейна.

5. Публичное API:
   Для публичных API, где простота интеграции для широкого круга сторонних разработчиков важнее тонкой настройки выборки данных.

Вы не хотите столкнуться с проблемами глубоких запросов и их оптимизации.

Примеры использования REST:

• Большинство существующих веб-сервисов и публичных API (Twitter, GitHub v3).

• Простые CRUD-операции, где клиент обычно нуждается во всех полях ресурса.

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

Используйте GraphQL, когда:

1. Гибкость выборки данных — ваш главный приоритет:
   Клиентские приложения (особенно мобильные и SPA), которым нужно получать очень специфичные наборы данных, чтобы минимизировать трафик и ускорить загрузку.
   Вам нужно избежать over-fetching и under-fetching.

2. Фронтенд- и бэкенд-команды должны быть максимально независимыми:
   Фронтенд-разработчики могут запрашивать данные, не дожидаясь изменений на бэкенде или создания новых эндпоинтов.

3. API быстро развивается, и вы хотите избежать проблем с версионированием:
   Часто добавляются новые поля, и вы не хотите ломать старые клиенты или поддерживать несколько версий API.

4. Необходимо агрегировать данные из множества источников:
   Ваш бэкенд состоит из микросервисов, и GraphQL может служить единым шлюзом, объединяющим данные из разных сервисов в один запрос для клиента.

5. Требуется строгая типизация и самодокументируемость:
   Схема GraphQL обеспечивает четкий контракт и автоматически генерируемую документацию, что упрощает разработку и отладку.

6. Вам нужны обновления данных в реальном времени (Subscriptions).

7. Команда готова к освоению новых концепций и решению проблем кэширования и оптимизации запросов.

Примеры использования GraphQL:

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

• Сложные одностраничные приложения (SPA) с богатым пользовательским интерфейсом.

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

• Facebook*, GitHub (их API v4), Shopify.

Заключение

Как и в случае с REST и SOAP, REST и GraphQL — не конкуренты, а две разные технологии для разных целей. REST отлично подходит для создания стабильных, кэшируемых API с чётко определёнными ресурсами. GraphQL превосходит его в сценариях, где нужна высокая гибкость запросов, минимизация трафика и быстрое развитие клиентских приложений. В некоторых случаях оптимальным решением может быть гибридный подход, где часть API реализована на REST (например, для простых CRUD-операций), а часть — на GraphQL (для сложных агрегированных запросов).