GraphQL — что это такое, язык запросов и применение в мобильных проектах

Что такое GraphQL?

GraphQL — это спецификация и среда выполнения для API, которая предоставляет клиенту полный контроль над получаемыми данными. Разработанная инженерами Facebook для решения проблем мобильного приложения News Feed, спецификация была опубликована как открытый стандарт в 2015 году. С 2018 года GraphQL находится под управлением GraphQL Foundation при поддержке Linux Foundation и таких компаний, как Apollo, AWS, GitHub, SAP и другие.

В отличие от REST, где каждый эндпоинт возвращает фиксированную структуру данных, GraphQL использует единый эндпоинт, принимающий строку запроса. Клиент описывает в запросе, какие поля ему нужны, и сервер возвращает ровно их. Например, запрос { user(id: "1") { name email } } вернёт только name и email пользователя, без лишних полей вроде address, phone или createdAt, которые пришлось бы получать в REST.

GraphQL не привязан к какой-либо конкретной базе данных или языку. Спецификация определяет только формат запросов и ответов. Существуют реализации серверов на Node.js (graphql-js, Apollo Server), Kotlin (graphql-kotlin, Netflix DGS Framework), Python (Graphene, Strawberry), Ruby (graphql-ruby) и других языках. Клиентские библиотеки доступны для всех основных платформ, включая Apollo Client для iOS, Android и веба.

Как работает GraphQL

Архитектура GraphQL состоит из трёх ключевых компонентов: схема (Schema), резолверы (Resolvers) и движок выполнения (GraphQL Engine). Схема определяет, какие типы данных доступны, какие запросы можно выполнять и какие аргументы они принимают. Резолверы — это функции на сервере, которые возвращают данные для каждого поля схемы. Движок выполнения получает входящий запрос, валидирует его по схеме, вызывает соответствующие резолверы и собирает ответ.

Процесс обработки запроса выглядит так:

• Клиент отправляет POST-запрос на /graphql с JSON-телом { "query": "..." }
• Сервер парсит запрос, строит AST (Abstract Syntax Tree) и валидирует его по схеме
• Движок проходит по AST, вызывая резолверы для каждого поля, собирая данные
• Ответ возвращается в формате JSON, строго соответствующий структуре запроса

Ключевое преимущество архитектуры GraphQL — разрешение на уровне полей. В REST разработчик либо получает все поля ресурса (возможно, с лишними), либо прибегает к расширениям вроде ?fields=name,email. В GraphQL такая фильтрация встроена в язык: каждый запрос явно специфицирует, какие поля нужны, и сервер возвращает ровно их. Это особенно важно для мобильных приложений, где объём передаваемых данных напрямую влияет на скорость загрузки и расход трафика.

Query, Mutation и Subscription

GraphQL определяет три типа операций, каждый из которых соответствует определённому сценарию взаимодействия. Query — для чтения данных, аналогичен GET в REST. Mutation — для изменения данных (создание, обновление, удаление), аналогичен POST/PUT/DELETE. Subscription — для real-time обновлений через WebSocket, что не имеет прямой аналогии в классическом REST (требует дополнительных решений вроде WebSocket или Server-Sent Events).

Базовый синтаксис запросов интуитивно понятен:

// Простой query с аргументом
query {
    user(id: "42") {
        name
        email
        avatarUrl
    }
}

// Mutation с возвратом изменённых данных
mutation {
    updateProfile(name: "Иван") {
        id
        name
        updatedAt
    }
}

// Subscription — слушает real-time обновления
subscription {
    newMessage(chatId: "chat_1") {
        id
        text
        sender { name }
    }
}

Query выполняется параллельно — все поля на одном уровне загружаются одновременно. Это позволяет загрузить связанные данные (пользователя и его посты) одним запросом без множества round-trip. Mutation выполняется последовательно — мутации в одном запросе выполняются одна за другой в порядке объявления. Subscription устанавливает постоянное соединение через WebSocket, по которому сервер отправляет данные при наступлении события.

Операции могут принимать переменные для отделения данных от запроса, директивы (@include, @skip) для условного включения полей и фрагменты для повторного использования наборов полей. Эти возможности делают GraphQL-запросы гибкими и переиспользуемыми, что особенно важно в крупных проектах с множеством экранов и компонентов.

Схема и система типов GraphQL

В основе GraphQL лежит система типов, описывающая все возможные данные и операции API. Схема (Schema) — это описание типов, которые может возвращать сервер, и запросов, которые принимает. Схема пишется на языке Schema Definition Language (SDL) и служит контрактом между клиентом и сервером. Клиент может получить схему через интроспекцию — специальный запрос __schema, который возвращает полное описание API.

Пример схемы для блога:

// SDL — Schema Definition Language
type User {
    id: ID!
    name: String!
    email: String
    posts: [Post!]!
}

type Post {
    id: ID!
    title: String!
    content: String
    author: User!
}

type Query {
    user(id: ID!): User
    posts(page: Int): [Post!]!
}

Восклицательный знак (!) означает non-null поле — оно гарантированно будет присутствовать в ответе. Квадратные скобки [ ] обозначают список. GraphQL поддерживает скалярные типы (Int, Float, String, Boolean, ID), объектные типы, enum, union, interface и input-типы (для аргументов мутаций). Строгая типизация само-документирует API и позволяет клиентским инструментам генерировать код: TypeScript-типы, Kotlin-дата-классы, Swift-структуры.

Интроспекция — уникальная возможность GraphQL, отсутствующая в REST. Клиент может отправить запрос к схеме и получить полное описание всех типов, полей, аргументов и директив. Это лежит в основе инструментов вроде GraphiQL и Apollo Studio, которые автоматически генерируют документацию и автодополнение для разработчиков. Интроспекция также позволяет писать автоматические тесты, проверяющие соответствие схемы ожидаемой структуре.

Сравнение GraphQL с REST

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

Основной недостаток GraphQL — сложность кэширования. В REST HTTP-кэширование работает на уровне URL: один запрос к /api/users/42 возвращает всегда одинаковую структуру, и ответ можно кэшировать по URL. В GraphQL все запросы идут на один эндпоинт, структура ответа зависит от тела запроса. Для решения этой проблемы Apollo Client использует нормализованный кэш на стороне клиента, который разбивает ответы на отдельные сущности по id и автоматически обновляет их при получении новых данных.

Ещё один важный аспект — N+1 проблема. При запросе вложенных данных (например, посты пользователя и комментарии к каждому посту) GraphQL может выполнить отдельный SQL-запрос для каждого элемента списка. Решается с помощью DataLoader — утилиты для батчинга и кэширования запросов к базам данных, которая группирует отдельные запросы в один пакетный. В REST эта проблема менее выражена, так как разработчик контролирует структуру ответа на сервере.

Примеры GraphQL запросов

Рассмотрим практические примеры использования GraphQL в мобильном приложении на Kotlin с Apollo Client. Примеры демонстрируют типичные сценарии: загрузка данных для экрана профиля (query), создание нового поста (mutation) и подписка на новые комментарии (subscription). Каждый пример включает как GraphQL-запрос, так и код на клиентской стороне.

Query: загрузка профиля с постами

Один запрос GraphQL загружает пользователя, его последние посты и общее количество подписчиков. В REST для этого потребовалось бы минимум 2-3 запроса: /users/42, /users/42/posts, /users/42/stats. GraphQL объединяет их в один round-trip, сокращая время загрузки экрана на медленных соединениях.

// GraphQL запрос (в .graphql файле)
query ProfileScreen($userId: ID!) {
    user(id: $userId) {
        name
        bio
        avatarUrl
        posts(limit: 10) {
            id
            title
            createdAt
        }
        followersCount
        followingCount
    }
}

// Вызов на клиенте (Apollo Client + Kotlin)
val response = apolloClient
    .query(ProfileScreenQuery(userId = "42"))
    .execute()
binding.nameText.text = response.data?.user?.name

Mutation: создание нового поста

Мутация не только создаёт ресурс, но и возвращает его актуальные данные для обновления UI. Поле __typename используется Apollo Client для нормализации кэша — клиент автоматически обновит запись Post в кэше при успешном ответе мутации.

// GraphQL мутация
mutation CreatePost($input: CreatePostInput!) {
    createPost(input: $input) {
        id
        title
        createdAt
        author {
            id
            name
        }
    }
}

// Вызов мутации с input-типом
val input = CreatePostInput(
    title = "Новый пост о GraphQL",
    content = "GraphQL упрощает работу с API..."
)
val result = apolloClient
    .mutation(CreatePostMutation(input))
    .execute()

Важное преимущество GraphQL перед REST в контексте мобильной разработки — автоматическая генерация кода. Apollo Client для Kotlin (Apollo GraphQL) генерирует типобезопасные классы из .graphql файлов на этапе сборки. Если сервер изменит схему, проект не соберётся до обновления запросов. Это предотвращает runtime-ошибки, характерные для REST, где изменение структуры ответа может остаться незамеченным при разработке.

Экосистема: Apollo, Relay и инструменты

Экосистема GraphQL включает несколько ключевых библиотек и инструментов, которые упрощают разработку и эксплуатацию. Apollo Client — самая популярная клиентская библиотека, поддерживающая React, iOS, Android и Kotlin Multiplatform. Relay от Facebook — альтернатива для React-приложений с уникальным подходом к управлению данными и кэшированием. Выбор между Apollo и Relay зависит от платформы и требований к производительности.

На серверной стороне лидируют Apollo Server (Node.js), Netflix DGS Framework (Kotlin/Java) и graphql-ruby. Для разработки схемы и тестирования запросов используется GraphiQL — интерактивная IDE, встроенная в браузер. Apollo Studio предоставляет метрики производительности, трассировку запросов и управление схемой для продакшн-среды. Отдельно стоит упомянуть GraphQL Code Generator — инструмент, генерирующий TypeScript, Kotlin, Swift и Dart типы из SDL-схемы.

Для мобильной разработки особый интерес представляет Apollo Kotlin (Apollo GraphQL) — библиотека, полностью написанная на Kotlin с поддержкой корутин, Flow и Multiplatform. Она позволяет использовать единые GraphQL-запросы для Android и iOS в Kotlin Multiplatform проектах. Apollo Kotlin нормализует кэш, поддерживает ошибки на уровне полей (partial errors) и автоматически генерирует модели данных из .graphql файлов. Это делает GraphQL предпочтительным выбором для крупных мобильных проектов, где важны скорость разработки и типобезопасность.