Документация / GraphQL

Подписки (subscription)

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

Многое из того, что относится к запросам, относится и к подпискам, поэтому сначала прочитайте страницу «Запросы».

Подписка на обновления

Поля подписок определяются точно так же, как поля Query и Mutation, но в корневом типе subscription:

type Subscription {
  reviewCreated: Review
}

Подписка начинается ключевым словом subscription в роли типа операции:

subscription NewReviewCreated {
  reviewCreated {
    rating
    commentary
  }
}

Обычно за подписками GraphQL стоит отдельная система публикации и подписки (pub/sub): сообщения об изменении данных публикуются в ней по мере необходимости, а резолверы полей подписки их получают.

Для примера выше: когда клиент отправляет новый отзыв изменением createReview, в систему pub/sub публикуется сообщение REVIEW_CREATED, а резолвер поля подписки reviewCreated слушает это событие и отправляет данные подписанным клиентам.

Подписки — не то же самое, что живые запросы (live queries): нестрого определённая возможность, которую предлагают некоторые реализации GraphQL. Обсуждение формальной спецификации живых запросов.

Как и для запросов и изменений, GraphQL не задаёт транспортный протокол — его выбирает сервер. На практике подписки часто реализуют через WebSocket или server-sent events (SSE). Клиенты, которые отправляют подписки, тоже должны поддерживать выбранный протокол. Сообщество поддерживает спецификации подписок GraphQL через WebSocket и server-sent events.

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

Например, такая операция некорректна:

subscription {
  reviewCreated {
    rating
    commentary
  }
  humanFriendsUpdated {
    name
    friends {
      name
    }
  }
}

А такой документ корректен:

subscription NewReviewCreated {
  reviewCreated {
    rating
    commentary
  }
}
subscription FriendListUpdated($id: ID!) {
  humanFriendsUpdated(id: $id) {
    name
    friends {
      name
    }
  }
}

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

Подписки в масштабе

Подписки — мощная возможность GraphQL, но реализовать их сложнее, чем запросы и изменения: документ GraphQL, переменные и прочий контекст нужно хранить всё время жизни подписки. Это непросто при горизонтальном масштабировании серверов GraphQL — каждый подписанный клиент должен быть привязан к конкретному экземпляру сервера.

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

На практике API GraphQL с подписками требует более сложной архитектуры, чем API только с запросами и изменениями. Её устройство зависит от реализации GraphQL, системы pub/sub, выбранного транспорта, а также от требований к доступности, масштабируемости и безопасности данных реального времени.

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

Итоги

Подведём итоги о подписках:

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

Мы разобрали все три вида операций GraphQL; дальше — как сервер GraphQL проверяет запросы клиентов.

Обновлено: 17 октября 2026 г.