GraphQL Federation 완전 가이드 2025: Apollo Federation, Supergraph, 분산 GraphQL

[클라이언트]
    ↓
[GraphQL Server]
    ↓
[User Service] [Order Service] [Product Service] [...]

[Stitching Gateway]
    ├─ User Schema
    ├─ Order Schema
    └─ Product Schema

        [Apollo Router]
       /       |        \
[Users]    [Orders]   [Products]  ← 각 subgraph가 독립

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

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

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

type Order @key(fields: "id") {
  id: ID!
  total: Float!
  user: User!  # User entity 참조
}

# User를 확장 (extend가 v1, v2에서는 그냥 정의)
type User @key(fields: "id") {
  id: ID! @external
  orders: [Order!]!  # 새 필드 추가
}

// users-subgraph
const resolvers = {
  User: {
    __resolveReference(reference) {
      // reference = { id: "123" }
      return getUserById(reference.id)
    }
  }
}

Subgraph A schema  ─┐
Subgraph B schema  ─┼→ [Composition] → Supergraph schema
Subgraph C schema  ─┘

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

type Address {
  street: String!
  city: String!
  zipcode: String!
}

type Query {
  user(id: ID!): User
  me: User
}

type Product @key(fields: "id") {
  id: ID!
  name: String!
  description: String!
  price: Float!
  stock: Int!
}

type Query {
  product(id: ID!): Product
  products(category: String): [Product!]!
}

type Review @key(fields: "id") {
  id: ID!
  rating: Int!
  comment: String!
  productId: ID!
  authorId: ID!
}

# Product 확장
type Product @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!
  averageRating: Float!
}

# User 확장
type User @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!
}

query {
  user(id: "123") {
    name              # users-subgraph
    email             # users-subgraph
    reviews {         # reviews-subgraph
      rating
      comment
      product {       # products-subgraph
        name
        price
      }
    }
  }
}

[Client] → [Router]
              ↓
              ├─ users-subgraph: query user(id: 123)
              │       ↓
              │   { name, email, reviews: ??? }
              │
              ├─ reviews-subgraph: 
              │   __resolveReference: User { id: 123 }
              │   → return reviews
              │
              └─ products-subgraph:
                  __resolveReference: Product { id: 456 }
                  → return product details
              
[Router] → [Composes response] → [Client]

# 다운로드
curl -sSL https://router.apollo.dev/download/nix/latest | sh

# 실행
./router --config router.yaml --supergraph supergraph.graphql

supergraph:
  listen: 0.0.0.0:4000

cors:
  origins:
    - https://example.com

telemetry:
  metrics:
    prometheus:
      enabled: true
  tracing:
    otlp:
      enabled: true
      endpoint: http://otel-collector:4317

# Rover CLI
rover supergraph compose --config supergraph-config.yaml > supergraph.graphql

federation_version: 2
subgraphs:
  users:
    routing_url: http://users-service:4001
    schema:
      subgraph_url: http://users-service:4001
  products:
    routing_url: http://products-service:4002
    schema:
      subgraph_url: http://products-service:4002
  reviews:
    routing_url: http://reviews-service:4003
    schema:
      subgraph_url: http://reviews-service:4003

# CI에서 schema validation
rover subgraph check my-graph@prod \
  --schema users.graphql \
  --name users

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

# 복합 키
type Order @key(fields: "id userId") {
  id: ID!
  userId: ID!
  total: Float!
}

# 다중 key
type Product 
  @key(fields: "id")
  @key(fields: "sku") {
  id: ID!
  sku: String!
  name: String!
}

type User @key(fields: "id") {
  id: ID! @external
  reviews: [Review!]!  # 새 필드
}

type Product @key(fields: "id") {
  id: ID! @external
  weight: Float! @external
  shippingCost: Float! @requires(fields: "weight")
}

type Review @key(fields: "id") {
  id: ID!
  product: Product! @provides(fields: "name")
}

type Product @key(fields: "id") {
  id: ID! @external
  name: String! @external
}

# users-subgraph
type User @key(fields: "id") {
  id: ID!
  name: String! @shareable
}

# auth-subgraph
type User @key(fields: "id") {
  id: ID!
  name: String! @shareable  # 같은 필드, 둘 다 정의 가능
}

type User @key(fields: "id") {
  id: ID!
  name: String!
  internalNotes: String! @inaccessible  # supergraph에 노출 안 됨
}

- Database subgraph
- Cache subgraph
- Auth subgraph

- Users subgraph
- Orders subgraph
- Products subgraph
- Inventory subgraph
- Shipping subgraph

User entity → users-subgraph가 소유
  - id, name, email (소유 필드)
  
- orders-subgraph: User에 orders 필드 추가
- reviews-subgraph: User에 reviews 필드 추가

query {
  users {
    name
    orders {
      id
    }
  }
}

const orderLoader = new DataLoader(async (userIds) => {
  // 한 번의 쿼리로 여러 user의 orders 가져옴
  const orders = await db.query('SELECT * FROM orders WHERE user_id IN (?)', userIds)
  return userIds.map(id => orders.filter(o => o.user_id === id))
})

const resolvers = {
  User: {
    orders: (user) => orderLoader.load(user.id)
  }
}

authentication:
  router:
    jwt:
      jwks:
        - url: https://auth.example.com/.well-known/jwks.json

headers:
  all:
    request:
      - propagate:
          named: authorization

apollo_router_http_requests_total
apollo_router_http_request_duration_seconds
apollo_router_operations_total
apollo_router_session_count

telemetry:
  tracing:
    otlp:
      enabled: true
      endpoint: http://otel-collector:4317
    propagation:
      trace_context: true
      jaeger: true

[Router] (50ms)
├─ [users-subgraph] (10ms)
├─ [orders-subgraph] (30ms)
│   └─ [DB query] (25ms) ← 병목
└─ [Composition] (10ms)

# CI에서 변경 검증
rover subgraph check my-graph@prod \
  --schema new-schema.graphql \
  --name users

// Persisted query 등록
const queryId = "abc123"
const query = "query GetUser($id: ID!) { user(id: $id) { name } }"

// 클라이언트
fetch('/graphql', {
  body: JSON.stringify({
    extensions: {
      persistedQuery: {
        version: 1,
        sha256Hash: queryId
      }
    },
    variables: { id: "123" }
  })
})

# 기존 모놀리스
type Query {
  user(id: ID!): User
  product(id: ID!): Product
  order(id: ID!): Order
}

const resolvers = {
  Query: {
    user: async (_, { id }) => {
      const response = await fetch(`http://users-rest/users/${id}`)
      return response.json()
    }
  }
}