Федерация GraphQL — это подход, при котором несколько GraphQL-сервисов объединяются в один общий API. Клиент работает с единой точкой входа, хотя данные и бизнес-логика остаются распределёнными между разными сервисами.
Содержание статьи
Как работает федерация GraphQL
Федерация GraphQL собирает несколько подграфов в одну общую схему, с которой взаимодействует клиент. За объединение обычно отвечает шлюз или роутер, который понимает, какой сервис должен обработать нужную часть запроса.
В обычной схеме GraphQL весь набор типов, запросов и мутаций часто живёт в одном месте. При росте системы такой подход начинает мешать: одна команда затрагивает код другой, выпуск изменений усложняется, а сама схема становится тяжёлой для сопровождения.
Федерация решает эту проблему через разделение. Каждый сервис отвечает за свой домен данных: каталог, пользователей, заказы, отзывы и другие части системы. При этом клиенту не нужно знать, где именно лежат данные. Он отправляет один GraphQL-запрос и получает цельный ответ.
На практике схема делится на подграфы. Каждый подграф описывает свои типы, поля и правила получения данных. Шлюз читает эти схемы, строит из них общую структуру и формирует план выполнения запроса между сервисами.
Из чего состоит федеративная архитектура
Базовые элементы федерации — это подграфы, сервисы подграфов и шлюз. Вместе они формируют единый граф данных поверх нескольких независимых источников.
- Подграф — часть общей GraphQL-схемы, которая описывает отдельный домен.
- Сервис подграфа — сервер, который реализует логику этого домена и получает данные из базы, REST API или других источников.
- Шлюз — компонент, который объединяет схемы подграфов и принимает клиентские запросы.
- Суперграф — общая схема, собранная из нескольких подграфов.
Такое разделение помогает командам двигаться независимо. Одна команда может изменять схему товаров, другая — схему пользователей, не переписывая общий монолитный сервер. При этом внешне система остаётся цельной.
Чем федерация отличается от schema stitching
Schema stitching объединяет несколько схем вручную, а федерация задаёт правила связи между сервисами на уровне архитектуры и схемы. За счёт этого федерация обычно проще в сопровождении в распределённых системах.
При schema stitching разработчики сами описывают, как склеивать схемы и как передавать данные между резолверами. Это работает, но по мере роста числа сервисов появляется много ручной логики. Чем больше связей, тем выше риск ошибок.
Федерация добавила более формальный способ объединения. Вместо большого слоя кастомной склейки сервисы заранее объявляют, какие сущности им принадлежат, какие поля расширяются в других сервисах и по каким ключам искать связанные данные.
Именно поэтому федерацию часто рассматривают как следующий шаг после stitching в системах, где схема распределена между несколькими командами.
Как появились Apollo Federation и open federation
Apollo Federation популяризировала сам подход к федерации GraphQL и ввела набор директив для связи схем. Позже появились более открытые варианты, где объединять можно не только Apollo-совместимые GraphQL-сервисы.
Изначально идея федерации стала известной благодаря Apollo. Этот подход предложил понятные механизмы для описания распределённого графа: ключи сущностей, внешние поля, расширение типов и зависимости между сервисами. За счёт этого стало проще строить общий API поверх нескольких доменов.
Но у такого варианта есть ограничение: архитектура сильнее зависит от конкретной экосистемы и её правил. Если в компании много разных технологий или есть желание подключать не только GraphQL-источники, появляются вопросы совместимости.
Open federation обычно выбирают там, где нужна большая свобода интеграций. В таких схемах единый слой может строиться поверх разных API и разных поставщиков технологий, а не только вокруг одной реализации федерации.
Какие задачи решает федерация GraphQL
Федерация GraphQL нужна там, где один GraphQL-сервер становится узким местом для разработки и сопровождения. Она помогает разделить ответственность между сервисами, не ломая единый интерфейс для клиента.
Чаще всего федерацию используют в архитектурах с микросервисами. Данные уже распределены по доменам, а фронтенду всё равно нужен единый API. Без федерации командам приходится либо строить отдельный агрегирующий слой вручную, либо держать громоздкий сервер, который знает слишком много обо всём сразу.
Есть и организационный эффект. Команды могут выпускать изменения в своей части схемы отдельно друг от друга. Это снижает количество пересечений в коде и уменьшает зависимость от общего релиза.
Для клиента разница тоже заметна. Запросы остаются цельными: можно получить связанные данные из нескольких сервисов через один интерфейс, не собирая ответ по кускам на стороне приложения.
Как устроен подграф
Подграф — это отдельная часть общей схемы GraphQL, которая отвечает за конкретную область данных. Он описывает свои типы, операции и правила доступа к данным, а также связи с другими подграфами.
По структуре подграф похож на обычную GraphQL-схему. В нём есть типы, запросы, мутации и резолверы. Разница в том, что в федеративной архитектуре схема дополняется специальными директивами, которые помогают объединять сущности между сервисами.
Например, один сервис может владеть сущностью товара, а другой — дополнять её полями с отзывами. Тогда общая схема будет выглядеть как единый тип, хотя его части фактически реализованы в разных местах.
Какие директивы используются чаще всего
Директивы федерации описывают, как связаны типы и поля в разных подграфах. Они нужны шлюзу, чтобы понимать, откуда получать сущности и как собирать итоговый ответ.
- @key — указывает поля, по которым сущность можно однозначно найти в федеративном графе.
- @extends — показывает, что тип расширяется в другом подграфе.
- @external — помечает поле, которое определяется не в текущем сервисе.
- @requires — задаёт зависимость поля от других полей при вычислении значения.
Набор директив зависит от реализации федерации, но сама идея одна: явно описать границы ответственности между сервисами и связи между сущностями.
Как проходит выполнение запроса
Клиент отправляет один запрос в шлюз, а шлюз разбивает его на части и распределяет между нужными подграфами. После этого он собирает результаты в один ответ.
Это похоже на диспетчера. Шлюз смотрит на структуру запроса, определяет, какие поля относятся к какому сервису, и в каком порядке их нужно получить. Если одно поле зависит от данных другого сервиса, шлюз строит план выполнения с учётом этой зависимости.
Например, клиент запрашивает товар, автора отзыва и профиль пользователя. Для приложения это один запрос. Для федерации — цепочка обращений к нескольким сервисам с последующей сборкой ответа.
Именно поэтому качество схемы и корректность связей между подграфами влияют на производительность. Чем точнее разделены домены, тем проще строить предсказуемый план выполнения.
Как внедряют федерацию GraphQL
Внедрение федерации обычно начинается с разделения общей схемы по доменам, затем поднимаются сервисы подграфов и настраивается шлюз. После этого систему разворачивают и наблюдают за её состоянием в работе.
- Определяют границы доменов. Нужно понять, какие сущности и операции относятся к одному сервису, а какие — к другому.
- Описывают схемы подграфов. В схемы добавляют типы, поля и директивы федерации.
- Реализуют сервисы. Каждый сервис обрабатывает свои запросы, мутации и доступ к данным.
- Настраивают шлюз. Он получает схемы подграфов, собирает общую схему и принимает клиентские запросы.
- Разворачивают и проверяют систему. После запуска отслеживают ошибки, задержки и доступность сервисов.
Этот процесс редко бывает полностью механическим. Главное решение здесь — не выбор библиотеки, а корректное разделение ответственности между доменами. Если границы выбраны плохо, федерация не упростит архитектуру, а лишь перенесёт путаницу на новый уровень.
Какие преимущества даёт федерация GraphQL
Главное преимущество федерации — единый API поверх распределённой системы. Она позволяет масштабировать разработку по командам и сервисам, не заставляя клиентов разбираться во внутреннем устройстве платформы.
| Преимущество | Что это даёт |
| Разделение схемы | Каждая команда управляет своей областью данных отдельно |
| Единая точка входа | Клиент работает с одним GraphQL API вместо набора сервисов |
| Независимые релизы | Изменения в одном подграфе меньше затрагивают другие части системы |
| Лучшая читаемость доменов | Структура схемы ближе к устройству бизнеса и сервисов |
| Упрощение интеграции | Связанные данные можно получать одним запросом |
При этом преимущества проявляются не автоматически. Федерация полезна там, где уже есть несколько доменных сервисов или реальная потребность в независимой работе команд. Для маленькой схемы один сервер нередко оказывается проще.
Какие ограничения и риски есть у федерации
Федерация GraphQL упрощает работу с распределённой схемой, но добавляет отдельный слой координации. Чем больше подграфов и межсервисных связей, тем выше требования к проектированию, наблюдаемости и дисциплине изменений.
Первый риск связан с производительностью. Один клиентский запрос может превратиться в серию внутренних обращений между сервисами. Если связи описаны неудачно, задержка ответа вырастает.
Второй риск — схема начинает выглядеть цельной, хотя за ней стоит сеть зависимостей. Ошибка в одном подграфе или несовместимое изменение может затронуть общий API. Поэтому командам нужны понятные правила версионирования и проверки схем.
Есть и операционная сторона. Нужно следить не только за самими сервисами, но и за шлюзом, составлением схемы, трассировкой запросов и обработкой ошибок на стыке доменов.
Когда федерация GraphQL уместна, а когда нет
Федерация уместна, если данные и логика уже распределены между несколькими сервисами или командами, а клиентам нужен единый GraphQL API. Если система небольшая и схема компактная, монолитный GraphQL-сервер часто проще и дешевле в сопровождении.
Хороший сценарий для федерации — крупное приложение, где отдельные команды отвечают за каталог, аккаунты, платежи, заказы или контент. У каждой области свои данные, свой темп изменений и свой набор зависимостей.
Сомнительный сценарий — маленький проект, где одна команда поддерживает одну схему и не испытывает проблем с выпуском изменений. В таком случае федерация добавит новый уровень архитектуры без явной пользы.
Короткое правило можно сформулировать так: если проблема в масштабе доменов и команд, федерация помогает. Если проблемы пока нет, вводить её заранее обычно не требуется.
Кратко: что нужно запомнить о федерации GraphQL
Федерация GraphQL объединяет несколько GraphQL-сервисов в один API через общий шлюз и набор правил связи между схемами. Этот подход помогает строить распределённый граф данных, в котором команды развивают свои домены независимо, а клиент видит единую схему.
Её ценность особенно заметна в системах с несколькими сервисами и командами. Основные элементы здесь — подграфы, сервисы подграфов, директивы федерации и шлюз, который собирает общий граф и выполняет запросы между источниками данных.
