GraphQL ミニファイア

GraphQL スキーマからコメント、説明、空白を取り除き、最小サイズの SDL で配信します

入力

出力

GraphQL ミニファイアとは？

GraphQL スキーマをデプロイ成果物、Lambda バンドル、CDN 配信の SDL 文字列として送り出すとき、説明文と `#` コメントは思った以上にかさみます。本番のスキーマは簡単にバイト数の 40〜60 % がドキュメントだったりします — 人間が読むには有用でも、クライアント起動のために通信路を流れるなら無駄な荷物です。GraphQL 仕様はコメント、ブロック文字列の説明、ほとんどの空白を無視されるトークンとして定義しているので、まともなパーサはどのみち無視します。このミニファイアはそれらをすべて取り除き、パーサから見て元と 1 バイトも変わらない 1 行の SDL を返します。

ミニファイアは手書きで実装してあります — graphql npm パッケージはページに読み込まれないので、初期描画は軽いままです。SDL をトークン化し、コメントとブロック文字列のトークンをすべて捨て、構造的なトークンを再出力するときに、隣り合う name トークン同士を区別するために必要な最低限の空白だけを残します（仕様に沿った SDL で空白が本当に必要なのはそこだけです）。出力はフォーマッタと同じ軽量パーサで検証されるので、起動時に graphql-js や Apollo Server を通したときの往復結果は元の SDL と完全に一致します。

すべてはブラウザ内で動作します。アップロードなし、スキーマもどこにも保存されません。貼り付けて、ミニファイして、コピーするだけです。

GraphQL ミニファイアの使い方

クイック 3 ステップ。下に挙げているボタンはこのページに実際あるボタンです — ミニファイは自動で動くので「ミニファイ」ボタンはありません。

1

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

左の 入力 パネルに GraphQL スキーマを貼り付けてください — 入力を止めてから 1 秒未満でミニファイが自動的に走るので、変換ボタンを探す必要はありません。.graphql、.graphqls、.gql ファイルなら アップロード をクリック、または サンプル を押すと、コメントとブロック文字列の説明付きの実際の EC 注文スキーマが読み込まれ、それらが取り除かれていく様子が見られます。典型的な入力はこんな形です：

"""An order placed by a customer."""
type Order {
  # The unique order identifier
  id: ID!
  placedAt: DateTime!
  customer: Customer!
  items: [OrderItem!]!
  status: OrderStatus!
}

サーバ用スキーマ（extend type Query を含むもの）も、単独の型定義もどちらも扱えます。受け付ける形は GraphQL スキーマ定義言語 がサポートする範囲と同じです。

2

ミニファイされた出力を読む

右の 出力 パネルにはミニファイ済みの SDL が 1 行で表示され、節約バイト数のピルがパネルヘッダに出るので、どれだけ縮んだか一目で分かります。コメント（# ...）とブロック文字列の説明（"""..."""）は完全に削除されます — Relay の GraphQL 仕様に従えばこれらは意味的にゼロですし、イントロスペクション系のツールはどのみちリゾルバ層から説明を拾います。SDL の波括弧が合っていない、その他のパースエラーがある場合は、ミニファイアが分かりやすいインラインメッセージを表示します — 例外を投げたりクラッシュしたりはしません。

3

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

コピー を押せば、ミニファイ済みのスキーマをデプロイスクリプト、Lambda の環境変数、設定ファイルにそのまま貼り込めます。ダウンロード を押せば .graphql として保存できます。入力パネルのクリアボタンで空の状態に戻せます。ミニファイは完全にクライアント側で行われるので、スキーマがページから外に出ることはありません。

実際にこれを使う場面

デプロイ成果物を小さくする

スキーマをサーバーレス関数や Docker レイヤーにバンドルしていますか？ 説明とコメントを削るとバイト数は通常半分になります。これにすべてのコールドスタート、すべてのレイヤーダウンロードを掛け合わせると、節約は請求書に効いてきます。ランタイムのパーサは気にしません — 説明はイントロスペクション専用のメタデータですし、ほとんどの本番デプロイでは Apollo Router の本番ガイダンスに従ってどのみちイントロスペクションをオフにしています。

CDN から配信するスキーマ

ゲートウェイが起動時に CDN から SDL を取得する場合（Federation のスーパーグラフ合成、スキーマレジストリからの取得など）、コールドパスではバイトひとつひとつがレイテンシに乗ります。ミニファイ済みの SDL はパース結果が同じで、転送量を大きく削れます — 多くの場合 gzip より効きます。すでに取り除かれているものを gzip は圧縮できないからです。

ソースにスキーマを埋め込む

設定ファイル、環境変数、自作ツールにスキーマ文字列を埋め込みたいときがあります。ミニファイ済みの 1 行版なら、改行を毎回エスケープしなくても TypeScript のテンプレートリテラルや YAML のスカラーにきれいに収まります。

差分のノイズを減らす

スキーマの 2 つのリビジョンが説明やコメントだけしか違わないとき、本当の構造的な差分はドキュメント文字列の変更に埋もれます。両方をミニファイしてから差分を取れば、本当のスキーマの差だけが浮かび上がります — 変更管理や破壊的変更の検出に便利です。

よくある質問

ミニファイ後のスキーマはまだ有効な GraphQL ですか？

はい — 仕様が無視可能と定めるトークン（コメント、説明、不要な空白、カンマ）はすべて取り除かれますが、名前、句読点、文字列リテラル、数値はすべて残ります。出力は入力とまったく同じ AST にパースされます。両方を graphql-js に通して、得られたドキュメントを比べてみれば確認できます。

スキーマのドキュメントは失われますか？

はい — それが目的です。説明と `#` コメントは取り除かれます。ミニファイされていないソースはバージョン管理に置いておき、成果物を出荷する直前にだけミニファイしてください。クライアントに本当に見せたいドキュメントはイントロスペクション応答に存在し、それはデプロイされた SDL 文字列ではなくランタイムのリゾルバメタデータから生成されます。

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

いいえ。ミニファイは完全にブラウザ内で動きます。何もアップロードされず、何もログに残りません。社内用や未公開のスキーマを貼り付けても安全です。

どれくらい節約できますか？

スキーマがどれくらいドキュメント化されているかによります。説明のない素の SDL なら 10〜15 % の節約（空白だけ）。すべての型とフィールドにブロック文字列の説明が付いた、よくドキュメント化されたスキーマなら通常 40〜60 % 節約できます。出力パネルヘッダの節約バイトピルが、入力ごとの正確な数字を教えてくれます。

ディレクティブ、カスタムスカラー、Federation には対応していますか？

はい。@deprecated、@key、@external、scalar DateTime、その他のカスタムディレクティブやスカラーはすべて残ります。ミニファイアが取り除くのは無視可能なトークンだけで、意味のあるものはすべて残ります。Federation のディレクティブもきれいに往復します。

どれくらい大きなスキーマまでミニファイできますか？

ブラウザが快適に描画できる範囲なら何でも大丈夫です。数百型あるスキーマでも問題ありません。5 MB を超えたあたりから Ace エディタ自体が遅くなり始めます — ボトルネックはミニファイアではなくエディタです。

その他の GraphQL ツール

ミニファイは GraphQL を扱う作業の一部です。残りはこちらのツールでカバーできます：

GraphQL FormatterGraphQL ViewerGraphQL FixerJSON MinifierXML Minifier