スキーマ A（旧）

スキーマ B（新）

Diff

両方のパネルにスキーマを貼り付けてください — 入力中にdiffが更新されます。

GraphQLスキーマ Diff とは？

APIの変更はどれかしらのクライアントを壊します。スキーマPRをマージする前にまず必要なのは、本当に何が変わったかの明快なリストです — 空白・再フォーマット・本物の変更を一面の赤と緑の壁にまとめてしまう600行のGitHub diffではなく。古いスキーマを左に、新しいスキーマを右に貼り付ければ、このツールは3つのリストを返します：追加されたもの、削除されたもの、既存フィールドのうち型が変わったもの。スキーマは 2021年10月版GraphQL仕様に従ってパースされるので、ツールが「型」「フィールド」とみなすものはサーバーが認識するものと一致します。

diffは構造的なものであり、テキスト的なものではありません。型の中でフィールドを並べ替えても見えません。SDLを再フォーマットしても見えません。引数のリネームは表示されます。Order.total の Int から Float への変更は表示されます。OrderStatus.REFUNDED のような新しいenum値は追加に表示されます。union メンバーの削除は削除に表示されます。出力スタイルは GraphQL Inspector や Apollo schema checks が使う分類に合わせているので、最終的にCIにチェックを移すときワークフローはそれらのツールにそのまま移行できます。

すべてブラウザ内で実行されます。アップロードなし、ログなし。未公開の社内スキーマでも安全です。

GraphQLスキーマ Diff の使い方

貼って、貼って、読む。Compareボタンはありません — 入力中にdiffが更新されます。

パネルAに古いスキーマを貼り付ける

スキーマ A（旧）とラベルされた左パネルに現在のプロダクションスキーマを投入します。.graphql、.graphqls、.gql ファイルならアップロードを、ペアになったスターター／イテレーション例をロードしたいならサンプルを押してください。スキーマは綺麗である必要はありません — 整形の差分は無視されます。

パネルBに新しいスキーマを貼り付ける

スキーマ B（新）とラベルされた右パネルに候補スキーマ（PRに入っているもの）を投入します。ツールは両方のスキーマをトークナイズし、すべての型定義を走査して、入力を止めた数分の1秒後にdiffを再計算します。リファレンスパーサーのセマンティクスは graphql-js に十分近く、ここで表示されるものはサーバーが見るものと同じです。

3つのリストを読む

下部パネルには3つのセクションがあります。追加（緑）には新しい型、新しいフィールド、新しいenum値、新しいunionメンバーが並びます。削除（赤）には同じカテゴリが逆方向で並びます — 通常これらが破壊的変更なので、まずこのリストを確認してください。変更（琥珀色）には型が変わったフィールドや引数が並びます。例：Order.total: Int → Float。スキーマが等価であれば、その旨を伝える単一の緑のバナーが表示されます。

実際にこれを使う場面

PRレビュー

チームメイトが5つの新フィールドを追加し、引数をリネームするPRを開きます。彼がスキーマをフォーマッタにかけたせいでGitHub diffは読めません。両バージョンをここに貼り付けて本物の変更リストを取得 — 通常300項目ではなく3〜4項目です。レビュアーはインデントの議論ではなく実際のセマンティクスについて議論できます。

破壊的変更を捕まえる

フィールドの削除、戻り値の型の絞り込み、必須引数のリネームは、本番のクライアントにとっては破壊的変更です。削除と変更のリストがそれらを直接浮かび上がらせます。マージ前にdiffを実行して、破壊的変更が意図的であることを確認してください。同じチェックは最終的にCIに置くべきものです — このワークフローのプロダクション版については Apollo schema checks のドキュメントを参照してください。

オンボーディングドキュメント

新しいエンジニアが「先週のスプリントで何が変わった？」と聞いてきたら、月曜版と金曜版をパネルに貼り付けてdiffをスプリントノートにコピーします。コミットをスクロールするより速く、ずっと読みやすい。

フェデレーション合成のサニティチェック

Apollo Rover のようなフェデレーテッドコンポーザを実行した後、以前の合成スキーマと新しいものを貼り付けます。diff は、subgraph PRから期待した変更を合成が拾ったか — それとも別のどこかが静かに変わったか — を教えてくれます。

よくある質問

diffは破壊的変更を特定して捕まえてくれる？

削除と変更のリストにあるものはすべて潜在的に破壊的です — フィールド削除、戻り値型の絞り込み、引数のリネーム。ツールはGraphQL Inspectorのように各変更を「破壊的」対「非破壊的」と分類しませんが、構造化されたリストでどれを見るべきかは明らかです。

フィールドの順序は変更とみなされる？

いいえ。型の中のフィールドを並べ替えても構造的には同一であり、無視されます。enum値、unionメンバー、引数の並べ替えも同じです。追加、削除、または型変更された項目だけが報告されます。

説明やコメントは？

block-stringの説明とコメントは構造比較時に無視されます。フィールドに説明を追加してもdiffには表示されません。ドキュメント変更を追跡したいなら、ここではなくPRのフォーマット済みSDL diffで行ってください。

スキーマはサーバーに送信される？

いいえ。トークナイザとdiffは完全にブラウザ内で実行されます。何もアップロードされず、何もログに記録されません。社内や未公開のスキーマを貼り付けても安全です。

どれくらい大きなスキーマを貼れる？

ページは各入力を5 MBに制限します。それを超えるとAceエディタ自体がもたつき始めます。数百の型のスキーマなら問題ありません。

CIで動かせる？

PRをプッシュする前のローカルなサニティチェックなら、このページで十分です。破壊的変更でビルドを落とすCIゲートには、専用の GraphQL Inspector CLIまたはApollo schema checksを使ってください — 両方ともexit-codeのセマンティクスとポリシー設定が適切です。

その他のGraphQLツール

diffはGraphQLとの仕事の一部にすぎません。残りはこれらのツールが扱います：