作っていたのは、記事の一覧画面です。タイトルと、書いた人の名前が並ぶだけの、なんてことのない画面でした。
これは【深掘り】の記事です。本線の順路ではありません。 本線の1画面のために3回叩く — GraphQLとRESTの違いで「GraphQL とは何か」は済んでいます。この記事はその続きで、React 側から実際にどう叩くのか、クライアントライブラリは要るのかを手を動かして確かめます。飛ばしても本線は進みます。
この記事のコマンドは、VMの中(Ubuntu Server)で打ちます。 Windows の PowerShell ではありません。画面の確認だけ、ホストの Windows のブラウザで行います。 外部の公開GraphQL APIは1つも叩きません。 練習用の公開APIはたくさんありますが、他人のサーバーに何十回もリクエストを投げて転送量を測るのは、練習であってもやってはいけないことです。 REST サーバーも GraphQL サーバーも、この記事の中で自分で立てます。 そうすると「サーバー側にどれだけ仕事が増えるか」も同時に分かるので、結局そのほうが学べます。 作業場所は
~/gqllab/。本線で作った~/react-demo/には触りません。 使うポートは 4010(REST)/ 4020(GraphQL)/ 5190(React) です。最後に全部消します。
その画面を出すために、私が書いた useEffect の中はこうなっていました。
GET /postsで一覧を取る- 一覧に著者名が入っていないので、
GET /posts/1GET /posts/2… と1件ずつ詳細を取る - 詳細に入っているのは
authorIdだけなので、GET /authors/xxxをさらに1件ずつ取る
10件並べるだけで、21回です。最初は3件しか置いていなかったので「4回」で済んでいて、そのときは何も感じませんでした。データを10件に増やした日に、画面が目に見えて遅くなりました。
しかも、GET /posts が返してくるJSONを開いてみて、もう一度驚きました。1件あたり70項目ありました。createdAt updatedAt deletedAt viewCount metaDescription ogImage …。私が使うのは title と著者の name の2項目だけです。
同時に2つのことで損をしていました。 ① 使わないものを大量に受け取っている(取りすぎ) ② 欲しいものが1回で揃わない(足りない)
「GraphQL を使えば解決する」とは、あちこちに書いてあります。でも、それを読んでも私は動けませんでした。 何が解決するのか、代わりに何を払うのかが分からなかったからです。
この記事は「GraphQLが優れている」を書く記事ではありません。 上の①と②を自分の手で再現して、数字で測って、GraphQL がそれをどう解くのか、そして代わりに何が増えるのかを確かめます。
結論だけ先に書いておきます。私は、いま作っているものには GraphQL を入れませんでした。 その理由も⑦に全部書きます。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
- 「取りすぎ」と「足りない」は別の問題であること。前者は転送量、後者はリクエスト回数で、測る道具が違う
- GraphQL は「新しい通信方式」ではないこと。中身はエンドポイント1本への POST で、
curlだけで叩ける。クライアントライブラリは必須ではない - スキーマ(型定義)が契約になること。「何が取れるか」がサーバーとクライアントの間で先に決まるので、
console.logで構造を探る作業が消える - サーバー側の実装は、確実に増えること。REST なら
res.json(posts)の1行で済んだものに、型定義とリゾルバを書く - urql の既定のキャッシュは「クエリ文字列ごとの丸ごとキャッシュ」であること。更新すると、関連するクエリを丸ごと捨てて取り直す。素直だが、粗い
- Relay は「urql の高機能版」ではなく、思想が違うこと。コンポーネントが自分の欲しいデータを宣言し、ビルド時に1本のクエリへまとめる。コンパイラとスキーマ側の規約を要求する
- GraphQL を入れると、HTTP のキャッシュが効かなくなること。POST 1本なので、CDN もブラウザキャッシュも素通りする
- 入れる価値があるのは「画面ごとに欲しいデータが大きく違うとき」だけであること。画面が数枚なら REST で十分
この記事でやること
~/gqllab/を作り、困りごとを再現する REST API を Express で立てる(ポート4010)- 転送量を
wc -cで、リクエスト回数をスクリプトで数える。①と②を数字にする - graphql-yoga で GraphQL サーバーを自分で書く(ポート4020)。型定義とリゾルバを手で書く
- クライアントライブラリを入れる前に、
curlの POST 1本だけで叩く。同じ表で REST と比べる - React(ポート5190)に urql を入れ、
useQuery/useMutationとキャッシュの挙動を Network タブで見る - Relay のコンパイラを実際に走らせて、スキーマ側に何を要求されるかを目で見る
- 素の
fetch/ urql / Apollo Client / Relay を表で比べ、入れる・入れないの判断基準を残す
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| over-fetching(取りすぎ) | 使わない項目まで一緒に送られてくること。 転送量が無駄に増える |
| under-fetching(足りない) | 1回では欲しいものが揃わず、追加のリクエストが要ること。 回数が増える |
| N+1 | 一覧を1回取ったあと、各件について1回ずつ追加で取ること。 10件なら 1+10 回。「足りない」の代表的な形 |
| スキーマ(schema) | 「このAPIには何があって、それぞれ何型か」を書いた型定義。 GraphQL ではこれがサーバーとクライアントの契約になる |
| クエリ(query) | 「この項目が欲しい」を書いた読み取りの要求。 欲しい形をそのまま書くと、その形で返ってくる |
| ミューテーション(mutation) | 書き込みの要求。 クエリと文法は同じで、「変更する側」だと宣言しているだけ |
| リゾルバ(resolver) | スキーマの各項目について「その値をどうやって用意するか」を書いた関数。 サーバー側の実体はここ |
| イントロスペクション | APIに「あなたには何がありますか」と問い合わせる仕組み。 GraphiQL の補完はこれで動く |
| ドキュメントキャッシュ | クエリ文字列をまるごと鍵にして結果を覚える、粗いキャッシュ。 urql の既定 |
| 正規化キャッシュ | 返ってきたデータを「型とid」ごとにバラして覚えるキャッシュ。 1件更新すれば、その1件を映している全画面が直る |
| フラグメント(fragment) | クエリの部品。 「この部分だけ欲しい」をまとめて名前を付けたもの。Relay の中心 |
| 接続(Connection) | ページ送りの書き方を決めた規約。 edges node cursor pageInfo という決まった形をとる。Relay が要求する |
① 困りごとを、実際に作る
まず、自分が困った状況を再現します。 借り物のAPIではなく、自分で立てます。
練習場を作る
VMの中で実行します。
確認: node -v が v20 以降を返せば大丈夫です。npm install が終わったあと ls に node_modules と package.json があることも見ておきます。
ESM(import 文)で書きたいので、package.json に1行足します。
"main": "index.js", の下あたりに "type": "module", を足して、こうします。
{
"name": "rest-api",
"version": "1.0.0",
"type": "module",
"main": "index.js",
"scripts": {
"start": "node server.js"
},
"dependencies": {
"express": "^4.19.2"
}
}
"type": "module"を書き忘れると、Cannot use import statement outside a moduleで落ちます。 私は毎回忘れます。
データを作る
1件70項目のデータを作ります。手で70個書くのは無理なので、生成します。
// 著者は3人だけ
export const authors = [
{ id: 'a1', name: '佐藤', bio: 'サーバーを触る人', email: 'a1@example.invalid' },
{ id: 'a2', name: '鈴木', bio: '画面を作る人', email: 'a2@example.invalid' },
{ id: 'a3', name: '高橋', bio: '両方やる人', email: 'a3@example.invalid' }
]
// 「使わないのに付いてくる」項目を60個ぶん作る
function padding(seed) {
const extra = {}
for (let i = 1; i <= 60; i++) {
const key = 'meta' + String(i).padStart(2, '0')
extra[key] = `記事${seed}の${key}にあたる、誰も読まない説明文です`
}
return extra
}
// 記事は10件。1件あたり 本文 + 10項目 + padding 60項目 = 約70項目
export const posts = Array.from({ length: 10 }, (_, i) => {
const n = i + 1
return {
id: String(n),
title: `記事タイトル ${n}`,
slug: `post-${n}`,
authorId: authors[i % authors.length].id,
body: `これは記事${n}の本文です。`.repeat(30),
excerpt: `記事${n}の抜粋`,
createdAt: '2026-09-01T00:00:00.000Z',
updatedAt: '2026-09-20T00:00:00.000Z',
deletedAt: null,
viewCount: n * 137,
published: true,
...padding(n)
}
})
REST サーバーを書く
import express from 'express'
import { posts, authors } from './data.js'
const app = express()
app.use(express.json())
// 一覧。中身は全部返す(よくある実装)
app.get('/posts', (req, res) => {
res.json(posts)
})
// 1件
app.get('/posts/:id', (req, res) => {
const post = posts.find((p) => p.id === req.params.id)
if (!post) return res.status(404).json({ error: 'not found' })
res.json(post)
})
// 著者1件
app.get('/authors/:id', (req, res) => {
const author = authors.find((a) => a.id === req.params.id)
if (!author) return res.status(404).json({ error: 'not found' })
res.json(author)
})
app.listen(4010, () => {
console.log('REST API: http://localhost:4010')
})
起動します。
確認: REST API: http://localhost:4010 と出れば起動しています。この端末はこのまま置いておきます。
以降、端末が3つ必要になります。 VS Code の Remote SSH を使っているなら、下のターミナルを分割すれば済みます(nanoで書き続けるのは無理)。素の SSH なら、もう1本 SSH で繋ぐか
tmuxを使ってください。
困りごと①「取りすぎ」を測る
新しい端末を開いて、VMの中で実行します。
私の環境では 49732 でした(データの作り方で変わるので、出た数字をメモしてください)。
では、私が本当に必要としていたのは何バイトぶんでしょうか。
必要な分だけ: 412 バイト と出ました。
49,732 バイト受け取って、使ったのは 412 バイト。99%以上が無駄でした。 これが over-fetching(取りすぎ) です。「遅い」ではなく「太い」という形の問題です。
困りごと②「足りない」を数える
著者名を出すには、まだ足りません。 実際に何回叩くことになるかを、スクリプトで数えます。
let count = 0
let bytes = 0
async function get(path) {
count++
const res = await fetch('http://localhost:4010' + path)
const text = await res.text()
bytes += Buffer.byteLength(text)
return JSON.parse(text)
}
// 画面が欲しいのは「タイトル」と「著者名」だけ
const list = await get('/posts')
const rows = []
for (const item of list) {
const post = await get(`/posts/${item.id}`) // 詳細(authorId が要る)
const author = await get(`/authors/${post.authorId}`) // 著者名
rows.push({ title: post.title, author: author.name })
}
console.log('リクエスト回数:', count)
console.log('受け取った合計バイト数:', bytes)
console.log('画面に出す行数:', rows.length)
console.log('最初の1行:', rows[0])
私の環境ではこうなりました。
リクエスト回数: 21
受け取った合計バイト数: 108514
画面に出す行数: 10
最初の1行: { title: '記事タイトル 1', author: '佐藤' }
10行の表を出すために、21回のリクエストと 108,514 バイト。 実際に画面に出るのは 412バイトぶんの情報です。
この21回のうち20回は、for の中で1件ずつ順番に待っています。 これが N+1 です。
[スクリーンショット: 01_rest_21回108KB.png] node count-rest.mjs の出力を撮ります。「リクエスト回数: 21」「108514」の2行が読めるように。 この数字が、③と⑦で何度も戻ってくる基準になります。
REST 側で直せないのか? 直せます。
GET /posts?fields=id,title&include=authorのようなクエリパラメータを自分で設計すれば、1回で済みます。ただしそれは「自分専用の小さなクエリ言語を、ドキュメントも型も無いまま自作する」ことです。 GraphQL は、その自作をやめて、決まった書き方に乗るという選択です。URLに動詞を入れない — REST APIの設計の続きとして読むと、位置が分かりやすいです。
② GraphQL サーバーを、自分で立てる
クライアントの話に行く前に、サーバーです。 ここを自分で書かないと、「サーバー側のコストがどれだけ増えるか」が体感できません。
graphql-yoga を使います。軽くて、設定ファイルが要らず、GraphiQL(ブラウザで試せる画面)が最初から付いてくるからです。
package.json に "type": "module" を足すのを、また忘れないでください。
{
"name": "gql-api",
"version": "1.0.0",
"type": "module",
"main": "index.js",
"scripts": {
"start": "node server.js"
}
}
データは①のものを使い回します。
スキーマ(型定義)を書く
ここが GraphQL の中心です。 「このAPIには何があるか」を先に宣言します。
type Author {
id: ID!
name: String!
bio: String
email: String
}
type Post {
id: ID!
title: String!
slug: String!
excerpt: String
body: String
viewCount: Int
author: Author!
}
type Query {
posts: [Post!]!
post(id: ID!): Post
}
type Mutation {
incrementView(id: ID!): Post!
}
読み方はこれだけです。
| 書き方 | 意味 |
|---|---|
type Post のブロック | Post という型には、これらの項目がある |
String! | 文字列で、必ず入っている(! は「nullにならない」) |
[Post!]! | Post の配列で、配列自体もnullにならず、中身もnullにならない |
author: Author! | Post から Author へ辿れる。 ここが「1回で著者名まで取れる」の正体 |
post(id: ID!) | 引数を取る項目。 REST のパスパラメータにあたる |
type Query | 読み取りの入口。 ここに書いた項目だけが最初に呼べる |
type Mutation | 書き込みの入口 |
これが契約です。 ここに書いていないものは取れません。書いてあるものは、必ず取れることをサーバーが約束します。 REST で私がやっていた「とりあえず
console.log(res)して、何が入っているか探す」作業は、この1ファイルを読む作業に変わります。
リゾルバを書く
スキーマは「何があるか」だけです。「どう用意するか」は別に書きます。 それがリゾルバです。
import { createServer } from 'node:http'
import { readFileSync } from 'node:fs'
import { createYoga, createSchema } from 'graphql-yoga'
import { posts, authors } from './data.js'
const typeDefs = readFileSync('./schema.graphql', 'utf8')
let requestCount = 0
const resolvers = {
Query: {
posts: () => posts,
post: (_parent, args) => posts.find((p) => p.id === args.id) ?? null
},
Mutation: {
incrementView: (_parent, args) => {
const post = posts.find((p) => p.id === args.id)
if (!post) throw new Error('その記事はありません')
post.viewCount += 1
return post
}
},
// Post の author をどう用意するか。ここが REST の「もう1回叩く」に相当する
Post: {
author: (post) => authors.find((a) => a.id === post.authorId)
}
}
const yoga = createYoga({
schema: createSchema({ typeDefs, resolvers }),
graphqlEndpoint: '/graphql'
})
const server = createServer((req, res) => {
if (req.url.startsWith('/graphql')) requestCount++
yoga(req, res)
})
server.listen(4020, () => {
console.log('GraphQL API: http://localhost:4020/graphql')
})
// 5秒ごとに、受けたリクエスト数を出す(回数を数えるため)
setInterval(() => {
console.log('これまでに受けたGraphQLリクエスト:', requestCount)
}, 5000)
起動します。
確認: GraphQL API: http://localhost:4020/graphql が出ること。この端末も置いておきます。
Post.authorのリゾルバに注目してください。 ここでやっているのは、REST で私がforの中で20回やっていたことと、まったく同じです。仕事が消えたわけではありません。サーバーの中に移っただけです。 移ると何が良いのか: その仕事がネットワークを越えなくなること。往復20回が、サーバー内のメモリアクセス20回になります。距離が違います。 そして、良くないこともあります: データベースを使う場合、このリゾルバがそのまま「SQLを10回発行する」になります。 GraphQL にすれば N+1 が消えるのではなく、N+1 の場所がサーバー側に移るだけです。そこは DataLoader のような仕組みで別途まとめる必要があります(サブクエリは行の数だけ実行されると、同じ形の話です)。
③ まず curl で、素のまま叩く
ここが、この記事でいちばん大事なところです。
私は最初、GraphQL には専用のライブラリが必要だと思い込んでいました。 違いました。
新しい端末で、VMの中から。
返ってきます。
{"data":{"posts":[{"id":"1","title":"記事タイトル 1","author":{"name":"佐藤"}},{"id":"2","title":"記事タイトル 2","author":{"name":"鈴木"}}]}}
これだけです。 エンドポイントは1本。メソッドは POST。ボディは
{"query": "..."}という普通のJSON。 新しいプロトコルではありません。 HTTP の上に乗った、ただの POST 1本です(APIの正体はJSONを返すHTTPでやったことと、何も変わりません)。
私はこれを知るまで、GraphQL を「大掛かりな何か」だと思っていました。 実際は、リクエストの本文に「欲しい形」を書いて POST するだけです。
数字を測る
658 でした。
①と同じ表で並べます。
| やり方 | リクエスト回数 | 受け取ったバイト数 | 画面に出す情報 |
|---|---|---|---|
REST /posts だけ | 1 | 49,732 | 著者名が無く、画面が作れない |
| REST(一覧 + 詳細10 + 著者10) | 21 | 108,514 | 揃う |
| GraphQL(欲しい項目だけ指定) | 1 | 658 | 揃う |
21回 → 1回。108,514バイト → 658バイト。 「取りすぎ」と「足りない」の両方が、同時に消えました。 ただし、消えたのはネットワーク越しの往復だけです。 サーバーの中では、②で書いた
Post.authorリゾルバが10回動いています。
引数とミューテーションも、curl で
引数付き。
変数を使う書き方(実際のアプリではこちらを使います)。
クエリ文字列に値を埋め込まず、
variablesで渡します。 理由は SQL と同じです。値を文字列連結で組み立てると、値が構文の一部として解釈されうるからです。GraphQL でも、値は必ず変数で渡すと覚えてください(アプリで弾いたはずの値が入ると地続きの話です)。 もう1つ利点があります。 クエリ文字列が固定になるので、キャッシュの鍵として使えるようになります。④で効いてきます。
書き込み。
{"data":{"incrementView":{"id":"3","viewCount":412}}}
mutationも、同じエンドポイントへの POST です。 メソッドも URL も変わりません。 「書き込みである」という情報は、URL でもメソッドでもなく、本文の中のmutationという単語だけが持っています。 これは⑦で「HTTPのキャッシュが効かない」という話に直結します。URL とメソッドだけを見る仕組み(CDN・プロキシ・ブラウザキャッシュ)からは、読み書きの区別が付きません。
GraphiQL をブラウザで開く
yoga は、ブラウザで試せる画面を最初から持っています。
ホストの Windows から見るために、ポートを開けます。 VMの中で。
確認: ufw が Rule added を返し、ip の出力に 192.168.x.x のようなVMのIPが見えること。
ホストの Windows のブラウザで http://<VMのIP>:4020/graphql を開きます。GraphiQL が出ます。
左側に書いて、実行ボタンを押します。
{
posts {
title
author {
name
}
}
}
[スクリーンショット: 02_graphiql_補完.png] GraphiQL で posts の中括弧まで打って Ctrl + Space を押し、取れる項目の候補が出ているところを撮ります。この補完は、私が何も設定していないのに動いています。 サーバーが自分のスキーマを教えられる(イントロスペクション)からです。「何が取れるか分からない」が構造的に起きません。
イントロスペクションは、本番では止めることが多い項目です。APIの全構造が誰にでも読めるためです。練習中は付けたまま、公開するときに落とす、と覚えておいてください。
④ urql を入れる
③で「ライブラリは要らない」と分かりました。では、なぜ入れるのか。
答えは「キャッシュとローディング状態の管理を、毎回書きたくないから」です。 取得のコードが200行になる — React深掘りでやった話と、まったく同じ動機です。
React 側を作る
Vite のポートと、プロキシを設定します。
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
export default defineConfig({
plugins: [react()],
server: {
host: true, // VMの外(ホストのブラウザ)から見えるようにする
port: 5190,
proxy: {
// ブラウザからは /graphql に投げる。Viteが 4020 へ中継する
'/graphql': 'http://localhost:4020'
}
}
})
proxyを書いた理由は CORS です。 ブラウザから直接http://<VMのIP>:4020/graphqlを叩くと、Reactの画面(5190番)とは別のオリジンなので、サーバー側に CORS の許可が無いと弾かれます。 Vite の proxy を通せば、ブラウザから見て同じオリジン(5190番)になるので、その問題が最初から起きません。 練習中はこれが一番手間が少ないです。
ポートを開けます。
プロバイダを置く
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { Client, Provider, cacheExchange, fetchExchange } from 'urql'
import App from './App.jsx'
import './index.css'
const client = new Client({
url: '/graphql', // Viteが4020へ中継する
exchanges: [cacheExchange, fetchExchange]
})
createRoot(document.getElementById('root')).render(
<StrictMode>
<Provider value={client}>
<App />
</Provider>
</StrictMode>
)
exchangesは「リクエストが通っていく処理の列」です。cacheExchangeがキャッシュ担当、fetchExchangeが実際に通信する担当。順番に意味があり、キャッシュが先です。キャッシュに当たれば、通信担当まで届きません。
一覧を出す
import { useQuery, gql } from 'urql'
const POSTS = gql`
query GetPosts {
posts {
id
title
author {
id
name
}
}
}
`
export default function PostList() {
const [result] = useQuery({ query: POSTS })
const { data, fetching, error } = result
if (fetching) return <p>読み込み中…</p>
if (error) return <p style={{ color: 'crimson' }}>失敗しました: {error.message}</p>
return (
<ul>
{data.posts.map((p) => (
<li key={p.id}>
{p.title} — {p.author.name}
</li>
))}
</ul>
)
}
①で21回叩いていた画面が、これだけになりました。 そして、
fetchingとerrorの分岐は消えていません。 読み込み中なのにエラーもある — React深掘りで書いたとおり、取得の状態は、道具を変えても消えません。 書く場所が減っただけです。
詳細も出して、キャッシュを見る
import { useQuery, useMutation, gql } from 'urql'
const POST = gql`
query GetPost($id: ID!) {
post(id: $id) {
id
title
viewCount
author {
id
name
bio
}
}
}
`
const BUMP = gql`
mutation Bump($id: ID!) {
incrementView(id: $id) {
id
viewCount
}
}
`
export default function PostDetail({ id }) {
const [result] = useQuery({ query: POST, variables: { id } })
const [bumpState, bump] = useMutation(BUMP)
const { data, fetching, error } = result
if (fetching) return <p>読み込み中…</p>
if (error) return <p style={{ color: 'crimson' }}>失敗しました: {error.message}</p>
const post = data.post
if (!post) return <p>その記事はありません</p>
return (
<section>
<h2>{post.title}</h2>
<p>閲覧数: {post.viewCount}</p>
<p>著者: {post.author.name}({post.author.bio})</p>
<button onClick={() => bump({ id })} disabled={bumpState.fetching}>
{bumpState.fetching ? '送信中…' : '閲覧数を+1'}
</button>
{bumpState.error && (
<p style={{ color: 'crimson' }}>更新に失敗: {bumpState.error.message}</p>
)}
</section>
)
}
import { useState } from 'react'
import PostList from './PostList.jsx'
import PostDetail from './PostDetail.jsx'
export default function App() {
const [id, setId] = useState('1')
return (
<main style={{ fontFamily: 'sans-serif', padding: 24 }}>
<h1>GraphQL 練習</h1>
<PostList />
<hr />
<p>
表示する記事:{' '}
{['1', '2', '3'].map((n) => (
<button key={n} onClick={() => setId(n)} style={{ marginRight: 8 }}>
{n}
</button>
))}
</p>
<PostDetail id={id} />
</main>
)
}
起動します。
ホストの Windows のブラウザで http://<VMのIP>:5190/ を開きます。
キャッシュが効いているところを、Network タブで見る
F12 を開いて Network タブにします(F12は「壊れたときに開くもの」ではない)。
- リロードします。
graphqlへの POST が 2本飛びます(一覧と、記事1の詳細) - 「2」ボタンを押します。 POST が 1本増えます(記事2の詳細)
- 「1」ボタンを押して、記事1に戻します。 POST が増えません。
[スクリーンショット: 03_urql_2回目は飛ばない.png] Network タブを開いたまま「2 → 1 → 2 → 1」と4回押した状態を撮ります。押した回数は4回なのに、graphql の行は2本しか増えていないところが見えるように。
variablesのidまで含めて、同じクエリだから当たっています。 これが urql の既定、ドキュメントキャッシュです。「このクエリ文字列+この変数」を鍵にして、返ってきたJSONを丸ごと覚えているだけです。
ドキュメントキャッシュの、素直で粗い挙動
「閲覧数を+1」ボタンを押してみてください。
Network タブに、POST が3本増えます。 ミューテーションが1本、そして GetPost と GetPosts(画面に出ている一覧)が1本ずつです。
なぜか。 urql の cacheExchange は、こういう判断をしています。
返ってきたミューテーションの結果に
Post型が含まれている。 →Post型を含んでいるキャッシュ済みのクエリは、全部信用できない。 → 丸ごと捨てて、画面に出ているものは取り直す。
この判断は、正しいけれど粗いです。
- 記事3の閲覧数を1つ増やしただけで、記事1も記事2も、一覧も、キャッシュから消えます
- 一覧に閲覧数は出していないのに、取り直されます
「粗い」の代わりに得ているのは、設定ゼロです。 何も書かなくても、古いデータが画面に残り続けることはありません。
正規化キャッシュとの違い
この粗さを解くのが、正規化キャッシュ(urql では Graphcache という別パッケージ)です。
| ドキュメントキャッシュ(既定) | 正規化キャッシュ(Graphcache) | |
|---|---|---|
| 覚え方 | クエリ+変数を鍵に、返ってきたJSONを丸ごと | Post:3 Author:a1 のように、型とidでバラして |
| 更新したとき | その型を含むクエリを丸ごと捨てる | その Post:3 を持つ画面だけが、その場で新しい値になる |
| 必要な設定 | 無し | id の付け方、一覧への追加・削除の反映を、自分で書く |
id を取らないと | 動く | 壊れる。 どのオブジェクトか特定できない |
| 追加のバイト数 | 小さい | 大きい |
| 向いている場面 | 画面が少ない・更新が少ない | 同じデータが複数の画面に同時に出ている |
idを必ずクエリに含めているのは、このためです。 ④のクエリでauthorからidまで取っているのは、画面で使わないのにです。正規化キャッシュに移る可能性があるなら、最初からidを取る癖を付けておくと、あとで楽です。
私の判断: 練習では既定のままでいいです。正規化キャッシュは「設定を自分で書く」段階に入るので、粗いキャッシュで実際に困ってから入れます。困る前に入れると、書いた設定が正しいかどうかを確かめる方法がありません。
⑤ Relay に触れる — 思想が違う
urql の次に Relay を見ると、「もっと高機能なやつ」だと思ってしまいます。違います。
何が違うのか
urql は「画面がクエリを1本書いて、取ってくる」道具です。
Relay は逆です。
コンポーネントが、自分が必要とするデータを fragment で宣言する。 それをビルド時にコンパイラが集めて、画面ごとに1本のクエリへまとめる。
書くとこうなります。
// 子: 自分が欲しいものだけを宣言する。どこから来るかは知らない
const authorFragment = graphql`
fragment AuthorCard_author on Author {
name
bio
}
`
// 親: 子のフラグメントを「差し込む」だけ。中身は知らない
const listQuery = graphql`
query PostListQuery {
posts {
id
title
author {
...AuthorCard_author
}
}
}
`
AuthorCardを書き換えて
実際にコンパイラを走らせてみる
話だけだと分からないので、走らせます。
②で書いたスキーマをコピーします。 Relay はコンパイル時にスキーマのファイルを読みます。
設定を package.json に足します。
{
"name": "relay-app",
"private": true,
"type": "module",
"scripts": {
"dev": "vite",
"relay": "relay-compiler"
},
"relay": {
"src": "./src",
"schema": "./schema.graphql",
"language": "javascript"
}
}
フラグメントを使うコンポーネントを書きます。
import { graphql, useFragment } from 'react-relay'
export default function AuthorCard({ author }) {
const data = useFragment(
graphql`
fragment AuthorCard_author on Author {
name
bio
}
`,
author
)
return (
<span>
{data.name}({data.bio})
</span>
)
}
コンパイラを走らせます。
ここで、意味のあるエラーが出ます。
[スクリーンショット: 04_relay_compiler_エラー.png] npx relay-compiler の出力を撮ります。「スキーマに Node インターフェースが無い」「node フィールドが無い」といった主旨のメッセージが出ているところが見えるように。これは失敗ではなく、この記事でいちばん見たかった画面です。
Relay は、サーバー側に規約を要求する
エラーの意味はこうです。
「このスキーマは Relay の仕様を満たしていません。」
Relay は、②で書いたような自由なスキーマでは動きません。 最低限、次を要求します。
| 要求 | 内容 | ②のスキーマは |
|---|---|---|
Node インターフェース | 主要な型が id: ID! を持つ Node を実装していること | 満たしていない |
node(id: ID!): Node | 「idを1つ渡せば、型を問わずそのオブジェクトが返る」入口があること | 無い |
| 接続(Connection) | 一覧は edges node cursor pageInfo という決まった形であること | 単なる配列 |
満たすには、②のスキーマをこう書き換えることになります。
interface Node {
id: ID!
}
type Author implements Node {
id: ID!
name: String!
bio: String
}
type Post implements Node {
id: ID!
title: String!
author: Author!
}
type PostEdge {
cursor: String!
node: Post!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
type PostConnection {
edges: [PostEdge!]!
pageInfo: PageInfo!
}
type Query {
node(id: ID!): Node
posts(first: Int, after: String): PostConnection!
}
そして、サーバー側のリゾルバも全部これに合わせて書き直します。
ここで私は手を止めました。 一覧を1枚出すために、スキーマとリゾルバを全部書き直すことになるからです。 Relay が要求しているのは、無茶ではありません。 「idさえあればどんなオブジェクトも取り直せる」「一覧は必ず同じ形」という前提が揃って初めて、キャッシュの自動更新とページ送りが機械的に書けるからです。規約を先に払って、あとで自動化を受け取る取引です。 でも、個人開発では重すぎます。 私が払う規約のコストに対して、受け取るものが釣り合いません。この記事では、ここで Relay を降ります。
Relay を選ぶ理由があるとしたら、これです。
- 画面が数十〜数百枚あり、コンポーネントの移動が日常的に起きる
- サーバーのスキーマを自分たちで設計・変更できる
- ビルドにコンパイラを1段挟むことを、チーム全員が受け入れられる
どれか1つでも欠けるなら、選ばないほうが幸せです。
⑥ 4つを、同じ表で比べる
素の fetch | urql | Apollo Client | Relay | |
|---|---|---|---|---|
| セットアップ | 不要。 ③でやったとおり POST 1本 | 小さい。 Client を作って Provider を置くだけ | 中くらい。 機能が多いぶん設定項目も多い | 重い。 コンパイラ + babel設定 + スキーマファイル |
| 追加されるバイト数 | 0 | 小さい | 大きめ | 中くらい(ただしビルド後) |
| キャッシュ | 自分で書く | 既定はドキュメント。 正規化は別パッケージ | 最初から正規化。 設定も多い | 正規化が前提。 規約に乗っている前提で強力 |
| コード生成 | 不要 | 任意(型が欲しいときだけ) | 任意 | 必須。 走らせないと動かない |
| サーバーへの要求 | 無し | 無し | 無し | Node と Connection の規約が必須 |
| ローディング/エラー | 自分で書く | フックが返す | フックが返す | フックが返す |
| 向いている規模 | 画面1〜3枚、クエリ数本 | 個人開発〜中規模 | 中〜大規模 | 大規模チーム |
| 学習コスト | ほぼゼロ | 低い | 中 | 高い。 GraphQL とは別に Relay を学ぶ |
私の結論: クエリが数本なら、素の
fetchで十分です。 ③で見たとおり、GraphQL を叩くのに専用ライブラリは要りません。同じデータが複数の画面に出て、キャッシュを自分で書くのが面倒になってから urql です。Apollo は機能が要ると分かってから。Relay は、上の3条件が揃ったときだけ。 状態管理ライブラリは要らなかった — React深掘りと、まったく同じ順番です。困ってから入れる。
型が欲しくなったら: GraphQL はスキーマがあるので、TypeScript の型を自動生成できます。 これは GraphQL の実務上の最大の利点かもしれません。手で型を書く必要が消えます(型は実行時には消える)。ただし、生成の仕組みをビルドに1段足すことにはなります。
⑦ 判断 — GraphQL を入れない理由のほうが多い
ここまで数字で見て、GraphQL は勝っています。21回が1回、108KBが658バイト。
それでも、私は今のプロジェクトに入れませんでした。 理由を全部書きます。
1. 画面が数枚なら、REST で十分
私が困ったのは、一覧画面1枚です。
REST 側で GET /posts?include=author&fields=id,title を足せば、それで終わりでした。 1枚の画面のために、サーバーの構造を丸ごと変える理由にはなりません。
「困っている画面の数」を数えてください。 1〜3枚なら、その画面のためのエンドポイントを足すほうが速く、壊れにくいです。
2. サーバー側の実装コストが、確実に増える
②を思い出してください。
| REST | GraphQL | |
|---|---|---|
| 一覧を返す | res.json(posts) の1行 | スキーマの型定義 + Query リゾルバ + Post.author リゾルバ |
| 項目を1つ足す | オブジェクトに足すだけ | スキーマにも書く(書かないと取れない) |
| N+1 | クライアント側に出る | サーバー側に移る。 DataLoader などで別途まとめる必要がある |
「クライアントが楽になった」ぶんの仕事は、消えていません。サーバーに移っただけです。 一人で両方書くなら、総量は増えます。
3. HTTP のキャッシュが、使えなくなる
これが、私にとって一番大きい理由でした。
REST の GET /posts は、URL が鍵です。だから、
- ブラウザがキャッシュできます
- CDN がキャッシュできます
Cache-ControlやETagが効きます
GraphQL は POST 1本です。URL は全部 /graphql で同じ。中身が違っても、外からは区別が付きません。
つまり、キャッシュは4箇所にある — Cache-ControlとCDNで見た層のうち、ブラウザとCDNの2層が丸ごと無効になります。
その代わりに、④で見たクライアント側のキャッシュを自分で持つことになります。 キャッシュが無くなったのではなく、「ただで付いてきたもの」を「自分で書くもの」に交換した、という話です。
回避策はあります(
GETで送る方式や、永続化クエリなど)。ただし、それは追加の仕組みで、追加の設定です。 「REST なら何もしなくても効いていたものを、努力して取り戻す」ことになります。
4. 重いクエリを投げられる危険がある
GraphQL は「クライアントが欲しい形を書ける」仕組みです。
裏返すと、「クライアントが、サーバーの仕事量を決められる」ということです。
②のスキーマで言えば、Post から Author へ辿れます。 もし Author から posts へも辿れるようにしたら、辿る方向が循環します。 そのとき、深く辿るクエリを1本受けただけで、サーバーがひどく重くなることがあります。
ここでは攻撃のやり方は書きません。守る側の設定だけ書きます。 公開するなら、次を必ず入れます。
| 守り | 何をするか |
|---|---|
| 深さ制限 | クエリの入れ子の深さに上限を付ける(例: 7段まで)。超えたら実行前に断る |
| 複雑度(コスト)制限 | 項目ごとに重みを付け、合計が上限を超えたら断る |
| イントロスペクションを止める | 本番ではスキーマを公開しない |
| 永続化クエリ | あらかじめ登録したクエリのIDしか受け付けない。 これが一番強い |
| タイムアウトと件数上限 | 一覧の first に上限を付け、無制限に返さない |
REST では、この心配はほとんどありません。 サーバー側が用意した形しか返さないからです。 「クライアントに自由を渡した」ぶん、「守る仕事」が増えています。 サーバーのセキュリティ点検|多層防御の考え方と確認項目の考え方が、そのまま要ります。
5. では、入れる価値があるのはいつか
画面ごとに、欲しいデータが大きく違うときです。
具体的には、こういうときです。
- Web・iOS・Android で、同じデータの違う部分を使っている(画面ごとにエンドポイントを増やし続けている)
- クライアント側の要求が頻繁に変わり、そのたびにサーバーの改修待ちになっている
- 1つの画面が、3つ以上の別々のサービスからデータを集めている
- API を作る人と使う人が別のチームで、「何が取れるか」の共有コストが高い
どれも「人と画面が増えたときの問題」です。 私の一覧画面1枚は、そこに当てはまりませんでした。だから入れませんでした。 ただし、③で見たとおり「GraphQL を叩くこと自体」は POST 1本です。 他人が用意した GraphQL の API を使う側に回るなら、迷わず使います。 入れるかどうかを迷うのは、自分がサーバー側も書くときだけです。
つまずいたところ
1. Cannot use import statement outside a module
package.json に "type": "module" を書き忘れました。 3回やりました。
npm init -y で作った package.json には入っていません。import を使うなら、毎回自分で足す必要があります。
確認: "type": "module", の行が出れば大丈夫です。
2. ブラウザから GraphQL を叩いたら、何も返ってこない
CORS でした。
React(5190番)から http://<VMのIP>:4020/graphql を直接叩くと、別オリジンなので弾かれます。Network タブでは「失敗」とだけ出て、原因は Console タブにしか出ません。
私は最初、GraphQL サーバー側に CORS の許可を足そうとしました。 それでも動きましたが、練習中は Vite の proxy のほうが安全です。許可を広く開けたまま忘れることがないからです。
// vite.config.js の中
proxy: { '/graphql': 'http://localhost:4020' }
3. ミューテーションを叩いたのに、画面が変わらない
urql の話ではなく、私のクエリの書き方の問題でした。
mutation Bump($id: ID!) {
incrementView(id: $id) {
id
viewCount
}
}
この id の行を、私は書き忘れていました。
id を返していないと、urql は「どの Post が更新されたのか」を判断できません。
ドキュメントキャッシュなら「Post 型を含むから全部捨てる」で結果的に直りますが、 正規化キャッシュに移った瞬間に壊れます。 ミューテーションの返り値には、必ず id と、変わった項目を全部入れると覚えました。
4. エラーなのに HTTP は 200 で返ってくる
存在しない id を渡して、res.status を見たら 200 でした。
GraphQL では、data と errors が同じ 200 のレスポンスに同居できます。
{
"data": { "post": null },
"errors": [{ "message": "その記事はありません" }]
}
if (!res.ok) だけで判定していると、エラーを素通りします。 もっと厄介なのは、「一部だけ成功」があることです。posts は取れたが author だけ失敗、という状態が正常にありえます。
urql の error はこれをまとめて拾ってくれますが、data が同時に入っていることがあります。 error があるからといって data を捨てないでください。
5. Network タブでキャッシュを見ようとしたら、毎回2本飛んでいた
StrictMode でした。
開発中は React がわざと2回実行します。「キャッシュが効いていない」と30分悩んだあと、そのuseEffectは要らない — React深掘りで同じことに引っかかった記憶が戻ってきました。
数を数えるときだけ StrictMode を外し、数え終わったら必ず戻します。
6. relay-compiler が動かない
2つ、別々の理由で止まりました。
schema.graphqlの場所が違っていた —package.jsonのrelay設定にあるschemaは、package.jsonからの相対パスです- スキーマが Relay の仕様を満たしていなかった — ⑤で書いたとおりです。これは設定ミスではなく、Relay の要求です
私は最初、1と2を切り分けられませんでした。 「パスの問題」なのか「仕様の問題」なのかは、エラーメッセージを最後まで読めば書いてあります。 エラーは下から読むを、また忘れていました。
7. GraphQL にしたのに、サーバーが遅くなった
当然でした。
②の Post.author リゾルバは、記事の数だけ動きます。 データが配列なので今回は速いですが、これがデータベースへの問い合わせだったら、SQL が10回発行されます。
クライアントから見えなくなっただけで、N+1 は消えていません。
サーバー側で、同じ問い合わせをまとめる仕組み(DataLoader など)が別途要ります。 「GraphQL にすれば N+1 が解決する」は、はっきり間違いです。
8. 一覧のクエリに項目を足したら、一覧のキャッシュが全部消えた
クエリ文字列が変わったからです。
ドキュメントキャッシュの鍵は、クエリ文字列(コメントなどを除いたもの)です。項目を1つ足しただけでも、別のクエリとして扱われます。
だから、クエリはコンポーネントの外に定義します。
// ✅ コンポーネントの外。1回だけ作られる
const POSTS = gql`query GetPosts { posts { id title } }`
export default function PostList() {
const [result] = useQuery({ query: POSTS })
return null
}
コンポーネントの中で gql を書いても、中身が同じなら鍵は同じなので、キャッシュは当たります。 鍵はオブジェクトの同一性ではなく、クエリの中身から作られるからです。外に置くのは、再描画のたびに作り直す無駄を省き、どこにどのクエリがあるかを見つけやすくするためです。
後片づけ
この記事の練習場を、全部消します。 VMの中で実行します。
まず、動かしている3つを止めます(それぞれの端末で Ctrl + C)。
~/gqllab/rest-apiのnode server.js~/gqllab/gql-apiのnode server.js~/gqllab/gql-appのnpm run dev
止まったか確かめます。
確認: 何も出なければ、全部止まっています。何か出たら、そのプロセスをまだ止めていません。
消します。
確認: gqllab が消えていて、ufw status に 4020 も 5190 も残っていないこと。
ufwの穴を消し忘れないでください。 練習で開けたポートを開けっぱなしにするのが、一番よくある事故です。開けたら、消すところまでが1セットです。
戻し方: もう一度やりたくなったら、①の
mkdir -p ~/gqllab/rest-apiから順にやり直すだけです。node_modulesは消してよいものなので、遠慮なく消してください(node_modulesは消してよい)。
まとめ — 理解できたこと
- 「取りすぎ」と「足りない」は別の問題。 前者は転送量(49,732バイトのうち使ったのは412バイト)、後者は回数(21回)。片方だけ直しても、画面は速くならない
- 測ってから始める。
curlの出力をwc -cに流すのと、fetchを数えるだけのスクリプト。 それ以上の道具は要らなかった - GraphQL は新しい通信方式ではない。 エンドポイント1本への POST で、ボディは
{"query": "..."}という普通のJSON。curlだけで全部叩ける - クライアントライブラリは必須ではない。 ③で一度もライブラリを入れずに、21回→1回、108KB→658バイトを達成した
- スキーマが契約になる。 「何が取れるか」を先に決めるので、
console.logでレスポンスの構造を探す作業が消える - 値は必ず
variablesで渡す。 クエリ文字列に埋め込まない。 安全のためでもあり、キャッシュの鍵を固定するためでもある - サーバー側の仕事は増える。
res.json(posts)の1行が、型定義 + Query リゾルバ +Post.authorリゾルバになった - N+1 は消えていない。サーバーの中に移っただけ。 往復がメモリアクセスになったのは大きいが、DBが相手なら別途まとめる仕組みが要る
- urql の既定はドキュメントキャッシュ。 クエリ文字列+変数を鍵に、丸ごと覚える。 設定ゼロで動くが、更新すると関連クエリを丸ごと捨てる
- 正規化キャッシュは型とidでバラして覚える。 その代わり、id の付け方と一覧への反映を自分で書く。 粗いキャッシュで実際に困ってから入れる
- Relay は「urql の高機能版」ではない。思想が逆。 コンポーネントが fragment で自分の要求を宣言し、コンパイラが1本のクエリにまとめる
- Relay はサーバー側に規約(
Nodeと Connection)を要求する。 スキーマとリゾルバを全部それに合わせる必要があり、個人開発では重すぎる - HTTP のキャッシュが使えなくなる。 POST 1本なので、ブラウザも CDN も素通り。 ただで付いてきたものを、自分で書くものに交換している
- クライアントに自由を渡すと、守る仕事が増える。 深さ制限・複雑度制限・イントロスペクション停止・永続化クエリ・件数上限は、公開する前に必ず入れる
- 入れる価値があるのは、画面ごとに欲しいデータが大きく違うとき。 Web/iOS/Android で違う部分を使う、要求が頻繁に変わる、複数サービスから集める、作る人と使う人が別チーム
- このサイトの方針: 画面が数枚なら REST。エンドポイントを1本足すほうが速い。
自分がサーバーも書くなら、GraphQL は「入れない」から始める。他人の GraphQL API を使う側なら、fetch で迷わず叩く。 入れないことは、遅れていることではありません。
参考リンク
- roadmap.sh — React
- roadmap.sh — Backend
- GraphQL 公式 — Introduction to GraphQL
- GraphQL 公式 — Queries and Mutations
- GraphQL 公式 — Schemas and Types
- GraphQL 公式 — Best Practices
- GraphQL Yoga 公式ドキュメント
- urql 公式ドキュメント
- urql — React での基本の使い方
- urql — Graphcache(正規化キャッシュ)
- Relay 公式ドキュメント
- Relay — GraphQL Server Specification
- Relay — Cursor Connections Specification
- React 公式 — useEffect
次に読む
この記事は 【深掘り】React の 23 / 24 本目です。
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- 取りすぎと足りないを実測する
- urql と Relay の思想の違い
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント