マイクロサービスのAPI地獄
マイクロサービスアーキテクチャの最大の課題はAPI統合だ。10個のサービスがそれぞれRESTエンドポイントを公開すると、フロントエンドは1画面の表示に5-8個のAPIを呼ぶことになる。BFF（Backend for Frontend）パターンで集約しても、BFF自体がモノリシックなボトルネックになる。この問題を根本的に解決するのがGraphQL Federationだ。
Apollo Federation v2は2023年にGAとなり、2025年現在、エンタープライズでの採用が急速に進んでいる。KGAの大規模クライアント3社でFederation v2を導入した経験から、設計パターンと落とし穴を共有する。
アーキテクチャ概要
Federation v2は「サブグラフ」と「スーパーグラフ」の2層構造だ。各マイクロサービスが自身のドメインに対応するGraphQLスキーマ（サブグラフ）を公開し、Apollo Routerがそれらを合成して単一のGraphQLエンドポイント（スーパーグラフ）として提供する。
フロントエンドはスーパーグラフに対して1つのクエリを発行するだけで、複数サービスにまたがるデータを取得できる。例えば「ユーザー情報 + 注文履歴 + レコメンデーション」を1回のGraphQLクエリで取得する。Routerが内部的にクエリプランを生成し、必要なサブグラフに並列リクエストを発行して結果をマージする。
サブグラフ設計の原則
サブグラフ設計で最も重要なのは「エンティティの所有権」だ。Userエンティティはユーザーサービスが所有し、@keyディレクティブでIDフィールドを指定する。他のサブグラフ（注文サービス等）はUserを参照するが、所有はしない。
KGAの設計ルール: 1エンティティの@key定義は1つのサブグラフのみ。フィールドの追加（@extends）は任意のサブグラフから可能。共有型（enum、input type等）はshared subgraphに集約。サブグラフ間の循環参照は禁止（ビルド時にlintで検出）。
実例として、KGAのクライアントの構成を示す。ユーザーサブグラフ（User, Profile, Authentication）、商品サブグラフ（Product, Category, Inventory）、注文サブグラフ（Order, Payment, Shipping）、レコメンドサブグラフ（Recommendation, UserPreference）、検索サブグラフ（SearchResult, Filter）。5つのサブグラフで構成され、各チームが独立してスキーマを進化させられる。
スキーマ合成とRouter設定
Apollo Router（Rust実装）はサブグラフのスキーマを合成してスーパーグラフを生成する。合成プロセスはApollo Studio（SaaS）またはrover CLIでローカル実行できる。KGAではCI/CDパイプラインにrover supergraph composeを組み込み、PRごとにスキーマ合成の検証を行っている。
Router設定で重視しているのはQuery Plan Caching。同一クエリ構造のリクエストに対してクエリプランを再利用し、プランニングのCPUコストを削減する。KGAの本番環境ではキャッシュヒット率98%を達成しており、Routerのp99レイテンシは12msに抑えられている。
Routerのパフォーマンスは優秀だ。Apollo Router（Rust実装）は旧Apollo Gateway（Node.js実装）と比較して、スループットが8倍、レイテンシが1/5。KGAの本番環境では、Routerインスタンス2台（4vCPU, 8GB RAM）で毎秒3,000リクエストを処理している。
RESTからの段階的移行
既存のRESTマイクロサービスをFederationに移行する際、ビッグバン移行は避けるべきだ。KGAが推奨する段階的移行ステップを示す。
Phase 1（2-3週間）: REST APIの前にGraphQLラッパーを配置。既存RESTエンドポイントはそのまま維持し、GraphQLサブグラフがRESTを内部的に呼び出す。Phase 2（4-6週間）: フロントエンドをGraphQLクライアントに移行。Apollo ClientまたはurqlでREST呼び出しを順次置き換え。Phase 3（6-8週間）: サブグラフの内部実装をREST呼び出しからデータソース直接アクセスに変更。Phase 4（継続的）: 不要になったRESTエンドポイントを段階的に廃止。
この移行パターンでは、Phase 1-2の期間中もRESTとGraphQLが共存するため、ロールバックが常に可能だ。KGAのクライアントでは平均3ヶ月で移行を完了し、フロントエンドのAPI呼び出し数を平均72%削減した。
モニタリングとトラブルシューティング
Federation環境のモニタリングで重要なメトリクスは、サブグラフ別レイテンシ（どのサービスがボトルネックか特定）、クエリプラン実行時間、サブグラフ間のN+1問題の検出、スキーマ合成エラーの早期発見。Apollo StudioのOperation Tracesで各サブグラフへのリクエストフローを可視化できるが、KGAではOpenTelemetry連携でDatadogにトレースを送り、既存の監視基盤と統合している。
最も多いトラブルはN+1問題だ。1つのUserに紐づく注文リストを取得する際、注文ごとにユーザーサブグラフへリクエストが発生するケース。DataLoaderパターンでバッチ化するのが定石だが、Federation環境ではRouter側の@requires指定を活用して、必要なフィールドを1回のリクエストで取得する設計が望ましい。