入力

出力

GraphQL フォーマッターとは

コードジェネレーター、フェデレーションコンポーザー、あるいはチャットウィンドウからのコピペで出てきた GraphQL スキーマは、ほぼ確実に望み通りの空白になっていません。型がくっつき、フィールドが同じ行に並び、説明文が次の定義に押し付けられている。GraphQL のスキーマ定義言語はフロントエンドとバックエンドの読みやすい契約のはずですが、それはきちんと整形されている場合だけ。SDL を左パネルに貼り付ければ、右パネルが整形して返してくれます：2スペースインデント、1行1フィールド、引数はインライン、ブロック文字列の説明はそれが説明する型・フィールドの上に置かれます。

pretty-printer は手書きで実装されており、graphql npm パッケージはページに読み込まれません。そのため初期描画は軽いまま。SDL をトークン化し、波括弧構造を辿り、2021年10月版 GraphQL 仕様に従って一貫した間隔で再出力します。実スキーマで現れる SDL 構文はすべて対応しています：type、interface、union、enum、input、scalar、extend、schema、directive、リスト・非 null 修飾子（[Foo!]!）、デフォルト値、ディレクティブ、三重引用符の説明文。フォーマッターは冪等です。すでに整形済みの SDL は変更されずに往復するので、CI ゲートや pre-commit フックの中で安心して回せます。

すべてブラウザ内で動きます。アップロードもなければ、スキーマもどこにも保存されません。貼って、整形して、コピー。

GraphQL フォーマッターの使い方

クイックな3ステップ。下で説明するボタンはこのページに実際にあるボタンです。

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

GraphQL スキーマを左の入力パネルに貼り付けます。タイプを止めてからほんの一瞬で自動的に整形されるので、Convert ボタンを探す必要はありません。アップロードを押せば .graphql、.graphqls、.gql ファイルを読み込めますし、サンプルでリアルな e コマースの Order スキーマを読み込めます。よくある乱れた貼り付けはこんな感じです：

type Order{id:ID! placedAt:DateTime! customer:Customer! items:[OrderItem!]!} type OrderItem{sku:String! name:String! quantity:Int! unitPrice:Money!}

サーバースタイルのスキーマ（extend type Query 付き）も、単独の型定義もどちらも動きます。受け付ける形は Apollo Server のようなツールが起動時にパースする形と同じです。

整形された出力を読む

右の出力パネルに 2スペースインデントで整形された SDL が表示されます。各フィールド、enum 値、union メンバーがそれぞれ独立した行になります。引数はフィールドと同じ行のインラインに残るので、シグネチャが自然に読めます。ブロック文字列で書かれた説明（"""..."""）はそれが説明する型・フィールドの上の行に置かれます。これは Relay GraphQL 仕様がスキーマをドキュメント化する推奨方法です。SDL に波括弧の不一致やその他のパースエラーがある場合、フォーマッターは親しみやすいインラインメッセージを表示します。例外を投げたりクラッシュすることはありません。

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

コピーを押せば、整形済みのスキーマを PR、ドキュメント、チャット用に持ち出せます。ダウンロードで .graphql として保存できます。入力パネルのクリアボタンで空の状態に戻せます。整形は完全にクライアントサイドで行われるので、スキーマがページから出ることはありません。

実際にこれを使う場面

PR レビューの読みやすさ

チームメイトがスキーマに新しい型を5つ追加する PR を開きます。コードジェネレーターの出力で整形が落ちていたため、diff が一つの大きなブロックに見える。ファイルをフォーマッターに通し、整形済み版を PR の説明欄に貼れば、レビュアーは何が追加されているか実際に読めます。GraphQL スキーマのベストプラクティスに従うのは、レビュアーが構造を見られたほうがずっと楽です。

スキーマレジストリの diff

ほとんどのスキーマレジストリ（Apollo Studio、GraphQL Hive、Hasura）は diff を行単位のテキストで表示します。あるリビジョンが minify されていて、次のがきれいだと、すべての行が変更扱いになり、本当の変更がノイズに埋もれます。両バージョンをアップロード前に整形しましょう。同じフォーマッター、同じ出力、本物の diff。

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

GraphQL API の公開ドキュメントを書いている、あるいは新人エンジニアをオンボーディング中？スキーマを貼り、整形済み版を wiki や README にコピー。各型の上に説明文が見えるスキーマは、コードジェネレーターが吐き出した整形なしの塊よりずっと親切な出発点です。

pre-commit と CI ゲート

フォーマッターは冪等なので、pre-commit フックや CI チェックとして実行できます：スキーマを整形し、結果がコミット済みファイルと違えばビルドを失敗させる。コントリビューター間の空白のドリフトはなくなり、diff の半分が再整形ノイズという PR もなくなります。

よくある質問

スキーマを検証するの？それとも整形だけ？

整形だけです。フォーマッターは pretty-print に必要な範囲で波括弧と引用符のバランスをチェックしますが、Query が存在するか、参照された型が定義されているか、ディレクティブの引数が定義に合っているかは検証しません。フル検証には、リファレンス実装の graphql-js や、サーバーの起動時チェックを通してください。

スキーマはサーバーに送信されますか？

いいえ。整形は完全にブラウザ内で行われます。何もアップロードされず、何もログに残りません。社内スキーマや未公開スキーマも安心して貼り付けられます。

ブロック文字列の説明には対応していますか？

はい。三重引用符の説明（"""顧客が出した注文。"""）は保持され、それが説明する型・フィールドの上の行に出力されます。これは GraphQL 仕様に沿った標準的な SDL ドキュメントの書き方です。

ディレクティブやカスタムスカラーは？

どちらも保持されます。@deprecated、@key、その他のカスタムディレクティブはフィールドにインラインのまま。scalar DateTime のようなカスタムスカラーは独立した行として出力されます。フォーマッターはディレクティブの意味を解釈しようとはしません。それはサーバー側の仕事です。

すでに整形された SDL は再整形される？

冪等です。すでに整形された SDL を整形しても出力は同じになります。だから CI チェックや貼って比較するワークフローでフォーマッターを回しても、空白のドリフトを心配する必要はありません。

どれくらい大きなスキーマを貼れますか？

ブラウザが快適にレンダリングできる範囲なら何でも。数百型のスキーマは問題ありません。5 MB を超えると Ace エディター自体が重くなり始めます。それがボトルネックで、パーサーではありません。

他の GraphQL ツール

整形は GraphQL を扱う作業の一部です。残りはこれらのツールが担当します：