入力

出力

GraphQL クエリフォーマッターとは？

手書きで書かれた GraphQL リクエストは、最初は決まって 1 行のカッコの壁から始まります。整形せずにそのままコードレビューに貼り付ければ、最初のコメントが「整形してください」になるのは確実です。フロントエンドのビルドから出てくるクエリ、サーバーがログに吐いたクエリ、チームメイトが「なんでこれが null を返すの？」と聞いてきた Slack のスレッドに貼られたクエリも同じ運命です。このページはクエリ、ミューテーション、サブスクリプション、フラグメントを受け取って整形します。2スペースインデント、1行1フィールド、収まる引数はインライン、変数はきれいに、そして GraphQL 仕様の操作文法を最後まで尊重します。

このページは GraphQL Formatter の操作側のお供であることに注意してください。あちらのツールはスキーマ定義言語を整形します — type Order、interface Node、enum Status といったやつです。こちらのツールはクライアントが送り、サーバーが受け取るものを整形します — query OrderDetails($id: ID!) { order(id: $id) { ... } }、ミューテーション、サブスクリプション、フラグメント定義です。2 つの文法はトークンを共有しますが構造的なルールは異なります — selection set、エイリアス、フラグメントスプレッド、インラインフラグメント、ディレクティブの適用は操作専用です。間違えて SDL を貼り付けてしまったなら、スキーマフォーマッターのほうへどうぞ。

整形ロジックは TypeScript で手書きしてあります — ページに graphql-js のバンドルは読み込まれないので、初回描画は軽量なままです。出力は一般的なケースで Prettier の GraphQL プラグインの結果に一致するので、すでに Prettier を使っているコードベースに整形済みクエリを貼っても diff は出ないはずです。すべてローカルで動きます — クエリがブラウザの外に出ることはありません。

GraphQL クエリフォーマッターの使い方

手順は 3 つ。Convert ボタンはありません — タイピングを止めた一瞬後に自動で整形が走ります。

貼り付け、アップロード、またはサンプルの読み込み

左の入力パネルに GraphQL の操作を貼り付けます。アップロード をクリックすれば .graphql や .gql ファイルを読み込めますし、サンプル を押せば現実的な EC サイトの OrderDetails クエリと小さなフラグメントが入ります。よくある汚い貼り付けはこんな感じです：

query OrderDetails($id:ID!,$includeItems:Boolean=true){order(id:$id){id placedAt status customer{id name email}items @include(if:$includeItems){sku quantity unitPrice{amountCents currency}}total{amountCents currency}}}

フォーマッターは実際のクライアントコードに出てくる操作の構文をすべてカバーします — デフォルト値付きの変数定義、リスト型のデフォルト値、@include / @skip およびカスタムディレクティブ、エイリアス、フラグメントスプレッド (...Money)、インラインフラグメント (... on PaidOrder { ... })。1 つのドキュメントに複数の操作やフラグメントがある場合は、空行で区切って分けます — Apollo Client やほとんどの GraphQL ツールが期待するレイアウトです。

整形された出力を読む

右の出力パネルに整形済みの操作が表示されます。各フィールドは独立した行になります。引数はフィールドが 80 文字に収まる場合はインラインのまま、収まらなければ別の行に折り返します — Prettier の GraphQL プラグインと同じルールです。変数定義も操作のヘッダで同じルールに従います。エイリアスはコロンの後ろに 1 つだけ空白を残します（aliasedAs: fieldName）。コメント (# ...) は元々付いていた行のインデントで保持されます。入力が壊れている場合 — カッコの不一致、不要な $、足りない : など — フォーマッターは例外を投げる代わりに、わかりやすいエラーをインラインで書き出します。

コピーまたはダウンロード

コピー を押せば、整形済みクエリを PR、ドキュメント、チャットに貼り付けるために掴めます。ダウンロード で query.graphql として保存できます。Clear で入力をリセット。パイプライン全体がクライアントサイドなので、社内 API を相手にクエリをデバッグしていてサードパーティのツールに貼りたくないとき便利です。

実際にどんなときに使うか

コードレビューと PR のお作法

フロントエンドの PR で新しいミューテーションが追加されました。クエリ文字列はビルドステップで空白を削られていて、diff は 400 文字の壁になっています。フォーマッターにミューテーションを通して、整形版を PR の説明欄に貼っておけば、レビュアーは実際にどんなフィールドを読んでいるかをちゃんと見られます。同じ手は graphql-react、urql、Relay、その他テンプレートリテラルとしてクエリをインライン化するクライアント全般で使えます。

本番のクエリをデバッグする

本番のあるクエリで、想定したフィールドが null を返している。ネットワークタブからリクエストボディを取ってここに貼れば、変数の値、どのフィールドが @include を使っているか、フラグメントスプレッドがどこに着地するかが一目瞭然になります。長い 1 行を目を細めて読むよりずっとマシです。curl や Postman でリクエストを手動で再現したいときは、GraphQL を HTTP で提供する公式ガイドと組み合わせて使ってください。

学習とオンボーディング

GraphQL の操作に初めて触れる？チュートリアルで見つけたクエリを貼り付けて整形すれば、構造が一目でわかります — 操作ヘッダ、selection set、ネストした selection set、最後にフラグメント定義。出力は graphql.org のクエリガイドのレイアウトをそのままなぞるので、学習中にドキュメントへ戻るのも簡単です。

pre-commit と CI のゲート

フォーマッターは決定的なので — すでに整形済みのクエリは何も変わらず往復します — コミット前の「自分のクエリ、もう綺麗？」チェックとしてこのページが使えます。完全自動のパイプラインなら、同じソースを Prettier の GraphQL プラグインに通して、diff が 0 でなければビルドを失敗させてください。発想は同じ、ただスケールが違うだけです。

よくある質問

GraphQL Formatter ページとどう違うのですか？

GraphQL Formatter ページはスキーマ定義言語を整形します — type、interface、enum、union、scalar、directive の宣言です。このページが整形するのは操作です — query、mutation、subscription、fragment。2 つの文法はトークンを共有しますが構造的なルールはまったく違うので、操作をスキーマ側のページで整形しようとすると（あるいはその逆）出力がぐちゃぐちゃになります。貼り付けたものに合うほうを選んでください。

スキーマに対してクエリを検証してくれますか？

いいえ。フォーマッターは pretty-print に必要な範囲で波カッコ、丸カッコ、角カッコのバランスを確認しますが、あなたのスキーマは知りません。なので order が id: Int! ではなく id: ID! を取る、というようなことは教えられません。本当のバリデーションが必要なら、サーバーの起動チェックや、上の GitHub リンクにあるリファレンス graphql-js バリデータに通してください。

クエリはサーバーに送られますか？

いいえ。整形は純粋なクライアントサイド JavaScript です — 何もアップロードされず、何もログに残りません。社内向けのクエリ、機密の変数値を含むクエリ、プライベート API に対するクエリでも安心です。

変数値や引数を勝手にいじりますか？

いいえ。引数の値、デフォルト値、リスト型のデフォルト値は、:、=、, 周りのスペースだけ揃えて、それ以外は書いた通りに出力されます。フォーマッターはフィールド、引数、変数を新たに作ったり、消したり、並べ替えたりは絶対にしません — 貼ったものがそのまま、ただ綺麗に並んで出てきます。

インラインフラグメントとフラグメントスプレッドは扱えますか？

はい。インラインフラグメント (... on PaidOrder { ... }) は通常の selection set として 2 スペースインデントで処理されます。フラグメントスプレッド (...Money) はフィールドのインデントで 1 行に収まり、ディレクティブがあれば同じ行に保たれます。1 つのドキュメント内の複数のフラグメント定義は、それぞれをトップレベルの別定義として扱い、間に空行を入れます。

匿名クエリ — <code>{ field }</code> — は <code>query { field }</code> に展開されますか？

いいえ。短縮形は仕様の一部であり、フォーマッターはそのまま保ちます。名前付きクエリにしたければ、自分で名前を付けてください — フォーマッターが黙って操作を書き換えることはありません。

その他の GraphQL ツール

クエリのフォーマッターは GraphQL を扱う作業のごく一部にすぎません。サイト内の他の GraphQL ツール：