Основы GraphQL для разработчиков React

REST предоставляет конечные точки с фиксированной структурой: GET /users/:id возвращает весь объект пользователя независимо от того, какие данные нужны клиенту. GraphQL позволяет клиентам указать именно нужные поля, устраняя получение лишних данных и недополучение данных, для которого требуется несколько запросов.

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

Каждый API GraphQL определяется схемой, записанной на языке определения схемы (SDL). Схема объявляет типы, их поля и корневые типы Query, Mutation и Subscription, с которыми могут работать клиенты.

Схема — это контракт между клиентом и сервером. Команды фронтенда и бэкенда могут работать параллельно после согласования схемы.

Запрос GraphQL выбирает поля: { user(id: "1") { name email posts { title } } }. Вложенные поля позволяют пройти по связям за один запрос. Псевдонимы переименовывают поля: { me: user(id: "1") { name } }. Фрагменты позволяют повторно использовать выборки полей в нескольких запросах.

Переменные делают запросы повторно используемыми: query GetUser($id: ID!) { user(id: $id) { name } } с переменными: { id: "1" }.

У каждого поля в схеме GraphQL есть функция-резолвер на сервере. Когда клиент запрашивает user.name, резолвер пользователя получает объект пользователя, а резолвер name (или резолвер по умолчанию) возвращает поле name.

Именно разрешение на уровне полей позволяет GraphQL получать только запрошенные данные.

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

DataLoader решает проблему N+1, объединяя все запросы авторов в один запрос к базе данных с помощью кэша на время запроса и функции пакетной загрузки.

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

Использование playground — самый быстрый способ разобраться с незнакомым API GraphQL, прежде чем писать код клиента.

API GraphQL предоставляют собственную схему через запрос интроспекции: { __schema { types { name } } }. Клиенты могут запрашивать саму схему, чтобы обнаружить доступные типы, поля и аргументы.

Инструменты генерации кода, такие как graphql-codegen, используют интроспекцию для автоматической генерации типов TypeScript, соответствующих схеме API.

Мутации GraphQL изменяют данные: mutation CreatePost($input: PostInput!) { createPost(input: $input) { id title } }. Подписки устанавливают постоянное соединение (обычно WebSocket) и передают обновления: subscription { postAdded { id title } }.

Все три корневых типа (Query, Mutation, Subscription) используют один и тот же синтаксис выбора полей.

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

REST проще для CRUD API с предсказуемой плоской структурой ресурсов и отличными возможностями кэширования через HTTP с помощью тегов ETag и заголовков кэша.

Apollo Client — самый функциональный клиент GraphQL: нормализованный кэш, управление локальным состоянием, подписки и связующие модули для обработки ошибок. URQL легче и использует кэш документов с более простым API. React Query вместе с graphql-request — самый простой подход для базовых запросов и мутаций без сложных возможностей кэширования.

Выбирайте клиент с учётом требований к кэшированию: нормализованный кэш подходит для сущностей, общих для нескольких запросов (Apollo), а более простой кэш документов — для независимых запросов (URQL или React Query).

Простой SDL: type User { id: ID! name: String! posts: [Post!]! } type Post { id: ID! title: String! author: User! } type Query { user(id: ID!): User users: [User!]! }. Восклицательные знаки обозначают поля, которые не могут иметь значение null.

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

Что означает «избыточная выборка данных» в контексте сравнения REST и GraphQL?

GraphQL позволяет клиентам запрашивать ровно те поля, которые им нужны (без избыточной или недостаточной выборки данных), используя язык запросов, определённый схемой. Резолверы обрабатывают каждое поле, а DataLoader решает проблему N+1. Интроспекция позволяет генерировать типы TypeScript. Apollo Client, URQL и React Query — основные клиенты GraphQL, совместимые с React.

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