Belajar GraphQL - Membangun Distributed Schema dengan Federation

#Pendahuluan

Seiring pertumbuhan tim dan domain, satu schema raksasa menjadi hambatan: setiap perubahan butuh koordinasi semua orang. Episode 22 memperkenalkan Apollo Federation — arsitektur yang memecah schema menjadi subgraph yang dimiliki masing-masing tim, lalu disatukan menjadi satu supergraph.

Kita akan mempelajari konsep supergraph dan gateway, direktif kunci Federation 2, cara membangun subgraph, setup Apollo Gateway dengan query planning, dan strategi migrasi bertahap dari monolith.

#Federation Concepts

#Monolith vs Federated GraphQL

Dalam federated GraphQL, setiap domain (user, product, order) menjadi subgraph — service GraphQL yang berdiri sendiri dengan schema parsialnya. Semua subgraph digabung oleh gateway menjadi supergraph yang dilihat client sebagai satu endpoint.

client -> gateway -> subgraph users
                  -> subgraph products
                  -> subgraph orders

Keuntungannya: setiap tim memiliki schema-nya sendiri, deploy independen, dan skala per-domain. Tantangannya: komposisi schema antar-service perlu aturan yang jelas — di sinilah direktif federation berperan.

#Apollo Federation 2

#Direktif Kunci

Federation 2 (versi stabil terbaru) menyederhanakan komposisi dengan direktif:

• @key(fields: "id"): menandai field unik sebagai referensi entitas lintas subgraph.
• @shareable: field yang boleh didefinisikan beberapa subgraph.
• @override(from: "OtherSubgraph"): mengambil alih implementasi field dari subgraph lain.
• @interfaceObject: memungkinkan subgraph menyumbang field ke interface.

type Product @key(fields: "upc") {
  upc: String!
  name: String!
  price: Int!
}
 
type Query {
  products: [Product!]!
}

#Entity References dan Extends

Subgraph lain bisa memperluas entitas Product tanpa memiliki datanya:

type Product @key(fields: "upc") {
  upc: String! @external
  reviews: [Review!]! @requires(fields: "upc")
}
 
type Review {
  id: ID!
  body: String!
  rating: Int!
}

Pola ini adalah kekuatan federation: service reviews tahu upc saja, dan gateway yang mengumpulkan data lengkap saat query membutuhkan keduanya.

#Building Subgraphs

#Membangun Subgraph dengan Apollo

Setiap subgraph adalah server Apollo biasa, dibangun dengan buildSubgraphSchema:

npm install @apollo/subgraph

Subgraph server

import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
import { buildSubgraphSchema } from "@apollo/subgraph";
 
const schema = buildSubgraphSchema({ typeDefs, resolvers });
 
const server = new ApolloServer({ schema });
const { url } = await startStandaloneServer(server, { listen: { port: 4002 } });
console.log("Subgraph products di", url);

Subgraph diekspos ke gateway lewat URL-nya, beserta introspect schema-nya. Setiap subgraph butuh resolver __resolveReference untuk entity yang bisa di-refer subgraph lain:

Resolver __resolveReference

const resolvers = {
  Product: {
    __resolveReference(ref, ctx) {
      return ctx.db.products.findByUpc(ref.upc);
    },
  },
  Query: {
    products: (_, __, ctx) => ctx.db.products.findAll(),
  },
};

#Apollo Gateway

#Setup Gateway dan Query Planning

Gateway menggabungkan subgraph. Pertama install lewat npm install @apollo/gateway @apollo/server, lalu definisikan daftar subgraph:

Gateway dengan dua subgraph

import { ApolloGateway } from "@apollo/gateway";
import { ApolloServer } from "@apollo/server";
import { startStandaloneServer } from "@apollo/server/standalone";
 
const gateway = new ApolloGateway({
  supergraphSdl: `
    schema @link(url: "https://specs.apollo.dev/federation/v2.3") {
      query: Query
    }
    extend schema
      @link(url: "https://specs.apollo.dev/federation/v2.3",
            import: ["@key", "@shareable"])
  `,
  subgraphs: {
    users: { url: "http://localhost:4001" },
    products: { url: "http://localhost:4002" },
  },
});
 
const server = new ApolloServer({ gateway });
const { url } = await startStandaloneServer(server, { listen: { port: 4000 } });

Gateway melakukan dua hal penting: composition (menyatukan subgraph jadi supergraph) dan query planning (membagi satu query client menjadi panggilan ke subgraph yang tepat). Client hanya berurusan dengan gateway — endpoint supergraph.

#Federation Patterns dan Migrasi

#Pola Umum dan Monitoring

Pola yang sering dipakai: value types (objek sederhana yang tidak memiliki identity sendiri, bisa di-@shareable) versus entities (yang punya @key). Untuk monitoring, gateway dan setiap subgraph bisa mengirim tracing ke Apollo Studio sehingga perjalanan query antar-service terlihat.

#Migrasi Monolith ke Federation

Migrasi bertahap agar tidak mengganggu client:

1. Pisahkan satu domain menjadi subgraph, tetap di-load dalam monolith dulu.
2. Setelah stabil, pindahkan subgraph ke service terpisah.
3. Ulangi per domain; gateway mengabstraksi perubahan dari client.

Pendekatan incremental ini dipakai banyak perusahaan — dan akan kita bedah lagi dalam konteks microservices di episode 36.

#Penutup

Inti yang harus dibawa pulang:

• Federation memecah schema menjadi subgraph yang dimiliki masing-masing tim.
• @key menandai referensi entitas; @external dan @requires memungkinkan perluasan lintas subgraph.
• @shareable dan @override mengatur kepemilikan field di Federation 2.
• Setiap subgraph dibangun dengan buildSubgraphSchema dan __resolveReference.
• Gateway menyatukan subgraph lewat composition dan memecah query lewat query planning.
• Migrasi monolith ke federation dilakukan bertahap per domain.

Di episode 23 selanjutnya kalian akan mempelajari GraphQL Code Generator dan type safety — instalasi dan konfigurasi codegen, generasi tipe TypeScript dari schema, generasi hook React yang typed, type-safe resolvers dan context, hingga integrasi watch mode dan pre-commit hooks. Type safety end-to-end akan kalian rasakan!