1画面のために3回叩く — GraphQLとRESTの違い

GraphQLとREST。アプリの画面と選択されたデータカード、APIの接続線。

REST API の設計で、GET POST PUT PATCH DELETE が一周しました。URLはモノ、メソッドが動詞。 きれいに揃っています。

前回: 待たせるAPIをやめる — メッセージキューとRabbitMQ 作業場所はVMの中(Ubuntu)です。ここまでで作った ~/server(Express + MySQL + Knex + セッション認証)を、そのまま使います。

そのAPIで、画面を1つ作ろうとしてみてください。

タスクの一覧を出したい。1件ごとに「タイトル」と「作った人のメールアドレス」を並べたい。

やることは、こうなります。

GET /api/tasks              ← 一覧を取る(100件)
GET /api/users/1            ← 1件目の人を取る
GET /api/users/2            ← 2件目の人を取る
GET /api/users/1            ← 3件目の人も、たまたま1番の人
...

画面1つのために、何回叩くことになるのか。 そして GET /api/tasks が返してくる created_at や done は、この画面では1つも使いません。

この回は、その不満を実際に数字で出してから、GraphQL を足します。置き換えません。足すだけです。

対象レベル: 初級〜中級 / 区分: 必修

目次

この記事でわかること

  • RESTで困るのは「多すぎる」と「足りない」の2つだということ(過剰取得と不足取得)。そしてそれは設計が下手だから起きるのではないこと
  • GraphQLは新しい通信方式ではないこと。1つのURLにPOSTするだけで、HTTPの上にそのまま乗っていること
  • スキーマが契約になること。ドキュメントを書かなくても、型がそのまま仕様になること
  • GraphQLはRESTより遥かにN+1を起こしやすいこと。しかも書いた本人にはSQLが見えないこと
  • 失われるものがあること(HTTPのキャッシュが効かない / エラーが200で返る / 認可が複雑になる)
  • 個人で作るサービスなら、RESTで十分なことが多いということ

この記事でやること

  1. いまのREST APIを実際に叩いて数える。 1画面ぶんの情報を集めるのに何回・何バイト必要か
  2. graphql と graphql-http を入れて、/graphql を1本足す(既存の /api/* は消さない)
  3. スキーマを書いてから、リゾルバを書く。curl でクエリを叩く
  4. GraphiQL を開いて、スキーマがそのまま説明書になっていることを見る
  5. わざとN+1を起こして、SQLが101本飛んでいることをログで数える

先に知る言葉

この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。

言葉意味
GraphQLAPIの問い合わせ方の仕様。「欲しい項目を、こちらが書いて渡す」やり方
スキーマこのAPIに何があって、どんな型かを書いたもの。サーバーと利用者の契約
SDLSchema Definition Language。スキーマを書くための書き方。type Task { ... } の形
クエリ / ミューテーションクエリ=読む、ミューテーション=書き換える。GraphQL での GET と POST に相当する区別
リゾルバ1つのフィールドの値を、実際に取ってくる関数。title はこれ、user はこれ、と項目ごとにある
過剰取得(over-fetching)使わない項目まで返ってくること
不足取得(under-fetching)1回では足りず、何回も叩くことになること
イントロスペクションAPIに向かって「お前は何ができるのか」と聞ける仕組み。GraphQLに標準で付いている
DataLoader同じ種類の問い合わせを、ひとまとめにして1回にするための道具。N+1対策

「GraphQL」の Graph は、グラフ(図表)ではなく「繋がり」のグラフです。 タスク → その人 → その人の他のタスク、と辿れる。だから「グラフに対する問い合わせ言語」という名前です。

① まず、いまのAPIで何回叩くのか数える

不満を言葉で説明しても意味がありません。数えます。

VMの中で、サーバーを立てておきます。

bash
$ cd ~/server
$ node --env-file=.env app.js

別のターミナルでログインして、Cookieを保存しておきます。(認証の回で作ったものです)

bash
$ curl -s -c cookie.txt -X POST http://localhost:3000/api/login \
    -H "Content-Type: application/json" \
    -d '{"email":"a@example.com","password":"himitsu123"}'

多すぎる — 過剰取得

一覧に必要なのは title だけだとします。取ってみます。

bash
$ curl -s -b cookie.txt http://localhost:3000/api/tasks | head -c 300
[{"id":1,"title":"Linuxのコマンドを覚える","done":1,"user_id":1,"created_at":"2026-09-02T04:11:20.000Z"},{"id":2,...

done も user_id も created_at も返ってきています。 画面では使いません。

大きさを測ります。

bash
$ curl -s -b cookie.txt http://localhost:3000/api/tasks | wc -c
9142

9KBです。 そのうち画面が使うのは title だけ。これが過剰取得です。

「使わないなら返さなければいい」と思うかもしれません。 その通りなのですが、GET /api/tasks は詳細画面からも呼ばれます。 そちらでは done も created_at も要ります。 1つのURLで、全部の画面の要求を満たそうとすると、一番多い画面に合わせるしかありません。 これは設計ミスではなく、「URL=モノ」という約束の当然の帰結です。

足りない — 不足取得

「作った人のメール」を出したい。 いまのAPIには user_id しか無いので、別のURLが要ります。

~/server/app.js に足します。

app.get("/api/users/:id", requireLogin, async (req, res) => {
  const user = await knex("users").where({ id: req.params.id }).select("id", "email").first();
  if (!user) return res.status(404).json({ error: "そのユーザーはいません" });
  res.json(user);
});

では、1画面ぶんを集めます。

bash
$ curl -s -b cookie.txt http://localhost:3000/api/tasks | jq -r '.[].user_id' | sort -u > ids.txt
$ wc -l ids.txt
4 ids.txt

タスク100件に、登場する人が4人。 ということは、この画面を描くのに必要な往復は。

1回(一覧) + 4回(人)= 5回

しかも「4人だと分かる」のは、1回目の返事が返ってきた後です。 つまり先に1回待ってから、次の4回。非同期処理の回でやった Promise.all を使っても、この2段階の待ちは消えません。

これは、まだ運が良いほうです。 sort -u で重複を潰したから4回で済んでいます。 素直に書くと、100件それぞれについて1回ずつ叩きます。101回です。 パフォーマンス改善の回でやった N+1 が、今度はサーバーの中ではなくブラウザとサーバーの間で起きます。 そしてこちらのほうが1回あたりが遥かに重い(ネットワークを1往復するので)。

[スクリーンショット: 01_rest_回数.png] 開発者ツールの Network タブ、または上の curl を並べたターミナルで、1画面ぶんに5回のリクエストが並んでいるところを撮ってください。回数が読めることが条件です。

RESTの逃げ道と、その限界

RESTのままでも、逃げ道はあります。 実際、よく使われます。

逃げ道例限界
項目を選ばせるGET /api/tasks?fields=id,title自前で作ることになる。 fields の解釈も検証も全部自分で書く
中身を埋め込むGET /api/tasks?include=user組み合わせが爆発する。 include=user,comments,tags …
画面専用のURLを作るGET /api/screens/task-list画面が増えるたびにURLが増える。 RESTで一番避けたかったこと

3つ目が、現場で一番よく起きます。 そして気づくと /api/tasks /api/tasks/summary /api/tasks/for-dashboard /api/tasks/mobile が並びます。 GraphQL は、この3つ目を「仕組みとして」やったものです。画面ごとのURLを作る代わりに、画面が欲しい形を毎回書いて渡す。

② GraphQLは「1つのURLにPOSTする」だけ

先に、いちばん大事なことを言います。

GraphQL は、HTTP を置き換えません。 POST /graphql に JSON を投げて、JSON が返ってくる。それだけです。

つまり、こういう1本のリクエストになります。

POST /graphql
Content-Type: application/json

{"query":"{ tasks(limit: 3) { title user { email } } }"}

RESTで言えば、POST /graphql という1本のエンドポイントしか無いAPIです。

  • URLは1本だけ。 /graphql に全部行く
  • メソッドは基本 POST だけ。 読むときも POST
  • ステータスコードは基本 200 だけ。 中身が失敗していても200(後述)
  • Cookieもヘッダーも、そのまま使える。 認証の回のセッションはそのまま効きます

「RESTを捨ててGraphQLにする」ではありません。 REST が使っていた HTTPの表現力(メソッド・URL・ステータス)を捨てて、代わりに本文の表現力を取る、という交換です。 何を捨てているかを分かっていないと、後で困ります。 その話は最後にまとめて書きます。

③ スキーマを書く — 型が契約になる

GraphQL で最初に書くのは、実装ではなくスキーマです。ここが REST と一番違うところかもしれません。

RESTでは、GET /api/tasks が何を返すかはコードを読むか、ドキュメントを書くかでした。書かなければ誰にも分かりません。

GraphQL では、返せるものを型で先に宣言しないと、そもそも動きません。

入れます。

bash
$ cd ~/server
$ npm install graphql graphql-http

~/server/schema.js を新しく作ります。

const { buildSchema } = require("graphql");

const schema = buildSchema(`
  type User {
    id: Int!
    email: String!
  }

  type Task {
    id: Int!
    title: String!
    done: Boolean!
    user: User
  }

  type Query {
    task(id: Int!): Task
    tasks(limit: Int): [Task!]!
  }

  type Mutation {
    addTask(title: String!): Task!
    setDone(id: Int!, done: Boolean!): Task!
  }
`);

module.exports = { schema };

読み方は3つだけ覚えれば足ります。

書き方意味
String!! は「必ず入っている」。無い可能性があるなら ! を付けない
[Task!]!Task の配列。 中身も配列自体も必ずある(空配列はあり得るが null にはならない)
tasks(limit: Int)引数。RESTのクエリパラメータやパスパラメータに相当

type Query と type Mutation は特別な名前です。入口になります。

  • Query = 読むときの入口(RESTの GET)
  • Mutation = 書き換えるときの入口(RESTの POST / PUT / DELETE)

Query と Mutation の区別は、GraphQLが強制してくれるものではありません。 Query の中で DELETE を実行するコードも普通に書けてしまいます。 動きます。そして誰も止めてくれません。 RESTでは「GET で状態を変えない」がHTTPの約束として外から効いていました。GraphQLでは、それは自分で守るルールに格下げされます。

型が説明書になる、ということ

Task に created_at が無いことに気づいたでしょうか。 意図的です。

スキーマに書かないものは、絶対に返りません。 逆に言えば、スキーマを見れば、このAPIから何が取れるかが全部分かります。

これが「契約」の意味です。 ドキュメントとコードがズレる、という定番の事故が起きません。ズレたら起動しないか、実行時に型エラーになるからです。

④ リゾルバを書いて、既存のRESTと並べる

スキーマは「何があるか」だけです。「どこから取るか」は別に書きます。 それがリゾルバです。

~/server/app.js に足します。 既存の app.get("/api/tasks", ...) などは1行も消しません。

const { createHandler } = require("graphql-http/lib/use/express");
const { schema } = require("./schema");

function toTask(row) {
  return {
    id: row.id,
    title: row.title,
    done: !!row.done,
    user: () => knex("users").where({ id: row.user_id }).select("id", "email").first(),
  };
}

const root = {
  async tasks({ limit }) {
    const rows = await knex("tasks").select("id", "title", "done", "user_id").limit(limit ?? 100);
    return rows.map(toTask);
  },
  async task({ id }) {
    const row = await knex("tasks").where({ id }).first();
    return row ? toTask(row) : null;
  },
  async addTask({ title }, context) {
    const [id] = await knex("tasks").insert({ title, user_id: context.userId });
    const row = await knex("tasks").where({ id }).first();
    return toTask(row);
  },
  async setDone({ id, done }, context) {
    await knex("tasks").where({ id, user_id: context.userId }).update({ done });
    const row = await knex("tasks").where({ id }).first();
    return toTask(row);
  },
};

app.all(
  "/graphql",
  requireLogin,
  createHandler({
    schema,
    rootValue: root,
    context: (req) => ({ userId: req.raw.session.userId }),
  })
);

要点は3つです。

1つめ。toTask の user が「関数」になっています。

user: () => knex("users").where({ id: row.user_id }).select("id", "email").first(),

これがリゾルバです。 GraphQL は、クエリで user が要求されたときだけ、この関数を呼びます。 要求されなければSQLは1本も飛びません。

「欲しい項目だけ取れる」の正体が、これです。 魔法ではなく、項目ごとに関数を分けて、聞かれたものだけ実行しているだけです。 そして、この「項目ごとに1回呼ばれる」という性質が、あとで山場になります。

2つめ。requireLogin を app.all に付けています。 認証の回で作ったミドルウェアが、そのまま使えます。GraphQLも普通のExpressのルート1本だからです。

3つめ。context でセッションのユーザーIDを渡しています。 req.raw が元のExpressのリクエストです(graphql-http が包んでいるので、1枚めくる必要があります)。

立て直します。

bash
$ node --env-file=.env app.js

⑤ curl で叩く

まず、いちばん短いクエリから。

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"{ tasks(limit: 3) { title } }"}' | jq
{
  "data": {
    "tasks": [
      { "title": "Linuxのコマンドを覚える" },
      { "title": "RESTを覚える" },
      { "title": "GraphQLを試す" }
    ]
  }
}

title しか返っていません。 頼んでいないからです。done も id も、スキーマにはあるのに返りません。

では、さっきRESTで5回叩いた画面を、1回で。

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"{ tasks(limit: 100) { title user { email } } }"}' | wc -c
4820
往復の回数返ってきた大きさ
REST5回(一覧1 + 人4)9142 + 人4件ぶん
GraphQL1回4820

回数が5→1、大きさが約半分。 これが冒頭の不満に対する答えです。

[スクリーンショット: 02_graphql_1回.png] 上の GraphQL のリクエスト1本と、その返り値を撮ってください。REST で5回叩いていたものが1本になっていることが分かる並びにしてください。

書き換える — ミューテーション

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"mutation { addTask(title: \"GraphQLを覚える\") { id title done } }"}' | jq

mutation と先頭に書く以外、形は同じです。そしてHTTPのメソッドは、読むときと同じ POST です。

{ ... } だけで始めたものは query の省略形です。 query { tasks { title } } と書いても同じです。 mutation は省略できません。 省略したら「読み取り」だと解釈されます。

変数を使う(文字列を組み立てない)

上の curl では、クエリ文字列の中に \"GraphQLを覚える\" を埋め込みました。 これはその場かぎりの確認用です。

アプリから呼ぶときは、必ず変数を使ってください。

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"mutation Add($t: String!) { addTask(title: $t) { id title } }","variables":{"t":"変数で入れた"}}' | jq

理由は、MySQLの回で「SQLを文字列で繋げるな」と書いたのと同じです。 クエリ文字列に利用者の入力を混ぜると、クエリの構造そのものを壊されます。 $t にして variables で渡せば、値は絶対に構造にならない。

⑥ GraphiQL — スキーマがそのまま説明書になる

GraphQL には「APIに向かって、お前は何ができるのかと聞く」仕組み(イントロスペクション)が標準で付いています。それを使った画面が GraphiQL です。

graphql-http 自体には画面が入っていないので、別に入れます。

bash
$ npm install ruru

~/server/app.js に足します。

const { ruruHTML } = require("ruru/server");

if (process.env.NODE_ENV !== "production") {
  app.get("/graphiql", (req, res) => {
    res.type("html").end(ruruHTML({ endpoint: "/graphql" }));
  });
}

ブラウザ(ホストのWindows側)から開きます。

http://192.168.x.x:3000/graphiql

左に書いて、実行すると右に出ます。 そして右端の Docs を開くと、さっき書いた schema.js がそのまま説明書になっています。

[スクリーンショット: 03_graphiql.png] GraphiQL で tasks のクエリを実行し、Docs に Task の型が出ているところを撮ってください。

本番でGraphiQLを開放しないでください。

GraphiQL は「誰でも触れる管理画面」に近いものです。ログイン不要で置いたら、外から自由にクエリを実行できます。 上のコードで NODE_ENV !== "production" で囲んでいるのは、そのためです。 セキュリティの回でやった「要らないものを外に出さない」と同じ話です。

さらに厳しく言うと、イントロスペクション自体も本番では切ることがあります。 APIの中身を全部教える機能だからです。 ただし、切ると「スキーマが契約になる」という利点も半分死にます。 ここは社内向けか、外向けかで判断が分かれるところです。

⑦ GraphQLはN+1を起こしやすい

ここがこの記事で一番大事なところです。

パフォーマンス改善の回で N+1 をやりました。一覧を1回引いたあと、1件ごとに追加で問い合わせてしまうやつです。

GraphQL では、これが「自然に」起きます。 しかも書いた本人が気づけません。

数える仕掛けを入れる

パフォーマンスの回と同じものを、もう一度入れます。

let queryCount = 0;
knex.on("query", () => {
  queryCount++;
});

app.use("/graphql", (req, res, next) => {
  queryCount = 0;
  const t0 = process.hrtime.bigint();
  res.on("finish", () => {
    const ms = Number(process.hrtime.bigint() - t0) / 1e6;
    console.log(`GraphQL SQL ${queryCount}本 / ${ms.toFixed(1)}ms`);
  });
  next();
});

queryCount はサーバー全体で1つの変数なので、同時にリクエストが来ると数字が混ざります。 1人で試す練習用と割り切ってください。

起こす

さっきと同じクエリです。 まず user を頼まないで叩きます。

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"{ tasks(limit: 100) { title } }"}' > /dev/null
GraphQL SQL 1本 / 5.3ms

1本。当然です。 では、user { email } を足すだけ。

bash
$ curl -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"{ tasks(limit: 100) { title user { email } } }"}' > /dev/null
GraphQL SQL 101本 / 218.4ms

101本です。

[スクリーンショット: 04_graphql_n1.png] GraphQL SQL 101本 と出ているログを撮ってください。101 という数字が読めることが条件です。

なぜ、これがRESTより危ないのか

RESTでN+1が起きるのは、自分がループを書いたときだけでした。

for (const t of tasks) {
  const user = await knex("users").where({ id: t.user_id }).first();  // ← 自分で書いた
}

画面には見えています。 ひどいコードですが、目で見えます。

GraphQLでは、ループを書いたのは自分ではありません。

  • サーバー側は user: () => ... を1つ書いただけ
  • 利用者側は user { email } を1行足しただけ
  • その間に100回のループを差し込んだのは、GraphQLの実行エンジン

サーバーを書いた人は「1件ぶんの取り方」しか書いていません。 クエリを書いた人は「SQLが何本飛ぶか」を知りません。 誰も悪くないのに101本になる。 ここが REST と決定的に違うところです。

しかも、これは深くなるほど掛け算になります。 tasks { user { tasks { title } } } と書かれたら、1 + 100 + 100×N です。クエリを書くのが外部の人なら、それはもう攻撃と区別が付きません。

DataLoader の考え方

直し方は、RESTのときと同じ発想です。「100回に分けて聞いていたものを、1回で聞く」。

ただし今回は、JOIN に書き換えることができません。 リゾルバは1件ずつ独立に呼ばれるので、まとめる場所がそもそも無いからです。

そこで使うのが DataLoader です。考え方はこれだけです。

「いますぐ取りに行かず、いったん注文票に溜める。 そのターンの注文が出揃ったら、WHERE id IN (1,2,3,4) で1回だけ取りに行って配る」

リゾルバ100個 → 「ユーザー1が欲しい」「ユーザー2が欲しい」…
                     ↓ 溜める(同じターンのぶん)
              WHERE id IN (1,2,3,4)  ← SQLは1本
                     ↓ 配る
リゾルバ100個 ← それぞれの結果

同じIDが何度も来たら、1回にまとめられます。 さっき sort -u で「実は4人しかいない」と分かったのと、まったく同じことを自動でやります。

bash
$ npm install dataloader

この記事では、ここから先には踏み込みません。 理由は2つです。

  1. リクエストごとにローダーを作り直す必要がある(使い回すと、他人のデータが混ざったキャッシュを返します。これは事故です)
  2. context の設計とセットで考える話になり、GraphQLとRESTの違いという本題から離れる

いま持ち帰るのは、これだけで十分です。

GraphQLを本気で使うなら、DataLoader(か、それに相当する仕組み)は「あとで入れるもの」ではなく「最初から要るもの」。 入れないと、フィールドを1行足されただけで本数が100倍になる。

⑧ 失われるもの

利点だけ書いて終わると嘘になります。 GraphQLを足すと、RESTで無料で手に入っていたものが、いくつか消えます。

1. HTTPのキャッシュが効かない

RESTでは、こう書けました。

GET /api/tasks/3   ← URLが違えば別のもの。ブラウザもnginxも中身を知らずにキャッシュできる

GraphQLでは、全部が POST /graphql です。

RESTの GETGraphQLの POST /graphql
ブラウザのキャッシュ効く効かない(POSTはキャッシュされない)
nginxのキャッシュ効く効かない(URLが全部同じ)
Cache-Control / ETag使える意味を持たない

確かめられます。

bash
$ curl -i -s -b cookie.txt http://localhost:3000/api/tasks | head -8
$ curl -i -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" -d '{"query":"{ tasks { title } }"}' | head -8

URLが違うか、同じか。 それだけの違いですが、キャッシュの仕組みは全部「URLで見分ける」前提で作られています。

だからGraphQLでは、キャッシュを自分で持ち込むことになります。 Redis の回でやったような、アプリ側のキャッシュです。 「HTTPが勝手にやってくれていた仕事を、自分でやる」 —— これが交換条件です。

2. エラーが 200 で返る

存在しないIDを聞いてみます。

bash
$ curl -i -s -b cookie.txt -X POST http://localhost:3000/graphql \
    -H "Content-Type: application/json" \
    -d '{"query":"{ task(id: 99999) { title } }"}' | head -3
HTTP/1.1 200 OK

200です。 RESTなら404を返していたところです。

さらに悪いのは、途中まで成功する場合があることです。

{
  "data": { "tasks": [ { "title": "...", "user": null } ] },
  "errors": [ { "message": "Cannot read properties of undefined", "path": ["tasks", 0, "user"] } ]
}

data と errors が両方入っています。 「半分成功」という状態が普通にあります。

監視への影響が大きいところです。 監視とログの回で、ステータスコードでエラー率を測るやり方をやりました。GraphQLでは、それが全部 200 になります。 ステータスコードを見ているだけの監視は、GraphQLの障害を1件も検知しません。 errors が入っているかを自分で数えてログに出す必要があります。

RESTの 404 / 400 / 500 の使い分けは、実は「無料で付いてきた監視の仕組み」でもあった、ということです。

3. 認可が複雑になる

RESTでは、認可はURLに貼れました。

app.delete("/api/tasks/:id", requireLogin, requireOwner, handler);

「このURLは、持ち主だけ」。 見れば分かります。

GraphQLでは、URLは1本しかありません。 requireLogin は入口に貼れますが、それだけです。

その先は、フィールド1つ1つで考えることになります。

{
  tasks {
    title
    user {
      email        # ← 他人のメールアドレスが見えていないか?
    }
  }
}

上のコードには、実際に穴があります。 toTask の user リゾルバは、ログインさえしていれば誰のメールでも返します。 REST版の /api/tasks は WHERE user_id = ? で自分のぶんだけに絞っていたのに、user を辿った先には、その絞り込みがありません。

GraphQLの認可は「URLごと」ではなく「フィールドごと・辿り方ごと」になります。 入口が1つになったぶん、中の分岐が全部こちらの責任に移った、と考えてください。 チェックする場所が増えるということは、チェックし忘れる場所が増えるということです。

4. 重いクエリを外から書ける

利用者が「欲しい形を書ける」というのは、裏返すと「重いものを書ける」ということです。

{ tasks { user { tasks { user { tasks { title } } } } } }

これはスキーマ上、完全に正しいクエリです。そして無限に深くできます。

対策は、外に公開するなら必須になります。

対策やること
深さの上限ネストが N 段を超えたら実行しない
複雑さの上限フィールド数に点数を付けて、合計に上限を置く
決めたクエリだけ許す事前に登録したクエリ以外を受け付けない

社内向けや自分のフロント向けなら、当面は要りません。 ただし、「要らない」と判断したことは覚えておいてください。 公開した瞬間に必要になります。

⑨ どちらを選ぶか

正直に書きます。

個人で作るサービスなら、RESTで十分なことが多いです。

理由は、GraphQLの利点が効くのが「特定の状況」だからです。

GraphQLが効く状況なぜ
クライアントが複数あるWeb・iOS・Android で欲しい項目が違う。サーバーを直さずに済む
フロントとバックの担当が分かれている「この項目も返してください」の往復が消える。これが最大の実利
画面の数が多く、変更が速い画面専用エンドポイントの増殖を止められる
繋がりを辿るデータユーザー → 投稿 → コメント → その人 ……
RESTで十分・RESTのほうがいい状況なぜ
クライアントが1つで、自分で両方書く欲しい項目が違うなら、自分でサーバーを直せばいい
キャッシュを効かせたいHTTPのキャッシュが無料で使える(GraphQLでは自作)
公開APIで、負荷を読みたい何が来るか予測できる。GraphQLは予測できない
ファイルのアップロードがあるGraphQLは苦手(別の仕組みを足すことになる)
単純なCRUDGraphQLを足す手間が、得るものを上回る

そして、この記事でやったことが答えでもあります。

/api/* を消さずに /graphql を足せた。 つまり、どちらかを選ぶ必要はありません。

実際の現場でよくあるのは、「基本はREST、画面が複雑なところだけGraphQL」という形です。 ただし 両方あるということは、認可も監視もキャッシュも2系統ぶん面倒を見るということです。それが割に合うかで決めてください。

いま ~/server にあるものについて言えば、GraphQLは要りません。 クライアントは自分だけで、両方自分で直せるからです。

それでも、この回を書いた価値はあります。 「RESTが何を無料でくれていたのか」は、失って初めて分かるからです。

つまずいたところ

症状原因
406 Not Acceptable が返るgraphql-http は Accept ヘッダーを見る。curl はふつう通るが、独自クライアントで Accept: text/html などを送ると弾かれる
400 で「Must provide query string」本文が JSON になっていない。-H "Content-Type: application/json" を忘れている
Cannot query field "createdAt" on type "Task"スキーマに書いていない項目は取れない。 DBに列があっても関係ない。schema.js に足す
done が true にならず型エラーMySQLの BOOLEAN は TINYINT。 0 / 1 が返る。!!row.done で真偽値に直す
context.userId が undefinedreq は graphql-http が包んだもの。元のExpressのリクエストは req.raw
エラーなのにログに何も出ないerrors は 200 で返る。 res.on("finish") でステータスだけ見ていると気づけない
項目を足しただけでAPIが遅くなったN+1。 user { email } の1行で101本になる。必ず本数を数える
GraphiQLが404NODE_ENV=production で立てている。それが正しい動作です

後片づけ

この回で入れたのは npm パッケージ3つとルート2本だけです。テーブルもポートも増えていません。

GraphiQL を確実に閉じておきます。

bash
$ grep -n "graphiql" ~/server/app.js

NODE_ENV !== "production" の中にあることを目で確認してください。

まるごと戻したいときは、こうです。

bash
$ cd ~/server
$ npm uninstall graphql graphql-http ruru dataloader
$ rm schema.js

そのうえで app.js から /graphql と /graphiql の2ブロックを消せば、この記事の前に戻ります。 /api/* は一切触っていないので、RESTはそのまま動きます。

~/server と appdb は残してください。

まとめ

  • RESTの不満は2つ。 多すぎる(過剰取得)と足りない(不足取得)。設計が下手だから起きるのではなく、「URL=モノ」の当然の帰結
  • 実際に数えると、1画面ぶんで5回・9KB。 使うのは title だけだった
  • GraphQLは新しい通信方式ではない。 POST /graphql に JSON を投げるだけで、HTTPの上にそのまま乗っている
  • スキーマを先に書く。 書かないものは返らない。だから型がそのまま説明書になり、ドキュメントとコードがズレない
  • Query は読む、Mutation は書く。 ただしQuery で書き換えることも普通にできてしまう。HTTPが守ってくれていた約束が、自分で守るルールに格下げされる
  • 「欲しい項目だけ取れる」の正体は、項目ごとに関数を分けて、聞かれたものだけ実行しているだけ
  • その性質が、そのままN+1になる。 user { email } の1行でSQLが1本から101本へ。サーバーを書いた人もクエリを書いた人もループを書いていないのに、起きる
  • DataLoaderは「あとで入れるもの」ではなく「最初から要るもの」
  • 失うもの: HTTPキャッシュ(全部POST・同じURL) / エラーが200で返る(監視が空振りする) / 認可がフィールド単位になる / 重いクエリを外から書かれる
  • 本番でGraphiQLを開放しない。 誰でも触れる管理画面と同じ
  • /api/* を消さずに /graphql を足せた。 どちらかを選ぶ必要はない。ただし両方持つなら、面倒も2系統ぶん
  • クライアントが1つで自分で両方書けるなら、RESTで十分。 GraphQLが効くのはクライアントが複数あるときと、フロントとバックの担当が分かれているとき

参考リンク


次に読む

この記事は 【第5段階】バックエンドとデータベース の 23 / 29 本目です。

記事
← 前の記事待たせるAPIをやめる — メッセージキューとRabbitMQ
→ 次の記事gRPCはcurlで叩けない — 関数を呼ぶようにAPIを呼ぶ

上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。

全体の順路は はじめに にあります。

roadmap.sh のどこをやっているか

Backend›APIs
  • GraphQL(REST とは別の、1つのURLに問い合わせる形)
  • REST との違いと、選ばない理由

この記事は、上の項目を実際に手を動かして確かめる回です。

よかったらシェアしてね!
  • URLをコピーしました!
  • URLをコピーしました!

コメント

コメントする

目次