GraphQL

GraphQL とは

GraphQL は、クライアントが必要なデータだけを指定して取得できる API のクエリ言語である。Facebook (現 Meta) が 2012 年に社内向けに作り、2015 年にオープンソースとして公開した。2019 年には仕様と関連資産の管理が GraphQL Foundation (Linux Foundation 傘下) へ移り、単一ベンダーの技術ではなくなっている。REST で起きやすい Over-fetching (不要なデータまで受け取る) と Under-fetching (1 画面分を揃えるのに複数リクエストが要る) を、取得内容をクライアント側で指定できる仕組みで抑えるのが狙いだ。

REST vs GraphQL

REST と GraphQL の違いを以下にまとめる。

観点	REST	GraphQL
エンドポイント	リソースごとに複数	単一エンドポイント
データ取得	サーバーが決定	クライアントが指定
Over-fetching	起きやすい	必要なフィールドだけ指定して避けられる
Under-fetching	複数リクエストが必要	1 リクエストにまとめられる
キャッシュ	HTTP キャッシュが容易	工夫が必要

クエリの例

クエリの例を以下に示す。

# クライアントが必要なフィールドだけ指定
query {
  user(id: "123") {
    name
    email
    orders(limit: 5) {
      id
      total
      status
    }
  }
}

{
  "data": {
    "user": {
      "name": "Alice",
      "email": "alice@example.com",
      "orders": [
        { "id": "o1", "total": 1000, "status": "completed" }
      ]
    }
  }
}

スキーマ定義

スキーマ定義の例を示す。

type User {
  id: ID!
  name: String!
  email: String!
  orders(limit: Int): [Order!]!
}

type Order {
  id: ID!
  total: Int!
  status: String!
}

type Query {
  user(id: ID!): User
  orders(userId: ID!): [Order!]!
}

type Mutation {
  createOrder(input: CreateOrderInput!): Order!
}

AppSync は AWS のマネージド GraphQL サービスで、DynamoDB、Lambda、RDS をデータソースとして接続できる。

GraphQL の注意点

GraphQL の注意点を以下にまとめる。

注意点	対策
N+1 問題	DataLoader でバッチ化
複雑なクエリ	クエリの深さ・複雑さを制限
キャッシュ	Apollo Client のキャッシュ
ファイルアップロード	REST と併用

いつ GraphQL を使うか

取得するフィールドをクライアント側で決める必要があるかが、判断の軸になる。

場面	選ぶ方式	理由
モバイルと Web で必要なフィールドが違う	GraphQL	クライアントが欲しい項目を指定できるため、サーバーが返す内容が固定される REST のように使わないデータまで受け取ることがない
1 つの画面のために複数のリソースを取りに行っている	GraphQL	単一エンドポイントへの 1 リクエストでまとめて取得でき、Under-fetching を埋めるためのリクエストを重ねずに済む
返す項目が決まっている単純な CRUD	REST	指定の柔軟さが要らないうえ、GraphQL では N+1 問題やクエリの深さの制限といった手当てを別に用意することになる
HTTP キャッシュをそのまま効かせたい、ファイルをアップロードする	REST	GraphQL はキャッシュに工夫が必要で、ファイルアップロードは REST を併用する形になる

理論と実装の両面から学ぶなら関連書籍が参考になる。