GraphQL

GraphQL - язык запросов к API: клиент выбирает поля из схемы, заданной сервером. Он полезен, когда экрану нужны связанные данные определённой формы, но сам по себе не устраняет задержки и не упрощает кеширование.

Операции и схема

• Query читает данные. Mutation изменяет данные или запускает действие на сервере; бездумно повторять её нельзя, поскольку она может быть неидемпотентной.
• Subscription передаёт обновления во времени. Транспорт (часто WebSocket) зависит от клиента и сервера, а не от самого языка GraphQL.
• Схема задаёт типы, поля, аргументы и допустимость null. Операция выбирает поля из этого контракта; сгенерированный Kotlin-тип описывает выбранный результат, а не обязательно весь тип схемы.

Передавайте динамические значения через переменные, а не собирайте текст запроса интерполяцией:

query RobotStatus($id: ID!) {
  robot(id: $id) {
    id
    name
    batteryPercent
  }
}

Клиент передаёт $id отдельно. ID! означает, что переменная не может быть null. При этом поле robot может быть nullable, если так указано в схеме. Фрагменты позволяют переиспользовать наборы полей в разных операциях.

Ответы и ошибки

Ответ может одновременно содержать data и errors: одно поле завершилось ошибкой, а остальные данные пригодны к использованию. Различайте сбой транспорта, ошибку выполнения GraphQL и бизнес-ошибку, представленную внутри data. Проверяйте допустимость null по схеме и явно решайте, можно ли показать частичные данные. Успешный HTTP-статус сам по себе не означает, что операция прошла без ошибок GraphQL.

GraphQL и REST

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

Apollo Kotlin на Android

Apollo Kotlin генерирует типобезопасные Kotlin-модели по схеме и операциям .graphql, выполняет запросы, мутации и подписки. Размещайте клиент в слое данных; репозитории могут преобразовывать сгенерированные ответы в стабильные доменные или UI-модели. Изменения схемы проверяйте на совместимость при сборке.

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

Связанные темы: HTTP / REST, Retrofit / OkHttp, StateFlow и SharedFlow.

Источники: запросы GraphQL, ответы GraphQL, Apollo Kotlin, нормализованный кеш Apollo.