GraphQLについて

bmf-san アプリケーション
#GraphQL

概要

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

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

GraphQLとは

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

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

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

特徴

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

用語

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

Schema

クエリの型定義。

Query

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

Mutation

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

Subscription

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

Argument

クエリにわたす引数。

関連技術

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
  • Queryが複雑になるとリクエストボディが肥大化する
    • Persisted Query
      • ApolloというGraphQLのツールが提供している機能
      • クエリに対応するIDを用意しておき、IDとクエリを交換してリクエストパラメータを減らす仕組み
        • 交換のためのエンドポイントをGETにすることによりキャッシュに乗せることができる
  • POSTリクエストであるため、HTTPキャッシュが利用できない
    • Persisted Query

所感

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

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

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

参考