API / Mikroserwisy

GraphQL Federation

Jeden GraphQL endpoint dla setek mikroserwisów. Federation pozwala każdemu teamowi posiadać swój subgraph — a klienci widzą jeden unified graph bez wiedzy o wewnętrznej architekturze.

Apollo Federation 2

Standard

Apollo Router (Rust)

Router

Cosmo / Hive

Open-source alt.

Netflix, Airbnb

Używają

6 kluczowych konceptów Federation

Federation opiera się na kilku dyrektywach które pozwalają subgraphom współdzielić typy i dane.

@key directive

Definiuje unikalne pola identyfikujące entity między subgraphami (odpowiednik primary key)

type User @key(fields: 'id') { ... }

Entity extension

Jeden subgraph rozszerza typ zdefiniowany w innym — dodaje pola bez kopiowania całego typu

extend type User @key(fields: 'id') { orders: [Order!]! }

__resolveReference

Funkcja w subgrafie która pobiera entity po kluczu — wywoływana gdy gateway łączy dane

User: { __resolveReference: (ref) => db.findUser(ref.id) }

@shareable

Pole może być zdefiniowane w wielu subgraphach — oba mogą je zwracać

type Product @key(fields: 'id') { id: ID! @shareable name: String! }

@requires

Subgraph wymaga pola z innego subgrafu przed resolwowaniem własnego pola

@requires(fields: 'shippingAddress') estimatedDelivery: String

Supergraph SDL

Skompilowany unified schemat z wszystkich subgraphów — używany przez Router do planowania

rover supergraph compose --config supergraph.yaml

Ekosystem narzędzi GraphQL Federation

Od routera przez schema registry po code generation — pełny stack narzędzi dla produkcyjnego GraphQL.

Gateway / Router

Apollo Router (Rust)

Produkcyjny supergraph router — 10x szybszy niż Node.js gateway

Schema Registry

Apollo Studio / Cosmo / Hive

Wersjonowanie schematów, breaking change detection, schema checks w CI

Subgraph (Node.js)

@apollo/subgraph

Biblioteka do budowania Federation-compatible subgraphów

Code Generation

GraphQL Code Generator

Automatyczne TypeScript types, hooks, resolvers z SDL

Testing

Apollo Server testClient / MSW

Integration tests, mocking GraphQL API w testach

N+1 Solution

DataLoader / Prisma

Batching + caching requesty do bazy — eliminacja N+1 queries

Często zadawane pytania

Co to jest GraphQL Federation i jak różni się od standardowego GraphQL?

GraphQL Federation to podejście do budowania GraphQL API z wielu niezależnych serwisów (subgraphów) które są automatycznie łączone w jeden unified graph. W standardowym GraphQL: jeden serwer, jeden schemat. Gdy masz wiele mikroserwisów każdy ma własne API (REST lub GraphQL) — klient musi odpytywać wiele endpointów lub potrzebuje gateway. Federation rozwiązuje to przez: każdy mikroserwis definiuje swój własny GraphQL subgraph (np. serwis Users, serwis Products, serwis Orders). Gateway (supergraph) automatycznie łączy subgraphy w jeden schemat. Klient wysyła jedno zapytanie do gateway — gateway planuje wykonanie przez subgraphy. Kluczowe koncepty: @key directive — definiuje jak entity jest identyfikowalna między subgraphami. @external — pole zdefiniowane w innym subgrafie. @provides, @requires — optymalizacja które pola są potrzebne. Apollo Federation vs. GraphQL Mesh vs. Hive: Apollo Federation — standard de facto, wersje 1.x i 2.x. Używany przez Netflix, Airbnb. GraphQL Mesh — bardziej elastyczny, może federować REST/gRPC/GraphQL. Hive — cloud platform dla federation management. Zalety federation: team autonomy (każdy team posiada swój subgraph). Unified API dla klientów. Schema registry — centralna kontrola wersji schematu.

Apollo Federation — jak skonfigurować supergraph z subgraphami?

Apollo Federation składa się z: Subgraphs — indywidualne GraphQL serwisy (Node.js, Java, Python, Go). Router/Gateway — Apollo Router (Rust) lub @apollo/gateway (Node.js). Schema Registry — Apollo Studio lub self-hosted Hive/Cosmo. Setup subgraph (Node.js + @apollo/subgraph): instalacja @apollo/subgraph. buildSubgraphSchema() zamiast makeExecutableSchema(). Dodaj __resolveReference dla entity types. Dodaj directives (@key, @external, @shareable). Przykład — subgraph Users: type User @key(fields: 'id') { id: ID! name: String! email: String! }. Subgraph Orders może rozszerzyć User: extend type User @key(fields: 'id') { id: ID! @external orders: [Order!]! }. Apollo Router (Rust): superlekki, wydajny router w Rust. Zastąpił @apollo/gateway (Node.js) — 10x szybszy. Supergraph schema: kompozycja przez rover CLI lub Apollo Studio. rover supergraph compose --config supergraph.yaml. Supergraph SDL — skompilowany unified schema. Cosmo (WunderGraph): open-source alternatywa dla Apollo Federation. Schema Registry, Router, Studio — self-hostable. Bardzo aktywny rozwój (2023-2024). Persisted Queries: wysyłaj ID zapytania zamiast pełnego tekstu. Bezpieczeństwo + wydajność (mniejszy payload).

GraphQL vs. REST vs. gRPC — kiedy wybrać GraphQL?

REST: proste, szeroko rozumiane, świetne dla publicznego API. Over-fetching (dostajesz więcej pól niż potrzebujesz) i under-fetching (potrzebujesz kilku requestów dla złożonych danych) jako główne problemy. GraphQL: klient definiuje dokładnie jakich pól potrzebuje. Jeden endpoint dla wszystkich zapytań. Introspection — samodokumentujące API. Subscriptions dla real-time. Silnie typowany schemat. Wyzwania GraphQL: N+1 problem — każde zapytanie może generować wiele zapytań do bazy (rozwiązanie: DataLoader). Caching trudniejszy vs. REST (brak URL per resource). File upload niestandardowy (multipart). Rate limiting bardziej skomplikowane. gRPC: binarny protokół (Protocol Buffers), bardzo szybki. Idealny dla wewnętrznej komunikacji mikroserwisów. Streaming (unary, server streaming, client streaming, bidirectional). Kiedy GraphQL: frontend potrzebuje elastycznych zapytań (różne widoki mają różne potrzeby danych). Rapid product development — frontend nie czeka na nowe endpointy. Aggregation z wielu źródeł (federation). Mobile apps — optymalizacja ilości danych. Kiedy REST lepszy: publiczne API (REST powszechnie znane). Simple CRUD bez złożonych relacji. Kiedy gRPC lepszy: internal mikroserwisy, performance critical paths, streaming.

DataLoader i N+1 problem w GraphQL — jak rozwiązać?

N+1 problem: zapytanie GraphQL które pobiera listę postów i dla każdego pobiera autora. Naiwna implementacja: 1 query dla listy postów + N queries dla autorów. DataLoader (Facebook): batching + caching requesty do bazy danych. Zamiast N osobnych SELECT WHERE id=X → jeden SELECT WHERE id IN (1,2,3,...N). Caching w ramach jednego requesta — ten sam użytkownik pobierany raz. Implementacja: const userLoader = new DataLoader(async (userIds) => { const users = await db.query('SELECT * FROM users WHERE id IN (?)', [userIds]); return userIds.map(id => users.find(u => u.id === id)); }). W resolverze: author: (post) => userLoader.load(post.authorId). Persistent resolvers: DataLoader instance na request — nie globalny (unikaj cache poisoning). Inne strategie: Join Monster — automatyczny SQL join generator dla GraphQL. Prisma — ORM który rozwiązuje N+1 przez query batching. Strawberry (Python) + dataclasses. Schema-first vs. Code-first: Schema-first — definiujesz SDL, generujesz typy. Code-first (Nexus, TypeGraphQL, Strawberry) — definiujesz w kodzie, generujesz SDL. Query complexity limits: analizuj złożoność zapytania przed wykonaniem. Odrzuć zapytania przekraczające threshold. Persisted Operations — whitelist dozwolonych zapytań.

Jak wdrożyć GraphQL w produkcji — security, monitoring, schema evolution?

Security w GraphQL produkcji: Depth limiting — ogranicz głębokość zapytania (chroni przed recursive queries). Amount limiting — maksymalna liczba zwracanych elementów. Query complexity limits. Persisted operations (whitelist). Introspection wyłączona na produkcji (lub ograniczona). Disable field suggestions (ujawniają schemat). Authentication: JWT validation w middleware (przed resolverami). Context object na request z decoded user. Authorization: field-level (sprawdź czy user ma dostęp do pola). Object-level (czy user może czytać tego zasobu). Monitoring: Apollo Studio / Cosmo — trace każde zapytanie per operacja. Response time per field, error rate, usage stats. OpenTelemetry — instrumentacja standardowa. Schema Evolution (schema registry): schemat jest kontraktem z klientami. Breaking changes: usunięcie pola, zmiana typu, zmiana argumentu. Non-breaking: dodanie pola, dodanie opcjonalnego argumentu. Schema diff w CI/CD — automatyczne wykrywanie breaking changes (rover). Schema registry (Apollo Studio, Hive, Cosmo) — wersjonowanie i deployment kontrola. SDL first approach: schemat jako source of truth, generuj typy po stronie klienta i serwera. GraphQL Code Generator — automatyczne typy TypeScript/Java/Python ze schematu. Subgraph testing: unit tests resolverów. Integration tests z Apollo Server testClient. Contract tests między subgraphami.

Czytaj dalej