Реалізація GraphQL Federation для об'єднання мікросервісів

Реалізація GraphQL Federation для об'єднання мікросервісів

Уявіть: фронтенд-команда витрачає години на координацію з бекендерами, щоб зібрати одну сторінку. Кожен мікросервіс віддає дані у своєму форматі — доводиться робити 5–10 запитів до різних API. Виникають N+1 проблеми, latency зростає, кешування перетворюється на головний біль. На одному з проєктів ми скоротили кількість запитів з 12 до 2, впровадивши Federation. Наш досвід — 7+ років у розподілених системах, понад 50 продакшен-впроваджень GraphQL. Федерація — це не просто gateway, а декларативний підхід: кожна команда описує, як її мікросервіс розширює загальний граф даних. На відміну від ручного агрегування, Federation автоматично будує оптимальний план виконання, використовуючи @key та @requires.

Як об'єднати мікросервіси за допомогою GraphQL Federation?

Federation дозволяє об'єднати декілька незалежних GraphQL-сервісів (subgraph) в єдиний API. Клієнт робить один запит до Federation Gateway (Apollo Router), який збирає дані з різних subgraph і повертає єдину відповідь. Кожна команда володіє своїм subgraph і деплоїть його незалежно — без блокувань і узгоджень. Детальна специфікація доступна в документації Apollo Federation.

Архітектура Federation:

• Клієнт (браузер/мобільний) → Federation Gateway (Apollo Router / Apollo Gateway)
  • User Subgraph (Node.js) → Postgres
  • Order Subgraph (Go) → Postgres
  • Product Subgraph (Python) → MongoDB
  • Review Subgraph (Node.js) → Postgres

  Subgraph: User Service — приклад реалізації

  // user-service/schema.ts
  import { buildSubgraphSchema } from '@apollo/subgraph';
  import { gql } from 'graphql-tag';
  
  const typeDefs = gql`
    extend schema @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@key", "@shareable"])
  
    type User @key(fields: "id") {
      id: ID!
      name: String!
      email: String!
      createdAt: DateTime!
    }
  
    type Query {
      me: User
      user(id: ID!): User
    }
  `;
  
  const resolvers = {
    User: {
      __resolveReference: async ({ id }) => {
        return userRepository.findById(id);
      }
    },
    Query: {
      me: (_, __, { userId }) => userRepository.findById(userId),
      user: (_, { id }) => userRepository.findById(id)
    }
  };
  
  export const schema = buildSubgraphSchema({ typeDefs, resolvers });
  

  Subgraph: Order Service — розширення типів

  // order-service/schema.ts
  const typeDefs = gql`
    extend schema @link(url: "https://specs.apollo.dev/federation/v2.3", import: ["@key", "@external", "@requires"])
  
    type Order @key(fields: "id") {
      id: ID!
      status: OrderStatus!
      total: Float!
      items: [OrderItem!]!
      customer: User!
      createdAt: DateTime!
    }
  
    type User @key(fields: "id") {
      id: ID! @external
      orders(limit: Int = 10): [Order!]!
      orderStats: OrderStats!
    }
  
    type OrderStats {
      totalOrders: Int!
      totalSpent: Float!
      lastOrderAt: DateTime
    }
  
    enum OrderStatus {
      PENDING
      PAID
      SHIPPED
      DELIVERED
      CANCELLED
    }
  
    type Query {
      order(id: ID!): Order
      orders(customerId: ID, status: OrderStatus): [Order!]!
    }
  `;
  
  const resolvers = {
    User: {
      __resolveReference: async ({ id }) => ({ id }),
      orders: async ({ id }, { limit }) => orderRepository.findByCustomerId(id, limit),
      orderStats: async ({ id }) => orderRepository.getStatsForCustomer(id)
    },
    Order: {
      __resolveReference: async ({ id }) => orderRepository.findById(id),
      customer: ({ customerId }) => ({ __typename: 'User', id: customerId })
    }
  };

  Apollo Router (Federation Gateway) — конфігурація

  ---
  # router.yaml
  federation_version: 2.3
  supergraph:
    listen: 0.0.0.0:4000
    subgraphs:
      users:
        routing_url: http://user-service:4001/graphql
      orders:
        routing_url: http://order-service:4002/graphql
      products:
        routing_url: http://product-service:4003/graphql
  cors:
    origins:
      - https://app.example.com
  headers:
    all:
      request:
        - propagate:
            named: Authorization
        - propagate:
            named: X-Correlation-Id
  ---
  

  Запуск через Docker: docker run -p 4000:4000 -v $(pwd)/router.yaml:/dist/config/router.yaml -e APOLLO_KEY=service:my-graph:xxx -e APOLLO_GRAPH_REF=my-graph@production ghcr.io/apollographql/router:latest.

  Що дає Federation порівняно з REST і звичайним Gateway?

  Характеристика	Federation	REST-агрегатор	Звичайний Gateway
  Кількість запитів	1	5–10	1 (але дані збираються послідовно)
  Час відповіді	~50 мс (паралельні запити)	~200 мс	~100–150 мс (послідовно)
  Незалежність команд	✅ Кожна команда володіє subgraph	❌ Спільна кодова база	❌ Спільна кодова база
  Зміна схеми	Без блокувань	Узгодження	Узгодження
  Кешування	На рівні subgraph	HTTP-кеш	Централізоване

  Federation дозволяє підвищити продуктивність у 2–3 рази порівняно з REST-агрегатором за рахунок паралельної вибірки та кешування на рівні subgraph. На одному проєкті ми знизили час завантаження сторінки з 2.3 до 0.8 секунди — це в 2.9 рази швидше.

  Інструмент	Призначення	Розповсюдження
  Apollo Router	Federation Gateway, паралельний збір даних	Open source + Managed Apollo
  Rover CLI	Публікація та перевірка схем	Open source
  Apollo Studio	Реєстр схем, моніторинг	SaaS

  Managed Federation (Apollo Studio)

  При Managed Federation схеми subgraph публікуються в Apollo Studio Registry. Router завантажує актуальну supergraph-схему автоматично при зміні будь-якого subgraph. Публікація з перевіркою сумісності виконується через rover subgraph check.

  # В CI/CD пайплайні rover subgraph publish my-graph@production \
  --schema ./schema.graphql \
  --name orders \
  --routing-url http://order-service:4002/graphql

  Авторизація на рівні subgraph

  Кожен subgraph самостійно перевіряє права. Приклад на TypeScript: в ресолвері Order __resolveReference перевіряється, що поточний користувач — власник замовлення або має роль admin. У разі відмови повертається помилка ForbiddenError.

  Чому Federation варто обрати для нового проєкту?

  Federation дає незалежність командам, атомарні деплої та автоматичну перевірку сумісності. Ми гарантуємо, що схема залишиться консистентною при кожній зміні. Це найкраще рішення для компаній з 3+ мікросервісами, де важлива швидкість змін.

  Що входить в роботу?

  • Аудит поточної архітектури та виділення меж subgraph.
  • Проектування supergraph-схеми з @key та @requires.
  • Реалізація subgraph-сервісів (Node.js, Go, Python — будь-який стек).
  • Налаштування Apollo Router з CORS, авторизацією, моніторингом.
  • Інтеграція Managed Federation з CI-пайплайном перевірки сумісності.
  • Документація по схемі та точках розширення.
  • Навчання команди роботі з Federation.
  • Підтримка на старті: 2 тижні після запуску.

  Процес роботи та терміни

  1. Аналіз — виділяємо межі subgraph, визначаємо точки інтеграції з legacy.
  2. Проектування — описуємо supergraph-схему, узгоджуємо @key та @requires.
  3. Розробка — кожен subgraph створюється як окремий сервіс з власним деплоєм.
  4. Налаштування Router — конфігурація CORS, авторизації, моніторингу (Apollo Studio).
  5. Managed Federation — підключаємо CI-пайплайн з перевіркою сумісності.
  6. Тестування — навантажувальне тестування та E2E-тести.
  7. Запуск — покроковий rollout з моніторингом помилок.

  Терміни реалізації:

  • 2–3 subgraph з базовою Federation — 2–3 тижні.
  • Apollo Router + Managed Federation + CI-перевірки сумісності — ще 1 тиждень.
  • Складні @requires, @provides, nested resolvers — 1–2 додаткові тижні.

  Вартість розраховується індивідуально після аналізу вашого проєкту. Орієнтовний бюджет від $5000 для базового впровадження. Отримайте консультацію — ми оцінимо обсяг роботи і запропонуємо оптимальне рішення. Команда має 7+ років досвіду та виконала 50+ проєктів. Замовте впровадження Federation: зв'яжіться з нами — підготуємо пропозицію під ключ. Ваша архітектура стане гнучкою та масштабованою без зайвих витрат.

  Приклад детальної реалізації subgraph на TypeScript

  Весь код User та Order subgraph доступний у репозиторії. При необхідності адаптуємо під ваш стек.

  Отримайте консультацію по впровадженню Federation — напишіть нам, і ми оцінимо ваш проєкт.