LASSIC Media らしくメディア

LASSIC IT事業部｜元請（プライムベンダー）としてシステム保守・運用を受託

GraphQL Federationとは — 複数グラフを1つの統合グラフにする仕組み

GraphQL Federationとは、複数のサービスがそれぞれ持つGraphQL APIを、1つのルーター（router）を介して単一の統合グラフ（スーパーグラフ）としてクライアントに提示する仕組みを指します。Apollo GraphQLの公式ドキュメントでは、複数のAPIを「宣言的に組み合わせ、単一の統合されたGraphQL API」にする仕組みとして説明されています^*1。

クライアントから見ると、問い合わせ先は1つのエンドポイントだけです。裏側ではルーターが複数のサブグラフ（subgraph、Federationを構成する個々のGraphQL API）へリクエストを振り分け、結果を1つのレスポンスにまとめて返します^*1。この記事では、複数のGraphQL APIを1つのグラフへ統合する「連合アーキテクチャ」としてのFederationに焦点を当てます。GraphQL自体の基本仕様やRESTからの移行については別稿で扱っているため、本稿ではFederation固有の仕組みと外注時の論点に絞って解説します。

なぜ必要か — サービスごとのGraphQLが抱える単一エンドポイント問題

マイクロサービス構成の組織では、サービスごとに個別のGraphQL APIを持つケースが珍しくありません。ユーザー管理・注文・レビューのように機能を分割して開発すると、それぞれのチームが自分たちのAPIを独立して運用できる利点があります。

一方で、クライアント側は複数のAPIにまたがるデータが欲しい場合、複数回のリクエストを実行する必要が生じます。Apollo GraphQLの解説では、ユーザー・フライト・ホテルのように個別のGraphQL APIが分かれている状況では、クライアントが各APIへの呼び出しを個別に実行しなければならない点が課題として挙げられています^*1。GraphQLの利点である「必要なデータを1回のリクエストで取得できる」という性質が、サービス分割によって失われてしまう格好です。

この課題への対処法として、全チームの型定義を1つの巨大なスキーマファイルにまとめる「モノリシックなスキーマ」を作る方法も考えられます。しかし、この方法ではスキーマの所有権が曖昧になりやすく、どのチームがどのフィールドに責任を持つかが不明確になります。複数チームが1つのファイルを編集することによる競合や、変更影響範囲の把握しづらさも生じます。GraphQL Federationは、この「単一エンドポイントを保ちながら、スキーマの所有権はチーム単位に保つ」という2つの要求を両立させるための仕組みとして位置づけられます。

サブグラフ・ルーター・エンティティ — Federationを構成する3つの要素

GraphQL Federationとは、複数のサブグラフをルーターが実行時に合成し、単一の統合グラフとしてクライアントに提示する仕組みを指します。この定義を理解する鍵になるのが、サブグラフ・ルーター・エンティティという3つの構成要素です。

サブグラフ — チームごとに所有する個別のGraphQL API

サブグラフ（subgraph）は、統合グラフ（スーパーグラフ）を構成する個々のGraphQL APIです。Apollo GraphQLのドキュメントでは、各サブグラフは異なるサーバー実装やプログラミング言語で開発できるとされています^*2。ユーザーチームはUsersサブグラフを、注文チームはOrdersサブグラフを、といった形でチームごとに独立してスキーマを開発・所有できます。

ルーター — 複数サブグラフを実行時に合成する単一の入口

ルーター（router）は、フェデレーション化されたGraphQL APIの単一のエントリーポイントとして機能します^*2。クライアントから1つのGraphQLリクエストを受け取ると、必要なサブグラフへの呼び出しを内部で調整し、結果を統一されたレスポンスに組み立てて返します。クライアント側は、裏側にいくつのサブグラフが存在するかを意識する必要がありません。

エンティティと参照解決 — 複数サブグラフが同じ型に貢献する仕組み

Federationの中でも理解のハードルになりやすいのが、エンティティ（entity）という概念です。エンティティとは、1つ以上のキーフィールドで識別される、フェデレーション内の型を指します^*3。例えばProduct型にupc（商品を一意に識別するコード）というキーを設定すると、そのキーを手がかりに複数のサブグラフが同じProduct型へフィールドを追加できます。

この仕組みを実現するのが@keyディレクティブです。あるサブグラフが型に@key(fields: “upc”)を宣言すると、「upcを渡されれば、このサブグラフはProductのインスタンスを解決できる」という意図を表明したことになります^*3。例えば、Productsサブグラフがupc・name・priceを定義する一方で、Reviewsサブグラフが同じProduct型にレビュー件数や評価点を追加する、といった役割分担が可能です^*3。それぞれのサブグラフは自分が追加したフィールドだけを解決すればよく、この設計によって関心の分離が保たれます^*3。

実装面では、フェデレーション対応のサブグラフはFederation Subgraph Specificationと呼ばれる仕様に準拠する必要があります。この仕様には、エンティティ解決のための仕組み（_Entityユニオン型やQuery._entitiesフィールド）や、サブグラフのスキーマ情報を提供する_Service型などが定義されています^*4。Apollo Serverのようなフェデレーション対応ライブラリを使う場合、これらの技術的な詳細を意識せずに実装できる点も、公式ドキュメントで補足されています^*4。

スキーマ統合の論点 — composition検証と破壊的変更の検知

複数のサブグラフを1つのスーパーグラフに統合する処理は、composition（構成）と呼ばれます。各サブグラフのスキーマを持ち寄り、矛盾なく1つのグラフへまとめられるかどうかを検証する工程です。サブグラフの数が増えるほど、この検証を継続的に回す体制の有無が運用の安定度を左右します。

Apollo GraphQLが提供するスキーマチェックの仕組みでは、スキーマへの変更を本番反映する前に妥当性を検証する目的で、複数の検査が用意されています^*5。1つ目はビルドチェックで、あるサブグラフの変更が有効なGraphQL定義であり、他のサブグラフと組み合わせても矛盾しないかを確認します^*5。2つ目はオペレーションチェックで、過去に実行された実際のクライアント操作のデータと照合し、提案中のスキーマ変更によって既存のクライアントが影響を受けないかを判定します^*5。フィールドの削除や型変更が、実際に使われているクエリを壊さないかを事前に把握できる仕組みです。

外注先にサブグラフの実装を委託する場合、この破壊的変更検知の仕組みをどちらが運用するかを事前に決めておく必要があります。サブグラフ単位の変更が統合グラフ全体に影響を及ぼす特性上、チェックを通さない変更を本番へ反映すると、他チームのサブグラフやクライアントに予期しない影響が及ぶ可能性があるためです。

BFFやスキーマスティッチングとの違い

複数のAPIを統合する手法としては、Federation以外にもBFF（Backend For Frontend、フロントエンドごとに専用の中間層を置く構成）やスキーマスティッチング（Schema Stitching）が候補に挙がります。それぞれ解決したい課題が異なるため、混同すると設計判断を誤りやすい領域です。

BFFは、フロントエンドの種類（Webアプリ・モバイルアプリなど）ごとに専用の中間層を用意し、その中間層が背後の複数APIを呼び出してクライアント向けに整形する構成です。中間層自体は、フロントエンド専用のロジックを持つアプリケーションとして開発・運用されます。これに対しFederationは、バックエンド側のGraphQL API群を1つのグラフとして合成する仕組みであり、フロントエンドの種類ごとに専用の中間層を作る発想とは異なります。BFFの詳細な設計論点は別稿で扱っているため、本稿ではFederationとの役割の違いに限定します。

スキーマスティッチングは、複数の既存GraphQLスキーマを実行時または構築時に結合する、Federation以前から存在するアプローチです。Apollo GraphQLは、名前空間の追加や関係をIDで表現するといった制約を課す代替アプローチが存在するとしつつ、Federationではクライアントがモノリスと同様の感覚でスキーマと対話できる点を特徴として挙げています^*1。スキーマ所有権の分割やエンティティによる参照解決といった仕組みが標準化されているかどうかが、両者を比較するときの実務的な着眼点になります。

外注の委託範囲と発注準備 — 何を渡し、何を社内に残すか

GraphQL Federationの導入を外注する場合、委託範囲の切り分けが成果を左右します。スキーマ全体の設計思想やエンティティの境界をどこに引くかは、業務ドメインの理解が前提になるため、社内チームが主導権を持つ領域です。どのサブグラフがどのエンティティを所有し、どのフィールドに責任を持つかという設計判断は、外部に委ねきるとドメイン知識の齟齬が生じやすくなります。

一方で、サブグラフの実装・ルーターの構築・composition検証パイプラインの整備・既存APIからの移行支援といった工程は、Federationの実装経験を持つ外部パートナーに委託しやすい領域です。特に複数チームのサブグラフを横断してルーターを構成し、スキーマチェックの仕組みを整える作業は、専門知識と実装経験の有無が進行速度に直結します。

発注準備の段階では、次の3点を整理しておくと外注先とのすり合わせがスムーズになります。1つ目は、統合対象となる既存GraphQL API（またはREST API）の一覧と、それぞれの所有チームです。2つ目は、エンティティ候補となる中核的な型（ユーザー・商品・注文など）と、そのキーフィールドの案です。3つ目は、スキーマチェックや破壊的変更の検知をどちらが運用し、誰が変更を承認するかという運用ルールです。これらが未整理のまま発注すると、外注先が自社の意図と異なる前提でサブグラフ境界を設計してしまい、後工程での手戻りにつながります。

外注先を評価する際は、Federation Subgraph Specificationに準拠した実装経験があるか、composition検証やスキーマチェックの運用経験があるかを確認するとよいでしょう^*4*5。単発のGraphQL API開発経験と、複数サブグラフを跨いだFederation設計・移行の経験は、求められる知見が異なります。

まとめ：GraphQL Federation外注を判断する3つの軸

本稿では、複数のGraphQL APIを1つの統合グラフにまとめるGraphQL Federationの仕組みと、外注時の論点を整理しました。要点を3つに集約すると次の通りです。第一に、Federationはサブグラフ・ルーター・エンティティという3要素で構成され、単一エンドポイントとチーム単位のスキーマ所有権を両立させる仕組みです。第二に、composition検証や破壊的変更の検知をどちらが運用するかは、外注前に合意しておくべき論点です。第三に、エンティティ境界やスキーマ設計の主導権は社内に残し、サブグラフ実装やルーター構築・移行支援を委託範囲として切り出す進め方が、ドメイン知識の齟齬を避けながら外部の実装力を活用する現実的な選択肢です。

著者：テレリモ総研編集部　鈴木 亮佑

ご不明な点はお問い合わせフォームからもご連絡いただけます。

1. *1　出典：Apollo GraphQL「Introduction to Apollo Federation」（確認：2026年）
2. *2　出典：Apollo GraphQL「Federated schemas overview」（確認：2026年）
3. *3　出典：Apollo GraphQL「Introduction to entities」（確認：2026年）
4. *4　出典：Apollo GraphQL「Apollo Federation Subgraph Specification」（確認：2026年）
5. *5　出典：Apollo GraphQL「Schema checks」（確認：2026年）

Tweet