Desain GraphQL Federation dan Schema Stitching untuk Layanan Microservices Modern

1. Konteks Industri & Analisis Akar Masalah

Dalam lanskap pengembangan aplikasi web modern, arsitektur microservices telah menjadi standar emas untuk organisasi skala enterprise yang menuntut skalabilitas horizontal, pemisahan tanggung jawab (separation of concerns), dan otonomi tim. Namun, seiring bertambahnya jumlah layanan—mulai dari manajemen pengguna (User Service), katalog produk (Product Service), manajemen pesanan (Order Service), hingga sistem pembayaran (Payment Service)—tantangan baru yang masif muncul di sisi konsumsi klien (Client-side consumption).

Pada masa-masa awal adopsi RESTful API, arsitektur ini sering kali memicu pola API Gateway tradisional atau Backend for Frontend (BFF) yang kaku. Ketika aplikasi klien (seperti SPA React, Vue, atau aplikasi seluler native) membutuhkan data teragregasi dari berbagai microservices, klien terpaksa melakukan multiple round-trips HTTP. Masalah ini dikenal sebagai Over-fetching dan Under-fetching. Pengembang sering kali menulis kode agregasi yang rapuh di dalam API Gateway berbasis Node.js atau Go, yang akhirnya menjadi bottleneck tunggal dan pusat kegagalan (single point of failure).

Di sinilah GraphQL masuk sebagai penyelamat. GraphQL memungkinkan klien untuk meminta tepat apa yang mereka butuhkan dalam satu permintaan tunggal. Namun, seiring berkembangnya perusahaan, monolitisasi skema GraphQL di satu repositori terpusat kembali menciptakan masalah bottleneck organisasi. Tim pengembang dari berbagai domain tidak dapat mendeploy skema mereka secara independen tanpa merusak deployment pipeline tim lain.

Perbandingan Kondisi: Sebelum vs Sesudah Penerapan

2. Konsep Inti & Deep Dive Arsitektur

Untuk memahami arsitektur GraphQL Federation (khususnya spesifikasi Apollo Federation v2), kita harus melihat bagaimana sebuah router pusat menggabungkan beberapa Subgraph (layanan microservices mandiri yang mengekspos endpoint GraphQL mereka sendiri) menjadi satu Supergraph yang koheren.

Berbeda dengan Schema Stitching tradisional yang menggabungkan skema melalui fungsi delegasi manual yang rentan terhadap inkonsistensi, Federation menggunakan arahan khusus (directives) seperti @key, @extends, @external, @requires, dan @provides untuk membangun grafik terdistribusi secara deklaratif.

Alur Eksekusi & Visualisasi Arsitektur (Under the Hood)

Perhatikan diagram ASCII alur eksekusi permintaan (request flow) di bawah ini:

+-----------------------------------------------------------------------------------+
|                           CLIENT (Browser / Mobile App)                           |
+-----------------------------------------------------------------------------------+
          |
          | 1. HTTP POST /graphql (Query Kompleks: User + Orders + Products)
          v
+-----------------------------------------------------------------------------------+
|                        EDGE / WAF & NGINX REVERSE PROXY                           |
|               (SSL Termination, Rate Limiting, Fail2ban, Cloudflare CDN)            |
+-----------------------------------------------------------------------------------+
          |
          | 2. Internal Upstream Routing
          v
+-----------------------------------------------------------------------------------+
|                           APOLLO ROUTER (Supergraph)                              |
|        - Parsing & Validation Query                                               |
|        - Query Planning (Menghasilkan Execution Plan)                             |
|        - Distributed Tracing & Telemetry (OpenTelemetry)                          |
+-----------------------------------------------------------------------------------+
          |                          |                          |
          | 3a. Fetch User Data      | 3b. Fetch Orders         | 3c. Fetch Products
          v                          v                          v
+--------------------+     +--------------------+     +--------------------+
|   USER SUBGRAPH    |     |   ORDER SUBGRAPH   |     |  PRODUCT SUBGRAPH  |
| (Node.js / Express)|     |     (Go / Gin)     |     |    (PHP / Swoole)  |
+--------------------+     +--------------------+     +--------------------+
          |                          |                          |
          v                          v                          v
+--------------------+     +--------------------+     +--------------------+
|    MySQL / MariaDB |     |    Redis Cluster   |     |     AWS S3 / CDN   |
+--------------------+     +--------------------+     +--------------------+

Cara Kerja Detail di Balik Layar:

1. Query Parsing: Klien mengirimkan query kompleks ke API Gateway (Apollo Router yang ditulis dalam bahasa Rust untuk performa tinggi).
2. Query Planning: Router memecah query tersebut menjadi beberapa operasi yang lebih kecil (sub-operations) berdasarkan pemetaan entitas yang didefinisikan dalam skema subgraf.
3. Parallel Fetching: Router mengirimkan permintaan HTTP/GraphQL secara paralel ke subgraf terkait (misalnya, mengambil data dasar pengguna dari User Subgraph, lalu menggunakan ID pengguna tersebut untuk meminta daftar pesanan dari Order Subgraph).
4. Entity Resolution: Menggunakan direktif @key(fields: "id"), router mengetahui bagaimana mereferensikan entitas lintas layanan. Jika Order Subgraph mengembalikan userId, router dapat meminta User Subgraph untuk memperkaya data tersebut dengan nama dan email pengguna secara transparan.
5. Response Aggregation: Router menggabungkan seluruh hasil respons dari berbagai subgraf ke dalam struktur JSON tunggal sesuai dengan bentuk query yang diminta oleh klien.

3. Perbandingan Komparatif / Analisis Pendekatan

Dalam membangun arsitektur data terdistribusi berbasis GraphQL, terdapat dua pendekatan utama yang sering diperdebatkan: GraphQL Federation vs Schema Stitching. Berikut adalah analisis perbandingan komparatif secara mendalam.

[!WARNING] Hindari menggunakan Schema Stitching pada proyek baru kecuali Anda sedang melakukan migrasi bertahap dari monolit REST lama ke GraphQL dan terikat oleh keterbatasan teknologi legacy tertentu. Selalu prioritaskan GraphQL Federation untuk arsitektur microservices baru.

4. Prasyarat Sistem & Persiapan Lingkungan

Sebelum menyelam ke dalam implementasi teknis, pastikan infrastruktur dan lingkungan pengembangan Anda memenuhi spesifikasi enterprise berikut:

Spesifikasi Lingkungan Produksi

• OS: Ubuntu Server 22.04 LTS / Debian 12 Bookworm
• Runtime & Bahasa: Node.js v20+ LTS (untuk User Subgraph), Go 1.22+ (untuk Order Subgraph)
• Gateway Router: Apollo Router (binary native Rust)
• Web Server / Reverse Proxy: Nginx (1.24+) dengan SSL/TLS Let's Encrypt
• Caching & Rate Limiting: Redis Cluster (v7.0+)
• Database: MySQL 8.0+ / MariaDB 10.11+

Verifikasi Awal & Dependensi Sistem

Jalankan perintah berikut di server Linux Anda untuk memastikan dependensi dasar terinstal dengan benar:

# Update sistem dan instalasi utilitas dasar
sudo apt update && sudo apt upgrade -y
sudo apt install -y curl git build-essential ufw fail2ban nginx redis-server

# Verifikasi versi Node.js
node -v # Harus v20.x atau lebih tinggi

# Verifikasi versi Go
go version # Harus v1.22.x atau lebih tinggi

5. Panduan Implementasi Langkah demi Langkah

Pada bagian ini, kita akan membangun dua subgraf sederhana (User Subgraph berbasis Node.js/Express dan Order Subgraph berbasis Go/Gin) serta mengonfigurasikannya ke dalam satu Apollo Router.

Langkah 1: Implementasi User Subgraph (Node.js + Apollo Server)

Buat direktori proyek untuk User Subgraph dan inisialisasi:

mkdir -p /var/www/graphql-services/user-subgraph
cd /var/www/graphql-services/user-subgraph
npm init -y
npm install @apollo/server graphql express cors body-parser

Buat file server.js dengan kode lengkap di bawah ini:

const { ApolloServer } = require('@apollo/server');
const { expressMiddleware } = require('@apollo/server/express4');
const { buildSubgraphSchema } = require('@apollo/subgraph');
const { gql } = require('graphql-tag');
const express = require('express');
const cors = require('cors');
const bodyParser = require('body-parser');

// Database Mock untuk User
const users = [
  { id: '1', name: 'Alice Enterprise', email: 'alice@enterprise.com' },
  { id: '2', name: 'Bob Architect', email: 'bob@enterprise.com' },
];

const typeDefs = gql`
  extend schema @link(url: "https://specs.apollo.tech/federation/v2.0", import: ["@key"])

  type User @key(fields: "id") {
    id: ID!
    name: String!
    email: String!
  }

  type Query {
    user(id: ID!): User
    users: [User!]
  }
`;

const resolvers = {
  Query: {
    user: (_, { id }) => users.find(u => u.id === id),
    users: () => users,
  },
  User: {
    __resolveReference(reference) {
      return users.find(u => u.id === reference.id);
    },
  },
};

async function startServer() {
  const app = express();
  const server = new ApolloServer({
    schema: buildSubgraphSchema({ typeDefs, resolvers }),
  });

  await server.start();

  app.use(
    '/graphql',
    cors(),
    bodyParser.json(),
    expressMiddleware(server),
  );

  app.listen(4001, () => {
    console.log(`🚀 User Subgraph running at http://localhost:4001/graphql`);
  });
}

startServer();

Langkah 2: Implementasi Order Subgraph (Go + Gin + gqlgen/manual)

Buat direktori untuk Order Subgraph:

mkdir -p /var/www/graphql-services/order-subgraph
cd /var/www/graphql-services/order-subgraph
go mod init order-subgraph

Buat file main.go dengan implementasi server HTTP sederhana yang merespons skema federasi Order:

package main

import (
	"encoding/json"
	"fmt"
	"net/http"
)

type Order struct {
	ID     string `json:"id"`
	Total  float64 `json:"total"`
	UserID string `json:"userId"`
}

var orders = []Order{
	{ID: "ord-101", Total: 150.50, UserID: "1\