GraphQLの始め方 — ひよこの名前だけ取得してみよう

ひよこ

メールは要らないから、名前だけ取れる？

ペンギン先生

GraphQLなら、APIが公開している項目から欲しいものを選んで要求できるよ。本文ではひよこの名前だけ返す例を動かし、メールを追加したときの違いを見てみよう。

ひよこ

何を準備するの？

ペンギン先生

Node.jsとnpm、新しい練習フォルダーだよ。まずgraphqlライブラリだけでクエリを実行するから、DBやクラウドの設定は不要なんだ。

ひよこ

クエリはJSONを書くの？

ペンギン先生

見た目は似ているけれど、GraphQL独自の言語だよ。{ user(id: "1") { name } }ならIDが1のユーザーの名前を要求する。結果は通常JSONで、選んだ項目に沿った形になるよ。

ひよこ

何でも好きな項目を取れる？

ペンギン先生

サーバーのスキーマが公開した項目だけだよ。スキーマは型と入口の設計図、リゾルバーは値を用意する担当。権限の確認はサーバー側でも行う必要があるんだ。

ひよこ

変更や通知もできる？

ペンギン先生

読み取りの入口がQuery、変更がMutation、更新イベントを受ける入口がSubscriptionだよ。今回はQueryだけ試そう。通知の配信や変更の保存は、サーバー側の実装も必要だよ。

ひよこ

ブラウザーから呼びたいときは？

ペンギン先生

次の段階でHTTPサーバーを用意しよう。GraphQL.jsの公式例やApollo Serverなどが参考になるよ。本文の練習はサーバーを起動しないので、localhostを開くだけでは画面は出ないんだ。

ひよこ

GraphQLなら通信が必ず軽くなる？

ペンギン先生

不要な返り値を減らせるけれど、深い問い合わせや大きな一覧は高コストになりうる。RESTも項目選択を設計できるし、GraphQLも取得回数やキャッシュを考える必要があるよ。

ひよこ

本番に進む前は何を見る？

ペンギン先生

認証と項目ごとの権限、一覧の上限、問い合わせの深さや費用、エラー処理を確認しよう。関連データのN+1も測るよ。まずクエリの項目を一つ変えて、結果が変わるところから始めればいいんだ。

まず、名前だけ表示する

JavaScriptの基礎とNode.js・npmが前提です。既存プロジェクトと分けた新しい作業フォルダーで準備します。

mkdir graphql-demo
cd graphql-demo
npm init -y
npm install graphql

次を first-query.mjs に保存します。.mjs を使うので、package.json のモジュール設定は変更しません。

import { buildSchema, graphql } from 'graphql';

const schema = buildSchema(`
  type User { name: String!, email: String }
  type Query { user(id: ID!): User }
`);
const users = {
  '1': { name: 'ひよこ', email: 'chick@example.com' },
};
const result = await graphql({
  schema,
  source: '{ user(id: "1") { name } }',
  rootValue: { user: ({ id }) => users[id] ?? null },
});
console.log(JSON.stringify(result, null, 2));

node first-query.mjs で data.user.name に ひよこ が表示されます。メールは要求していないため、結果に入りません。

一つ変えて、結果を比べる

コードの source を次に変えて、もう一度実行してください。

{ user(id: "1") { name email } }

今度は email も返ります。次に name を未定義の nickname に変えると、検証エラーになります。スキーマは「何を要求できるか」を決めています。これは架空ユーザーをメモリから読む練習で、実ユーザー情報や通信は使いません。

サーバーへ進むなら

HTTP APIとして使うには、リクエストを受けてGraphQLを実行するサーバーが必要です。公式のGraphQL.jsのサーバー例、Apollo Server、GraphQL Yogaなどから用途に合うものを選びます。クライアントも、最初はHTTPリクエストを送るだけから始められます。

Apollo Sandboxはクエリを試す画面で、Apollo Clientはアプリに組み込むクライアントライブラリです。サーバーライブラリとは役割が違います。使用するツールによって画面の開き方や実行手順も違うため、公式のセットアップ手順に沿って進めましょう。

もう少し詳しく：公開前の確認

GraphQLは通常、一つのHTTPエンドポイントで複数の操作を受けますが、エンドポイント数は仕様が一つに固定しているわけではありません。RESTでもレスポンス項目を選べる設計ができます。RESTとの比較で、必要な画面や運用から考えてみましょう。

認証・権限、ページングと件数上限、深さや複雑さの制限、タイムアウトを組み合わせます。事前登録した操作の許可リストは一つの対策ですが、単なるクエリの保存だけで未知の操作が禁止されるとは限りません。

DataLoaderを使う場合も、バッチ関数とリクエスト単位のキャッシュを設計します。詳しくはリゾルバーの仕組みへ。画面では data と errors の両方を確認しましょう。

ペンギン先生のまとめ

「GraphQL」って出てきたら「APIが用意した項目から、欲しい形でお願いする方法」と思えばだいたいOK！ まずはnameだけ、次にemailも、という小さな変化を試してみよう。

参考資料

• GraphQL：Execution — フィールド・親の値・実行
• GraphQL仕様：September 2025 — Mutationの最上位の直列実行とNon-Nullのエラー伝播
• GraphQL.js：Constructing Types — buildSchemaとルートの値
• DataLoader README — バッチ関数とリクエスト単位のキャッシュ
• GraphQL：Security — 需要制御・許可リスト・権限