概要

GraphQLの素振りをしていたので調べたことについてまとめておく。

親切なチュートリアルが用意されており、始めやすい。 cf. www.howtographql.com

GraphQLとは

Meta社によって開発されたWeb API開発のためのクエリ言語。

GraphQLはGraphQL Foundationによって管理されており、Meta社はその一員である。

GraphQLの仕様と全ての関連プロジェクトはOSSとして公開されている。

特徴

• HTTP上で使用される
• クエリをPOSTリクエストすることでデータを取得する
• 単一のエンドポイントで複数のデータを取得できる
• GraphQLのスキーマやクエリは有向グラフの考え方に基づいて設計されている
• スキーマファースト
• ドキュメンテーション
  • スキーマファーストであるので、仕様が自明
  • ドキュメントジェネレーターによりドキュメントを生成することもできる
• 型定義
  • スカラー型とオブジェクト型、列挙型、リスト型、Non-null型、ユニオン型、入力型、インターフェースがある
    • 入力型はQueryやMutationの引数に使用するオブジェクト型
    • デフォルトはNullable
      • maku.blog - NullableとNon-nullのガイドライン
• データ取得の柔軟性
  • 必要なデータだけをQueryによって取得できる
  • オーバーフェッチやアンダーフェッチの発生が回避できる
• バージョン管理
  • バージョン管理することはできる
  • 新しい型やフィールド追加によってバージョンレスで開発することもできる
  • 思想としては回避派
• エラーハンドリング
  • エラーでもステータスコード200を返し、エラーメッセージを内包して返却するのが一般的

用語

いくつかピックアップしたものだけ記載。

Schema

クエリの型定義。

type Query {
  user: User
}

Query

データ取得のためのクエリ。

query {
  user {
	name
  }
}

Mutation

データ更新のためのクエリ。

mutation {
  updateUser {
	name
  }
}

Subscription

データの変更を監視するためのクエリ。

subscription {
  user {
	name
  }
}

Argument

クエリにわたす引数。

{
  user(id: 123) {
    username
    email
  }
}

関連技術

GraphQL Mesh

gRPC、OpenAPI、Swagger、oData、SOAP、GraphQL等々のAPI仕様で実装されたAPIへのゲートウェイサーバー（GraphQL Gateway）。

API仕様さえあればAPIに対してGraphQLクエリでアクセスできる。

cf. the-guild.dev

openapi-to-graphql

OpenAPIに基づいたAPI仕様をGraphQLのSchemaに変換する。

cf. github.com - IBM/openapi-to-graphql

graphql-tools

GraphQLのSchemaを作成するための便利ツール。モックを作成することもできる。

cf. github.com - ardatan/graphql-tools

GraphQL Gateway

パフォーマンス

• N+1
  • Data Loader
    • 同一テーブルへの複数のSELECTを1つのSELECTにまとめる
    • BatchとCacheという機能がある
      • cf. lyohe.github.io - 主要な機能
• Queryが複雑になるとリクエストボディが肥大化する
  • Persisted Query
    • ApolloというGraphQLのツールが提供している機能
    • クエリに対応するIDを用意しておき、IDとクエリを交換してリクエストパラメータを減らす仕組み
      • 交換のためのエンドポイントをGETにすることによりキャッシュに乗せることができる
• POSTリクエストであるため、HTTPキャッシュが利用できない
  • Persisted Query

所感

Restful APIと比較して始めるのに少し手間はかかりそうだが、得られる恩恵は大きそう。

GraphQLクライアントは色々種類があるようで、選定には悩みそう。

cf. user-first.ikyu.co.jp - あなたのプロダクトに Apollo Client は必要ないかもしれない

参考

• graphql.org
• zenn.dev - GraphQLを徹底解説する記事s
• kinsta.com - GraphQLとRESTの比較─知っておきたい両者の違い
• panda-program.com - 「初めてのGraphQL」を読んでGraphQLの概要を学んだ
• qiita.com - GraphQLのスキーマと型定義
• gist.github.com - GraphQL についてまず知っておきべきこと
• maku.blog - GraphQL ベストプラクティス
• qiita.com - GraphQL でのパフォーマンス関連の問題について色々紹介する
• engineering.mercari.com - GraphQLを導入する時に考えておいたほうが良いこと
• engineering.mercari.com - メルカリ Shops での NestJS を使った GraphQL Server の実装
• lyohe.github.io - graphql/dataloader を読んだ話
• zenn.dev - GraphQL で N+1 問題を解決する 4 つのアプローチ
• www.apollographql.com - GraphQL Concepts Visualized