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で十分なことが多いということ
この記事でやること
- いまのREST APIを実際に叩いて数える。 1画面ぶんの情報を集めるのに何回・何バイト必要か
graphqlとgraphql-httpを入れて、/graphqlを1本足す(既存の/api/*は消さない)- スキーマを書いてから、リゾルバを書く。
curlでクエリを叩く - GraphiQL を開いて、スキーマがそのまま説明書になっていることを見る
- わざとN+1を起こして、SQLが101本飛んでいることをログで数える
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| GraphQL | APIの問い合わせ方の仕様。「欲しい項目を、こちらが書いて渡す」やり方 |
| スキーマ | このAPIに何があって、どんな型かを書いたもの。サーバーと利用者の契約 |
| SDL | Schema 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の中で、サーバーを立てておきます。
別のターミナルでログインして、Cookieを保存しておきます。(認証の回で作ったものです)
多すぎる — 過剰取得
一覧に必要なのは title だけだとします。取ってみます。
[{"id":1,"title":"Linuxのコマンドを覚える","done":1,"user_id":1,"created_at":"2026-09-02T04:11:20.000Z"},{"id":2,...
done も user_id も created_at も返ってきています。 画面では使いません。
大きさを測ります。
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画面ぶんを集めます。
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 では、返せるものを型で先に宣言しないと、そもそも動きません。
入れます。
~/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枚めくる必要があります)。
立て直します。
⑤ curl で叩く
まず、いちばん短いクエリから。
{
"data": {
"tasks": [
{ "title": "Linuxのコマンドを覚える" },
{ "title": "RESTを覚える" },
{ "title": "GraphQLを試す" }
]
}
}
title しか返っていません。 頼んでいないからです。done も id も、スキーマにはあるのに返りません。
では、さっきRESTで5回叩いた画面を、1回で。
4820
| 往復の回数 | 返ってきた大きさ | |
|---|---|---|
| REST | 5回(一覧1 + 人4) | 9142 + 人4件ぶん |
| GraphQL | 1回 | 4820 |
回数が5→1、大きさが約半分。 これが冒頭の不満に対する答えです。
[スクリーンショット: 02_graphql_1回.png] 上の GraphQL のリクエスト1本と、その返り値を撮ってください。REST で5回叩いていたものが1本になっていることが分かる並びにしてください。
書き換える — ミューテーション
mutation と先頭に書く以外、形は同じです。そしてHTTPのメソッドは、読むときと同じ POST です。
{ ... }だけで始めたものはqueryの省略形です。query { tasks { title } }と書いても同じです。mutationは省略できません。 省略したら「読み取り」だと解釈されます。
変数を使う(文字列を組み立てない)
上の curl では、クエリ文字列の中に \"GraphQLを覚える\" を埋め込みました。 これはその場かぎりの確認用です。
アプリから呼ぶときは、必ず変数を使ってください。
理由は、MySQLの回で「SQLを文字列で繋げるな」と書いたのと同じです。 クエリ文字列に利用者の入力を混ぜると、クエリの構造そのものを壊されます。
$tにしてvariablesで渡せば、値は絶対に構造にならない。
⑥ GraphiQL — スキーマがそのまま説明書になる
GraphQL には「APIに向かって、お前は何ができるのかと聞く」仕組み(イントロスペクション)が標準で付いています。それを使った画面が GraphiQL です。
graphql-http 自体には画面が入っていないので、別に入れます。
~/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 を頼まないで叩きます。
GraphQL SQL 1本 / 5.3ms
1本。当然です。 では、user { email } を足すだけ。
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人しかいない」と分かったのと、まったく同じことを自動でやります。
この記事では、ここから先には踏み込みません。 理由は2つです。
- リクエストごとにローダーを作り直す必要がある(使い回すと、他人のデータが混ざったキャッシュを返します。これは事故です)
contextの設計とセットで考える話になり、GraphQLとRESTの違いという本題から離れる
いま持ち帰るのは、これだけで十分です。
GraphQLを本気で使うなら、DataLoader(か、それに相当する仕組み)は「あとで入れるもの」ではなく「最初から要るもの」。 入れないと、フィールドを1行足されただけで本数が100倍になる。
⑧ 失われるもの
利点だけ書いて終わると嘘になります。 GraphQLを足すと、RESTで無料で手に入っていたものが、いくつか消えます。
1. HTTPのキャッシュが効かない
RESTでは、こう書けました。
GET /api/tasks/3 ← URLが違えば別のもの。ブラウザもnginxも中身を知らずにキャッシュできる
GraphQLでは、全部が POST /graphql です。
RESTの GET | GraphQLの POST /graphql | |
|---|---|---|
| ブラウザのキャッシュ | 効く | 効かない(POSTはキャッシュされない) |
| nginxのキャッシュ | 効く | 効かない(URLが全部同じ) |
Cache-Control / ETag | 使える | 意味を持たない |
確かめられます。
URLが違うか、同じか。 それだけの違いですが、キャッシュの仕組みは全部「URLで見分ける」前提で作られています。
だからGraphQLでは、キャッシュを自分で持ち込むことになります。 Redis の回でやったような、アプリ側のキャッシュです。 「HTTPが勝手にやってくれていた仕事を、自分でやる」 —— これが交換条件です。
2. エラーが 200 で返る
存在しないIDを聞いてみます。
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は苦手(別の仕組みを足すことになる) |
| 単純なCRUD | GraphQLを足す手間が、得るものを上回る |
そして、この記事でやったことが答えでもあります。
/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 が undefined | req は graphql-http が包んだもの。元のExpressのリクエストは req.raw |
| エラーなのにログに何も出ない | errors は 200 で返る。 res.on("finish") でステータスだけ見ていると気づけない |
| 項目を足しただけでAPIが遅くなった | N+1。 user { email } の1行で101本になる。必ず本数を数える |
| GraphiQLが404 | NODE_ENV=production で立てている。それが正しい動作です |
後片づけ
この回で入れたのは npm パッケージ3つとルート2本だけです。テーブルもポートも増えていません。
GraphiQL を確実に閉じておきます。
NODE_ENV !== "production" の中にあることを目で確認してください。
まるごと戻したいときは、こうです。
そのうえで 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が効くのはクライアントが複数あるときと、フロントとバックの担当が分かれているとき
参考リンク
- roadmap.sh — Backend
- roadmap.sh — GraphQL
- GraphQL 公式 — Learn
- GraphQL 仕様
- graphql-http(GitHub)
- DataLoader(GitHub)
- MDN — HTTP レスポンスステータスコード
次に読む
この記事は 【第5段階】バックエンドとデータベース の 23 / 29 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- GraphQL(REST とは別の、1つのURLに問い合わせる形)
- REST との違いと、選ばない理由
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント