左に壊れた GraphQL を貼り付けて「Fix GraphQL!!」をクリックしてください壊れた GraphQL を貼り付け

GraphQL Fixer とは？

GraphQL スキーマをツールに貼り付けたら Syntax Error: Expected ":", found Name が返ってきた経験、あるいは誰かがフィールド名のあとのコロンを忘れていたせいで Schema Registry の diff が通らなかった経験があるなら、あの痛みはご存じでしょう。SDL は容赦がありません — 句読点が一つ抜けるだけでドキュメント全体が parse できなくなります。このツールはよくある壊れ方を直します：フィールド名のあとのコロン抜け、type 内の重複フィールド、対応していない波括弧、余分なカンマ、打ち間違えたスカラー参照。左のエディタに壊れたスキーマを貼り付けて緑色の Fix GraphQL!! ボタンを押すと、右側にきれいな SDL が返ってきます。

修復は GraphQL October 2021 仕様の type、field、argument の文法に従います。文法は小さいですが厳密です — 規則の全体像は公式の Schemas and Types 入門をご覧ください。Fixer はフィールド名、type、ディレクティブには手を加えず構造だけを整えるので、registry に対する diff はクリーンなままです。出力をさらに確認したい場合は、Apollo Server のスキーマドキュメントのバリデータに通すか、graphql-js 同梱のリファレンスパーサーで走らせてみてください。

スキーマは小さな AI サービスに送られ、構文だけを直すよう指示されています — フィールドを発明したり、リネームしたり、削除したりすることは決してありません。修復済みの SDL はプレーンテキストで返り、そのままプロジェクトに貼り付けられます。当方ではログは取りません。

GraphQL Fixer の使い方

3 ステップ。それぞれこのページの実際のボタンを使います。

壊れた SDL を貼るかサンプルを読み込む

壊れた GraphQL SDL を左のエディタに入れます。サンプル GraphQL をクリックすると、このツールが扱う種類の壊れ方 — コロン抜け、重複フィールド、閉じ括弧の抜け — を意図的に含んだ Order/Customer スキーマが読み込まれます。

type Order {
  id: ID!
  placedAt DateTime!
  total Money!
}

Fixer は書かれていないフィールドを発明しません。GraphQL の文法が拒否する構文だけを直します。妥当な構文の上の命名・設計の規約については、GraphQL ベストプラクティスガイドを読む価値があります。

Fix GraphQL!! をクリック

緑のボタンを押します。Fixer は壊れた SDL を読み、構造と句読点のエラーを特定してドキュメントを書き直します。処理中はローディング表示が出ます。両方のエディタが SDL シンタックスハイライトを使うので、修正前と後を並べて確認できます。

整ったスキーマをコピー

右側のパネルに修復済みの SDL が表示されます。フィールド名、type、説明、ディレクティブはそのまま — 構文エラーだけが直っています。出力をコピーして schema.graphql ファイルや registry に貼り付けてください。

実際に使う場面

手で編集したスキーマのクリーンアップ

大きな schema.graphql を手で編集して placedAt と DateTime! の間のコロンを忘れていませんか？エラーメッセージは "Expected :" と行番号しか出ません。Fixer ならフィールドを 1 つずつ追わずにコロンを戻してくれます。

AI 生成 SDL の修正

新機能のスキーマを LLM に下書きしてもらったら、重複フィールドあり、波括弧の代わりにカンマあり、対応していない { あり、で返ってきた。よくある失敗です。貼り付けて Fix を押せば、書き直さずに parse 可能なスキーマが手に入ります。

ログからのスキーマ復元

エスケープに包まれていたり改行が削られていたりするログ行から SDL の断片を引き抜いた？ Fixer が構造を整えるので、復元したスキーマがちゃんと parse できるようになります。

Schema Registry 投入前のチェック

フェデレーテッド registry に変更を push する前に、SDL を Fixer に通して diff をブロックしそうな句読点ミスを潰しておきます。registry にアップロードを拒否されて往復する手間が省けます。

よくある質問

どんなエラーを直しますか？

フィールド名と型の間のコロン抜け（最も多い壊れ方）、同じ type 内の重複フィールド、閉じ波括弧の抜けや余り、input object 内の余分なカンマ、list type を囲む対応していない角括弧などです。フィールド、type、argument を発明することはありません — パーサーが拒否する構文だけを直します。

フィールド名や型を変えますか？

いいえ。フィールド名、スカラー名、type 名、説明、ディレクティブはそのまま通します。Fixer が触るのは構造的な構文だけ — あなたが書いた名前はそのまま残ります。

カスタムスカラーやディレクティブはサポートしますか？

はい。scalar Money、scalar DateTime、独自の @auth や @deprecated ディレクティブ — すべて保持されます。カスタムスカラーがサーバー側で登録されているかは検証しません。SDL が parse できることだけを保証します。

フェデレーテッド subgraph (Apollo Federation) は？

フェデレーションディレクティブ（@key、@external、@requires）はそのまま通します。Fixer は純粋に構文修復レイヤーで、フェデレーションの composition は実行しません。整ったあとの出力を、registry の composition ステップに別途通してください。

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

はい — 言語モデルがそこにあるため、修復は小さなバックエンドサービスで動きます。入力はログに残しません。レスポンスは直接ブラウザに返ります。1 リクエストあたり 64 KB の上限があります。

常に parse 可能なスキーマを返しますか？

上で挙げたよくある壊れ方については、はい。元の意図が曖昧になるくらい構造が欠けている入力（たとえば type の本体まるごと削除）の場合は、推測する代わりにエラーを示すことがあります。その時は明らかな穴を手動で埋めてからもう一度通してください。

その他の GraphQL ツール

修復は GraphQL ワークフローの一部です。残りはこれらのツールがカバーします：