GraphQL整形ツール

GraphQLを整形する理由

GraphQL のクエリは、コードの中で組み立てられたり、ログに1行で出力されたり、ブラウザのネットワーク記録からコピーされたりすることがよくあります。数階層のネストがあるクエリは、その形だとほとんど読めません。どのフィールドがどのオブジェクトに属しているのか、フラグメントがどこで終わるのかもわかりません。

GraphQL整形ツールは、フィールドを1行に1つずつ並べ、選択セットを親より1段深くインデントします。するとクエリの構造が返ってくるレスポンスの構造と一致するので、確認がしやすくなります。

このツールは、GraphQL プラグインを組み込んだ Prettier 3 をブラウザ内で使っています。

使い方

1. 左のボックスにクエリ、ミューテーション、スキーマを貼り付けます。貼り付けるとすぐに整形されます。
2. または ファイルを開く で .graphql ファイルを読み込むか、サンプル で例を表示します。
3. インデント を選びます：スペース2つ、スペース4つ、タブのいずれかです。
4. 行の幅 を選びます。収まらない引数や変数のリストは、複数行に分割されます。
5. 整形 または Ctrl+Enter を押します。
6. コピー を押すか、ダウンロード で .graphql ファイルとして保存します。

一度整形すると、その後は入力に合わせて出力が更新されます。構文エラーがあればメッセージに行と列が表示され、入力欄で表示 でその場所へ移動できます。

整形前と整形後

1行のクエリです。

query GetUser($id:ID!,$first:Int=5){user(id:$id){id name email posts(first:$first){edges{node{id title publishedAt}}}}}

スペース2つで 整形 した結果です。

query GetUser($id: ID!, $first: Int = 5) {
  user(id: $id) {
    id
    name
    email
    posts(first: $first) {
      edges {
        node {
          id
          title
          publishedAt
        }
      }
    }
  }
}

変数のコロンの後にスペースが入り、デフォルト値 5 の = の前後にもスペースが入り、ネストしたすべての選択セットがインデントされています。これで title が posts の中の edges の中の node のフィールドであることがわかります。

ミューテーションと入力オブジェクト

行の幅に収まる入力オブジェクトは1行のまま残ります。

mutation {
  createPost(input: { title: "Hello", tags: ["news", "update"] }) {
    id
  }
}

収まらない場合は引数が分割されます。同じミューテーションを行の幅 40 で整形した例です。

mutation {
  createPost(
    input: {
      title: "Hello"
      tags: ["news", "update"]
    }
  ) {
    id
  }
}

複数行になったオブジェクトでは、入力フィールドの間のカンマが削除される点に注意してください。GraphQL ではカンマは省略可能で、空白と同じ扱いです。

フラグメント

フラグメントとスプレッドは、書いた順序のまま残ります。

fragment UserParts on User {
  id
  name
}
query {
  me {
    ...UserParts
  }
}

スキーマファイル

スキーマ定義言語も同じルールで整形されます。フィールドは1行に1つ、enum の値もそれぞれ別の行に並びます。

type User {
  id: ID!
  name: String!
  posts(first: Int): [Post!]!
}
enum Role {
  ADMIN
  EDITOR
}

インデント をスペース4つにすると、query{viewer{login}} は次のようになります。

query {
    viewer {
        login
    }
}

構文エラー

GraphQL のパーサーは厳密で、メッセージは短めです。よくある2つの例です。

• 最後の閉じ波かっこが抜けていると、4行目、1列目：Syntax Error: Expected Name, found <EOF>. と表示されます。パーサーが選択セットの中にいるまま、入力の末尾に達したということです。
• user(id: ) のように値のない引数があると、2行目、12列目：Syntax Error: Unexpected ")". と表示されます。

表示された位置から波かっこを数えてみてください。長いクエリで閉じかっこの抜けを探すのにも、整形ツールは手軽です。貼り付けてみて、エラーが入力の末尾を指していれば、どこかの選択セットが閉じられていません。

制限事項

• チェックするのは構文だけです。フィールド名、引数の型、必須の変数は、どのスキーマに対しても検証されません。
• フィールドの並べ替え、型のソート、使われていないフラグメントの削除は行いません。
• JavaScript や TypeScript の gql テンプレート文字列の中にあるクエリは、クエリの部分だけをここに貼り付け、結果を元に戻してください。JavaScript整形ツール と TypeScript整形ツール は周りのコードを整形しますが、テンプレート文字列はそのまま残します。
• 変数は GraphQL ではなく JSON で送られます。変数のオブジェクトは JSON整形ツール で整形してください。

GraphQLを整形するほかの方法

• VS Code：Prettier 拡張機能を入れて「ドキュメントのフォーマット」（Windows は Shift+Alt+F、macOS は Shift+Option+F）を実行すると、.graphql と .gql のファイルがこのページと同じルールで整形されます。
• コマンドライン：npx prettier --write schema.graphql
• GraphiQL などの GraphQL IDE には、エディタ内のクエリを整形する Prettify ボタンがあります。テスト中はそちらが便利で、IDE が手元になくテキストしかないときはこのページが役立ちます。