GraphQL 10 лет. Пора в нем разобраться?

Сегодня GraphQL остаётся одной из самых популярных технологий для работы с API, особенно в среде веб-разработки. В этой статье я проведу экскурс, напомню, что такое GraphQL, его ключевые особенности, как быстро настроить собственный GraphQL-сервер, какие интересные публичные API можно попробовать и что использовать для его интеграции с фронтендом. А также заглянем в будущее GraphQL в 2025 году.

Что такое GraphQL?

GraphQL — это язык запросов к API и среда выполнения, разработанный Facebook в 2012 году и опубликованная как open source в 2015 году. Основное преимущество GraphQL заключается в том, что он предоставляет клиенту возможность запрашивать только те данные, которые ему необходимы, и в удобной структуре.

На изображении ниже показан, простой пример GraphQL query запроса. Запрашиваю страну, где code равен RU, с указанием необходимых полей для получения.

В GraphQL есть три вида запросов:

• Query - получение данных (аналог GET запроса в REST)

• Mutation - добавление и изменение данных (аналог POST, PUT запроса в REST)

• Subscription - подписка на изменение данных. Но с ними не все так однозначно, подробнее о них написано здесь ^[1].

Основные особенности

1. Гибкость запросов: позволяет клиенту запрашивать только те данные, которые ему действительно нужны.

2. Единая точка входа:  есть только один endpoint (обычно /graphql), через который проходят все запросы.

3. Schema definition language (SDN): GraphQL API основывается на схеме, которая описывает все доступные данные, их типы и связи между ними. Подробнее о том, как читать SDL можно почитать в этой статье ^[2]

4. Поддержка real-time: Subscriptions позволяют подписаться на обновления.

5. Сильная типизация: все данные строго типизированы, что помогает избежать ошибок. Типы включают стандартные (String, Int, Float, Boolean, Enum ) и на их основе можно создавать пользовательские типы данных.

6. Единый источник данных: GraphQL может объединять данные из разных источников (базы данных, REST API, микросервисы и т.д.) в единый API

7. Широкая экосистема инструментов: доступны различные генераторы кода для клиентов, поддерживающие полную спецификацию GraphQL. Одна из ключевых функций — встроенная поддержка кэширования запросов.

И чтобы долго не задерживаться на теории, давайте сразу перейдем к практике и попробуем GraphQL в действии! А если хочется больше теории, на хабре есть для этого статья ^[3] .

Как быстро поднять свой GraphQL?

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

Hasura
Автоматически генерирует GraphQL API поверх вашей базы данных (PostgreSQL), так же позволяет строить федерации - это построение единого шлюза для нескольких сервисов. Сам я на проектах использую версию v2 self-hosted. Быстрый старт ^[4]

Directus
Это Headless CMS + Backend, накладывает API на существующую базу данных и позволяет быстро создавать админ-панели. Очень простой и удобный инструмент для запуска MVP, что-то большее не довелось сделать на нем. Быстрый старт ^[5]

Apollo Server
Apollo Server - это сервер GraphQL с открытым исходным кодом, совместимый со спецификациями, который совместим с любым клиентом GraphQL, включая клиента Apollo. Не самый быстрый старт ^[6]

Публичные API с поддержкой GraphQL

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

1. SpaceX GraphQL API: ^[7]

2. GitHub API: ^[8]

3. Gitlab API ^[9]

4. Rick and Morty API ^[10]

5. Countries API ^[11]

Эндпоинты GraphQL схем можно добавить в Sdudio Apollo ^[12], указав при необходимости заголовки авторизации.

Как подключить GraphQL к фронту?

Чтобы быстро и удобно подключить GraphQL на клиенте, рекомендую использовать Apollo Client. Также обязательно настройте кодогенерацию ^[13] — это значительно упростит разработку за счет автоматического создания типов данных, хуков, классов и других вспомогательных структур на основе схемы, и все со строгой типизацией.

Apollo Client поддерживает:

• React ^[14] и React Native. Также совместим с другими веб-фреймворками ^[15], но основная документация сосредоточена на React.

• iOS ^[16].

• Kotlin ^[17].

Для Flutter рекомендую использовать graphql_flutter ^[18] и graphql_codegen ^[19].

Как изменится GraphQL в 2025 году?

1. Обязательная поддержка application/graphql-response+json:

   • С 1 января 2025 года серверы обязаны поддерживать медиа-тип application/graphql-response+json для ответов на запросы, которые указывают этот тип в заголовке Accept.

   • Это изменение направлено на улучшение совместимости и надежности, так как application/graphql-response+json лучше подходит для обработки ошибок и частичных ответов в GraphQL.

2. Кодировка UTF-8:

   • Ответы, использующие application/graphql-response+json, должны быть закодированы в UTF-8.

3. Изменение поведения по умолчанию:

   • Если клиент не указывает заголовок Accept, сервер должен рассматривать запрос как если бы он содержал Accept: application/graphql-response+json. Это изменение направлено на постепенный отход от использования application/json для ответов GraphQL.

4. Статус коды:

   • При использовании application/graphql-response+json сервер должен возвращать соответствующие статус-коды HTTP (например, 4xx или 5xx) в случае ошибок, которые полностью препятствуют генерации корректного GraphQL-ответа. Это отличается от текущей практики, где серверы могут возвращать 200 OK даже при ошибках.

5. Легаси-совместимость:

   • До 2025 года клиентам рекомендуется включать application/json в заголовок Acceptдля обеспечения совместимости с устаревшими серверами. После 2025 года это больше не будет необходимо.

Источник1 ^[20] Источник2 ^[21]

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

Недостатки GraphGL

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

На хабре можно найти статьи, в которых описываются боли с которыми встретились разработчики: 1 ^[22], 2 ^[23].

Заключение

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

В 2025 году исполняется 10 лет с момента, как GraphQL стал open source! По этому случаю на GraphQL Conf ^[24] пройдёт празднование десятилетия.

GraphQL по-прежнему остаётся востребованной технологией: он активно используется, о нём пишут как о плюсах, так и о минусах, его обсуждают на конференциях, а знания GraphQL часто требуются в вакансиях. Я считаю, что важно понимать, как он работает, и уметь применять его на практике. Надеюсь, этот экскурс помог вам разобраться в основах и попробовать GraphQL в действии!