- Day 55:データ取得 ― GET APIでデータベースの情報を読み取る
- 今日のゴール
- GETとPOSTの役割を整理する
- データ取得には2つの経路がある
- Day 54の環境を確認する
- APIの返却形式を先に決める
- 今回のステータスコード
- 作成・変更するファイル
- 共有する型を追加する
- 取得サービスを変更する
- 既存のAPIへGETを追加する
- クエリパラメータの検証を理解する
- ブラウザーとcurlで一覧を確認する
- Client ComponentからGET APIを呼び出す
- API確認ページを作る
- POSTとGETを組み合わせて確認する
- 発展:ユーザー1件を取得するGET API
- キャッシュを混同しない
- 読み込み中と失敗を確認する
- 自動取得へ発展させる前に知っておくこと
- セキュリティで特に重要なこと
- 動作確認表
- 本番ビルドも確認する
- 自力で取り組む練習問題
- Day 55のチェックリスト
- まとめ
Day 55:データ取得 ― GET APIでデータベースの情報を読み取る
Day 55では、Next.jsのRoute HandlersとPrismaを使って、データベースに保存したユーザーを取得するGET APIを作ります。Day 54ではPOST APIでデータを保存しました。今回は、その保存したデータをAPIとして返し、ブラウザーから取得して表示します。
学習の中心は、「取得条件を受け取る」「データベースへ問い合わせる」「必要な情報だけ返す」「画面で取得結果を扱う」という流れです。正常に取得できる場合だけでなく、0件、入力不正、存在しないユーザー、取得失敗も区別します。
今日のゴール
今回は、ユーザー一覧APIを中心に実装し、後半でユーザー1件を取得する詳細APIへ発展させます。
| 作るもの | URLの例 | 動作 |
|---|---|---|
| ユーザー一覧API | GET /api/users | 最大20件を返します |
| 件数指定付き一覧API | GET /api/users?limit=5 | 最大5件を返します |
| ユーザー詳細API | GET /api/users/1 | IDが1のユーザーを返します |
| API確認ページ | /users/api-demo | ボタンで一覧APIを呼び出します |
Day 54のPOST /api/usersは残します。同じURLでも、HTTPメソッドによって処理を分けます。
今回のAPIは、ダミーデータを使うローカル学習用です。 認証をまだ実装していないため、Day 54と同じく、開発環境以外ではアクセスを拒否する構成にします。
GETとPOSTの役割を整理する
最初に、これまで作ったPOST APIとの違いを確認します。
| 項目 | GET | POST |
|---|---|---|
| 今回の目的 | データ取得 | データ作成 |
| 例 | ユーザー一覧を見る | 新しいユーザーを登録する |
| 条件・データの渡し方 | パスやクエリ文字列 | JSONのリクエスト本文 |
| 今回のDB操作 | findMany()、findUnique() | create() |
| 正常時のステータス | 200 | 201 |
今回のGET APIにはリクエスト本文を持たせず、取得条件をURLで表現します。Next.jsのRoute Handlersでは、GETやPOSTという名前の関数をexportして、メソッドごとの処理を定義できます。(🔗 nextjs.org)
GETでデータを変更しない
今回の設計では、GETを呼び出してもユーザーの登録・更新・削除は行いません。
GET /api/users
ユーザーを読む
POST /api/users
ユーザーを作る
「URLを開くだけでユーザーが作成される」という設計にはしません。取得処理と変更処理を分けることで、APIの使い方も理解しやすくなります。
データ取得には2つの経路がある
ここは、Next.jsで特に混乱しやすい部分です。
Day 53とDay 54の/usersページでは、Server Componentからサービスを直接呼び出していました。
Server Component
↓
取得サービス
↓
Prisma
↓
データベース
今回のAPI確認ページでは、ブラウザーからGET APIを呼び出します。
Client Component
↓ fetch()
GET API
↓
取得サービス
↓
Prisma
↓
データベース
すべてのデータ取得を、必ず自分のAPI経由にする必要はありません。
Server Componentで使うだけの情報は、サービスから直接取得するほうが自然な場合があります。Next.js公式でも、Server Componentから不要な内部HTTP通信を挟まず、データソースへ直接アクセスする方法が案内されています。(🔗 nextjs.org)
今回は、GET APIの作り方と呼び出し方を学ぶために、API経由の経路を追加します。
Day 54の環境を確認する
次の状態を前提に進めます。
- PrismaからSQLiteへ接続できます。
Userモデルにid、name、emailがあります。src/lib/prisma.tsでPrisma Clientを共有しています。src/services/user.service.tsに取得処理と作成処理があります。src/app/api/users/route.tsにPOSTがあります。- 開発サーバーからユーザー登録できます。
Prisma関連のパッケージは、これまで動作確認できた組み合わせを引き継ぎます。今回のためだけに、バージョンを更新する必要はありません。
また、前回と同じく、cacheComponents: trueを有効にしていない構成を前提にします。
APIの返却形式を先に決める
コードを書く前に、「APIがどのようなJSONを返すか」を決めます。
一覧取得に成功した場合
{
"users": [
{
"id": 2,
"name": "蓮"
},
{
"id": 1,
"name": "葵"
}
],
"returnedCount": 2
}JSONJSONにはコメントを書けないため、JSONの例だけはコメントを付けずに掲載します。
今回は次のルールにします。
usersへ、ユーザーの配列を入れます。- 公開する項目は
idとnameだけです。 returnedCountは、今回返した件数です。- 並び順は、IDの大きい順です。
- 標準の取得上限は20件です。
- 指定可能な取得上限は1〜50件です。
returnedCountは総件数ではありません
データベースに100件のユーザーがあり、今回5件だけ返した場合は、returnedCountは5です。
DB全体のユーザー数:100件
今回返したユーザー数:5件
returnedCount:5
総件数を返す機能は、今回は作りません。「何の件数か」が曖昧にならない名前にします。
0件の場合
{
"users": [],
"returnedCount": 0
}JSON一覧が0件でも、取得処理が正常に完了したなら200です。
一覧の0件と、指定したユーザー1件が存在しない状態は、別々に扱います。
今回のステータスコード
| ステータス | 今回の意味 | 例 |
|---|---|---|
200 | 取得成功 | 一覧や詳細を取得できました |
400 | 指定された条件が不正 | limit=abcです |
403 | この実習では実行を許可しない | 開発環境以外です |
404 | 指定した対象が存在しない | 指定IDのユーザーがいません |
500 | サーバー側の予期しない失敗 | DBの取得処理に失敗しました |
この表を、今回のAPIと画面の共通ルールにします。
作成・変更するファイル
src/
├── app/
│ ├── api/
│ │ └── users/
│ │ ├── [id]/
│ │ │ └── route.ts
│ │ └── route.ts
│ └── users/
│ ├── api-demo/
│ │ └── page.tsx
│ └── page.tsx
├── components/
│ ├── UserCreateForm.tsx
│ └── UserListClient.tsx
├── lib/
│ └── prisma.ts
├── services/
│ └── user.service.ts
└── types/
└── user.ts
既存の/usersページと登録フォームは残します。
GET APIの確認には、新しく作る/users/api-demoを使います。既存画面を大きく変更しないことで、学ぶ対象をGET APIへ絞ります。
共有する型を追加する
Day 54のsrc/types/user.tsへ、一覧表示で使う型を追加します。
src/types/user.ts
// Day 54で作成した、登録用の入力型です
export type CreateUserInput = {
name: string;
email: string;
};
// 今回、APIから公開するユーザーの形です
export type UserSummary = {
id: number;
name: string;
};
// ユーザー一覧APIの成功レスポンスです
export type UsersResponse = {
users: UserSummary[];
returnedCount: number;
};TypeScriptUserSummaryは、データベースの全項目ではありません。
「このAPIで公開するユーザー情報」の形を定義しています。メールアドレスや管理用の値がDBに存在していても、それらを返す必要はありません。
取得サービスを変更する
一覧取得へ件数指定を追加し、詳細取得用の関数も用意します。
src/services/user.service.ts
// サーバー側だけで利用する処理です
import "server-only";
// 共通のPrisma Clientと型を読み込みます
import { prisma } from "../lib/prisma";
import type {
CreateUserInput,
UserSummary,
} from "../types/user";
// ユーザー一覧を取得します
// 引数を省略した既存ページでは、これまでどおり20件です
export async function getUsers(
limit = 20,
): Promise<UserSummary[]> {
// API以外から呼ばれた場合にも、上限を守ります
if (
!Number.isInteger(limit) ||
limit < 1 ||
limit > 50
) {
throw new RangeError("取得件数の指定が正しくありません。");
}
return prisma.user.findMany({
// DBの全項目を返さず、必要な列だけ取得します
select: {
id: true,
name: true,
},
orderBy: {
id: "desc",
},
take: limit,
});
}
// IDを指定して、ユーザーを1件取得します
export async function getUserById(
id: number,
): Promise<UserSummary | null> {
return prisma.user.findUnique({
where: {
id,
},
select: {
id: true,
name: true,
},
});
}
// Day 54のユーザー作成処理も残します
export async function createUser(input: CreateUserInput) {
return prisma.user.create({
data: {
name: input.name,
email: input.email,
},
select: {
id: true,
name: true,
},
});
}TypeScriptPrismaのfindMany()は複数件、findUnique()は主キーなどの一意な条件による取得に使います。selectで取得項目を限定し、takeで件数を制限できます。今回は、これまでの講座で使用しているPrisma 7のAPIを引き継ぎます。(🔗 docs.prisma.io)
なぜサービスでも件数を確認するのか
Route Handlerは、外部から届いた文字列を検証します。
サービス側では、「アプリ内の別の処理から呼ばれても、上限を超える値は受け付けない」というルールを守っています。
役割を整理すると、次のようになります。
- APIは、HTTPの入力が正しいか確認します。
- サービスは、データ取得処理として許可する範囲を守ります。
今回は取得件数という小さなルールですが、処理の入口が増えた場合にも重要な考え方です。
既存のAPIへGETを追加する
Day 54のsrc/app/api/users/route.tsには、すでにPOSTがあります。
ファイル全体を消して置き換えず、既存のPOSTを残して追加します。
importを変更する
既存のサービス読み込みを、次のように変更します。
// POSTとGETが使うサービスをまとめて読み込みます
import {
createUser,
getUsers,
} from "../../../services/user.service";TypeScriptcreateUserを別のimportでも読み込んでいる場合は、重複しないよう整理します。
既存のreply()を確認する
Day 54で作った次の関数を、そのまま使います。すでに存在する場合、もう一度追加しません。
// APIのJSONレスポンスを作る共通関数です
function reply(body: unknown, status: number) {
return NextResponse.json(body, {
status,
headers: {
"Cache-Control": "no-store",
},
});
}TypeScriptNextResponseのimportとruntime = "nodejs"も、既存のものを使います。
GET関数を追加する
同じファイルへ、次の関数を追加します。
// GET /api/users を処理します
export async function GET(request: Request) {
// 認証未実装のため、ローカル学習用に制限します
if (process.env.NODE_ENV !== "development") {
return reply(
{
message: "この取得APIはローカル学習用です。",
},
403,
);
}
// URLのクエリ文字列を読み取ります
const url = new URL(request.url);
const limitValues = url.searchParams.getAll("limit");
// 同じ条件が複数ある場合は、曖昧に処理せず拒否します
if (limitValues.length > 1) {
return reply(
{
message: "limitは1つだけ指定してください。",
},
400,
);
}
// 未指定なら20件にします
const rawLimit = limitValues[0] ?? "20";
// 今回は、先頭ゼロなしの1〜2桁の整数だけを受け付けます
if (!/^[1-9]\d?$/.test(rawLimit)) {
return reply(
{
message: "limitは1〜50の整数で指定してください。",
},
400,
);
}
const limit = Number(rawLimit);
if (limit > 50) {
return reply(
{
message: "limitは1〜50の整数で指定してください。",
},
400,
);
}
try {
// 検証済みの条件を使って取得します
const users = await getUsers(limit);
return reply(
{
users,
returnedCount: users.length,
},
200,
);
} catch {
// DB接続先や入力値を、そのままログへ出しません
console.error("ユーザー一覧の取得に失敗しました。");
return reply(
{
message: "ユーザー一覧を取得できませんでした。",
},
500,
);
}
}TypeScriptこれで、同じファイルにGETとPOSTが並ぶ構成になります。
app/api/users/route.ts
GET
一覧取得
POST
ユーザー作成
Next.jsのRoute Handlersでは、同じroute.tsに複数のHTTPメソッドを定義できます。(🔗 nextjs.org)
クエリパラメータの検証を理解する
今回のAPIでは、次のURLを受け付けます。
/api/users
/api/users?limit=1
/api/users?limit=5
/api/users?limit=50
一方、次の指定は400にします。
/api/users?limit=0
/api/users?limit=-1
/api/users?limit=1.5
/api/users?limit=abc
/api/users?limit=51
/api/users?limit=
/api/users?limit=01
/api/users?limit=5&limit=10
01や同名条件の複数指定を拒否するのは、今回のAPIの仕様です。
数値へ変換するだけでは十分ではありません
今回は、先に文字列の形を確認し、その後で数値へ変換しています。
// 入力形式を確認してから数値へ変換します
if (!/^[1-9]\d?$/.test(rawLimit)) {
// 不正な形式を拒否します
}
const limit = Number(rawLimit);TypeScript「文字列を何とか数値にする」のではなく、APIが許可する表記を先に決めると、入力ルールを説明しやすくなります。
ブラウザーとcurlで一覧を確認する
開発サーバーを起動します。
# Day 54までと同じ開発環境で起動します
npm run devBashブラウザーで、次のURLを開きます。
http://localhost:3000/api/users
GETは、今回のようにアドレスバーへURLを入力して確認できます。
件数指定も試します。
http://localhost:3000/api/users?limit=1
ターミナルでは、次のように確認できます。
# 一覧APIを呼び出し、ステータスとヘッダーも表示します
curl -i "http://localhost:3000/api/users"
# 取得上限を1件にします
curl -i "http://localhost:3000/api/users?limit=1"
# 不正な取得件数を送ります
curl -i "http://localhost:3000/api/users?limit=abc"BashGETには、POSTで使用したJSON本文やContent-Type: application/jsonの指定は必要ありません。
Client ComponentからGET APIを呼び出す
次に、ボタンを押すと一覧を取得する画面を作ります。
今回は通信の開始タイミングを分かりやすくするため、自動取得ではなくボタン操作にします。
src/components/UserListClient.tsx
"use client";
// 画面状態と連続実行防止用の参照を使います
import { useRef, useState } from "react";
// APIが返すデータの型を読み込みます
import type {
UserSummary,
UsersResponse,
} from "../types/user";
// 画面が持つ状態を、ひとつの型で表現します
type LoadState =
| { status: "idle" }
| { status: "loading" }
| { status: "error"; message: string }
| { status: "success"; data: UsersResponse };
// APIのユーザー情報を実行時にも確認します
function isUserSummary(value: unknown): value is UserSummary {
if (typeof value !== "object" || value === null) {
return false;
}
return (
"id" in value &&
typeof value.id === "number" &&
Number.isSafeInteger(value.id) &&
value.id > 0 &&
"name" in value &&
typeof value.name === "string"
);
}
// 一覧APIの成功レスポンスを確認します
function isUsersResponse(
value: unknown,
): value is UsersResponse {
if (typeof value !== "object" || value === null) {
return false;
}
if (
!("users" in value) ||
!Array.isArray(value.users) ||
!value.users.every(isUserSummary)
) {
return false;
}
return (
"returnedCount" in value &&
typeof value.returnedCount === "number" &&
value.returnedCount === value.users.length
);
}
// エラーレスポンスからメッセージだけを取り出します
function readMessage(value: unknown): string | null {
if (
typeof value === "object" &&
value !== null &&
"message" in value &&
typeof value.message === "string"
) {
return value.message;
}
return null;
}
export default function UserListClient() {
const [state, setState] = useState<LoadState>({
status: "idle",
});
// 再描画前の連続クリックも抑えます
const loadingRef = useRef(false);
async function loadUsers() {
if (loadingRef.current) {
return;
}
loadingRef.current = true;
setState({ status: "loading" });
try {
const response = await fetch("/api/users?limit=20", {
method: "GET",
// ブラウザーのHTTPキャッシュを使わず取得します
cache: "no-store",
});
// JSONではない障害レスポンスも想定します
const payload: unknown = await response
.json()
.catch(() => null);
if (!response.ok) {
setState({
status: "error",
message:
readMessage(payload) ??
"ユーザー一覧を取得できませんでした。",
});
return;
}
// TypeScriptの型だけでなく、中身も確認します
if (!isUsersResponse(payload)) {
setState({
status: "error",
message: "取得データの形式が正しくありません。",
});
return;
}
setState({
status: "success",
data: payload,
});
} catch {
setState({
status: "error",
message:
"通信に失敗しました。接続を確認して再度お試しください。",
});
} finally {
loadingRef.current = false;
}
}
const isLoading = state.status === "loading";
return (
<section aria-labelledby="api-users-heading">
<h2 id="api-users-heading">APIからユーザーを取得する</h2>
<button
type="button"
onClick={loadUsers}
disabled={isLoading}
>
{isLoading ? "取得しています…" : "一覧を取得・更新する"}
</button>
{state.status === "idle" && (
<p>ボタンを押すと、GET APIへ問い合わせます。</p>
)}
{state.status === "loading" && (
<p role="status">ユーザーを読み込んでいます。</p>
)}
{state.status === "error" && (
<p role="alert">{state.message}</p>
)}
{state.status === "success" && (
<div>
<p role="status">
{state.data.returnedCount}件取得しました。
</p>
{state.data.users.length === 0 ? (
<p>ユーザーはまだ登録されていません。</p>
) : (
<ul>
{state.data.users.map((user) => (
<li key={user.id}>
ID:{user.id} / 名前:{user.name}
</li>
))}
</ul>
)}
</div>
)}
</section>
);
}TSX状態を分けると画面を判断しやすくなる
今回の画面には、次の状態があります。
| 状態 | 意味 | 表示 |
|---|---|---|
idle | まだ取得していません | 操作の案内 |
loading | 取得しています | 読み込み中 |
successで0件 | 正常取得しましたが空です | 未登録の案内 |
successで1件以上 | 正常取得できました | 一覧 |
error | 取得できませんでした | エラー案内 |
「まだ取得していない状態」と「取得した結果が0件」を、同じ空配列だけで表さないことがポイントです。
response.okを必ず確認する
fetch()は、400や500のHTTPレスポンスを受け取っただけでは、通常catchへ入りません。
HTTPとして失敗しているかは、response.okなどで確認します。通信そのものの失敗はcatchで扱います。(🔗 developer.mozilla.org)
自分のAPIでもレスポンスの形を確認する
今回は、成功時のJSONをunknownとして受け取り、必要な構造か確認しました。
型を付けるだけで内容が保証されるわけではないため、ブラウザーとサーバーの境界では、実際の値を確認することを意識します。
大規模なアプリでは、同じ確認を手書きで増やす代わりに、スキーマ検証ライブラリなどで整理する方法もあります。
API確認ページを作る
src/app/users/api-demo/page.tsx
// Metadataと確認用コンポーネントを読み込みます
import type { Metadata } from "next";
import UserListClient from "../../../components/UserListClient";
// このページのMetadataです
export const metadata: Metadata = {
title: "GET APIの確認",
description: "ユーザー一覧APIを呼び出す学習用ページです。",
};
// ページ自体はServer Componentのままにします
export default function UsersApiDemoPage() {
return (
<section>
<h1>GET APIの動作確認</h1>
<p>
登録済みのダミーユーザーを、ブラウザーから取得します。
</p>
{/* 操作が必要な部分だけをClient Componentにします */}
<UserListClient />
</section>
);
}TSX次のURLを開きます。
http://localhost:3000/users/api-demo
ボタンを押して、DBに保存したユーザーが表示されるか確認します。
Stateやイベントハンドラーが必要なのは操作部品なので、ページ全体をClient Componentにする必要はありません。(🔗 nextjs.org)
POSTとGETを組み合わせて確認する
ここで、Day 54の作成処理とつなげます。
/usersで、未登録のダミーメールアドレスを使って登録します。/users/api-demoへ移動します。- 「一覧を取得・更新する」を押します。
- 作成したユーザーが一覧に含まれるか確認します。
- 別タブでさらに登録し、もう一度取得します。
今回の一覧はIDの大きい順なので、新しく作成したユーザーを確認しやすい構成です。
router.refresh()とClient Componentの再取得は別です
Day 54の登録フォームは、保存後にrouter.refresh()を呼んでいました。
これは、現在のルートのServer Componentを再取得するための操作です。今回のようにClient Component内のStateへ保存した一覧を、必ず自動更新してくれる命令ではありません。(🔗 nextjs.org)
今回のAPI確認画面では、ボタンを押してloadUsers()を再実行します。
将来、登録フォームとAPI一覧を同じ画面へ置く場合は、登録成功後に取得関数を呼ぶ、共有する状態を更新する、といった連携を設計します。
発展:ユーザー1件を取得するGET API
一覧取得ができたら、IDを指定した詳細取得を追加します。
GET /api/users/1
ここでは、Dynamic RouteでIDを受け取ります。
src/app/api/users/[id]/route.ts
// JSONレスポンスと取得サービスを読み込みます
import { NextResponse } from "next/server";
import { getUserById } from "../../../../services/user.service";
// SQLiteドライバーをNode.jsで使います
export const runtime = "nodejs";
// 動的ルートのパラメータ型です
type RouteContext = {
params: Promise<{
id: string;
}>;
};
// このAPIのレスポンスを作ります
function reply(body: unknown, status: number) {
return NextResponse.json(body, {
status,
headers: {
"Cache-Control": "no-store",
},
});
}
// GET /api/users/[id] を処理します
export async function GET(
_request: Request,
context: RouteContext,
) {
// 一覧APIと同じく、開発環境だけで許可します
if (process.env.NODE_ENV !== "development") {
return reply(
{
message: "この取得APIはローカル学習用です。",
},
403,
);
}
const { id: rawId } = await context.params;
// 今回は、先頭ゼロなしの正の整数だけを受け付けます
if (!/^[1-9]\d{0,9}$/.test(rawId)) {
return reply(
{
message: "ユーザーIDの形式が正しくありません。",
},
400,
);
}
const id = Number(rawId);
// 今回のAPIで許可するIDの上限を明示します
if (!Number.isSafeInteger(id) || id > 2_147_483_647) {
return reply(
{
message: "ユーザーIDが許可範囲を超えています。",
},
400,
);
}
try {
const user = await getUserById(id);
if (!user) {
return reply(
{
message: "ユーザーが見つかりません。",
},
404,
);
}
return reply({ user }, 200);
} catch {
console.error("ユーザー詳細の取得に失敗しました。");
return reply(
{
message: "ユーザーを取得できませんでした。",
},
500,
);
}
}TypeScriptRoute Handlersの動的パラメータは、コンテキストのparamsから受け取ります。今回はPromiseをawaitしてIDを取得しています。(🔗 nextjs.org)
APIで404を返すことと、404ページは別です
今回のAPIでは、ユーザーがなければJSONと404を返します。
{
"message": "ユーザーが見つかりません。"
}JSONページ用の見つからないUIを表示するのではなく、APIを呼んだ側が扱えるJSONを返す設計です。
HTMLページを作る処理と、JSON APIを作る処理では、返すものが異なります。
詳細取得をテストする
# 存在するIDを指定します
curl -i "http://localhost:3000/api/users/1"
# 形式が不正なIDです
curl -i "http://localhost:3000/api/users/abc"
# 形式は正しくても、存在しないIDなら404です
curl -i "http://localhost:3000/api/users/2147483647"Bash最後の例は、そのIDのユーザーが登録されていない学習用DBを前提とします。
キャッシュを混同しない
データ取得では、「どこに保存された結果を再利用しているか」を分けて考えます。
| 層 | 今回の対応 | 注意すること |
|---|---|---|
| ブラウザーのHTTPキャッシュ | fetchにcache: "no-store" | 過去のHTTP結果を使わず問い合わせます |
| APIレスポンス | Cache-Control: no-store | レスポンスを保存させない方針です |
| Next.js側の取得処理 | 今回は追加のキャッシュを設定しません | 後から導入したら無効化も設計します |
| ReactのState | 取得結果を保持します | ボタンで再取得するまで同じ結果です |
Next.jsのGET Route Handlerは、既定ではキャッシュされません。ただし、キャッシュを明示的に有効化した構成やCache Componentsを使う構成では、別途その設定に従って考える必要があります。(🔗 nextjs.org)
APIへno-storeを付けても、ReactのStateに入っている一覧が勝手に更新されるわけではありません。
今回の画面では、再取得するタイミングをボタン操作として明示しています。
読み込み中と失敗を確認する
APIが速い場合、読み込み表示は一瞬だけになることがあります。
確認したい場合は、一覧APIのtry内で、getUsers()の前へ次の学習用処理を一時的に入れます。
// 読み込み表示の確認用です。確認後は削除します
await new Promise<void>((resolve) => {
setTimeout(resolve, 1500);
});
// 待機した後で取得します
const users = await getUsers(limit);TypeScript取得失敗を確認する場合は、同じtry内に一時的な例外を入れます。
// エラー表示の確認用です。確認後は必ず削除します
throw new Error("学習用の取得エラーです。");TypeScriptこの確認は、ダミーデータのローカル環境だけで行います。
loading.tsxだけでは、この通信を表現できない
今回のAPI呼び出しは、表示後のボタンイベントで始まります。
そのため、Client ComponentのisLoading相当の状態を使って、取得中の表示を切り替えています。
同様に、GET APIが500を返しても、ページのerror.tsxへ自動的に切り替わるわけではありません。フォーム送信と同じく、HTTP結果を受け取った側で扱います。fetch()のHTTPエラー確認にはresponse.okなどを使います。(🔗 developer.mozilla.org)
自動取得へ発展させる前に知っておくこと
今回はボタン取得ですが、「ページを開いたら自動で取得する」設計も考えられます。
Client ComponentでuseEffectを使う場合は、画面が切り替わった後に古い取得結果が反映されないよう、キャンセルや結果を無視する処理が必要になります。また、開発時のStrict Modeでは、Effectのセットアップとクリーンアップが追加で実行される場合があります。(🔗 react.dev)
取得のタイミング、再取得、重複排除などの要件が増えたら、フレームワークのデータ取得機構や、それらを扱うライブラリも検討します。
まずは今回のボタン方式で、通信と画面状態の関係を理解します。
セキュリティで特に重要なこと
GETでも個人情報は漏えいします
GETはデータを変更しないため、無条件に安全という意味ではありません。
ユーザー一覧を返すAPIを作ると、そのURLへ直接アクセスできる入口ができます。Next.jsのRoute Handlersは公開HTTPエンドポイントなので、保護が必要な情報はAPI側で認証・認可する必要があります。(🔗 nextjs.org)
今回は開発環境限定ですが、この制限を削除するだけで公開可能になるわけではありません。
IDを知っていることと、閲覧できることは別です
/api/users/1のように対象を指定できても、その情報を誰でも見てよいとは限りません。
公開する際は、たとえば次のような条件を設計します。
- 管理者だけがユーザー一覧を取得できます。
- 一般利用者は、自分の非公開情報だけを取得できます。
- 公開プロフィールと管理用情報で、返す項目を分けます。
画面上のリンクを隠すだけでなく、APIやデータアクセス側で権限を確認します。(🔗 nextjs.org)
クエリ文字列へ秘密情報を入れない
GETの条件はURLに表れます。
今回のlimit=5は秘密情報ではありませんが、パスワードや非公開トークンなどを検索条件としてURLへ含める設計は避けます。GETのURLがログなどに記録される可能性も考える必要があります。(🔗 nextjs.org)
件数制限だけで負荷対策が完成するわけではない
最大50件にしても、短時間に大量のリクエストが来る可能性は残ります。
公開APIでは、必要に応じて認証、レート制限、タイムアウト、インデックス、ページネーションなどを組み合わせます。Next.jsのバックエンド設計でも、レート制限や入力検証、保護対象へのアクセス確認が重要です。(🔗 nextjs.org)
エラーの詳細をそのまま返さない
DBのエラーには、内部構造や接続情報など、利用者へ公開する必要のない内容が含まれる可能性があります。
利用者向けと調査用を分ける
利用者には、再試行など次の行動が分かるメッセージを返します。調査用の情報は、公開範囲を管理したログで扱います。
今回の原則
取得できる情報を、すべてレスポンスやログへ出さないことです。APIのエラーメッセージにも、機密情報を含めないようにします。(🔗 nextjs.org)
動作確認表
| 確認内容 | 操作 | 期待する結果 |
|---|---|---|
| 一覧取得 | GET /api/users | 200、最大20件 |
| 件数指定 | GET /api/users?limit=1 | 200、最大1件 |
| 不正な文字列 | limit=abc | 400 |
| 範囲外 | limit=51 | 400 |
| 同名条件の複数指定 | limit=1&limit=2 | 400 |
| 詳細取得 | 存在するユーザーID | 200 |
| ID形式不正 | /api/users/abc | 400 |
| 詳細の未存在 | 存在しない有効範囲のID | 404 |
| 取得失敗 | 学習用例外を一時追加 | 500、画面にエラー |
| POSTとの共存 | Day 54のフォームで登録 | 作成処理も動作 |
| 開発環境以外 | 本番起動でAPIを呼ぶ | 今回の制限により403 |
0件のテストは、別の空の学習用DBなどで行います。0件を確認するためだけに、既存データをまとめて削除しないようにします。
本番ビルドも確認する
# 生成クライアントを確認・更新します
npx prisma generate
# TypeScriptの整合性を確認します
npx tsc --noEmit
# 本番用にビルドします
npm run build
# 本番用サーバーを起動します
npm run startBash今回のGET APIは、本番起動では403を返します。
API確認画面で、そのメッセージをエラー表示できれば、HTTPの失敗結果も扱えています。開発用の制限を解除して公開する場合は、その前に認証・認可などを追加します。
自力で取り組む練習問題
取得件数を画面で変更する
画面へ選択欄を追加し、5件、10件、20件から選べるようにします。
- 選択した件数をStateで管理します。
- GETのクエリ文字列へ反映します。
- 表示件数と、指定した上限の違いを確認します。
- API側の件数検証も残します。
「20件指定したのに3件しか返らない」場合でも、DBに3件しかなければ正常です。
詳細APIを画面から呼ぶ
ユーザーIDの入力欄を作り、GET /api/users/[id]を呼び出します。
- 取得前を表示します。
- 読み込み中を表示します。
- 取得成功時にユーザー名を表示します。
- 404の場合は見つからないことを案内します。
- 400や500も区別して確認します。
名前検索を追加する
GET /api/users?keyword=葵のような検索へ発展させます。
実装前に、検索対象、最大文字数、空文字の意味、件数制限との組み合わせを決めます。URLから受け取った文字列を、そのまま無制限に使わない設計を考えます。
Day 55のチェックリスト
- 既存のPOSTを残したままGETを追加できました。
- 一覧APIからDBのデータを返せました。
- 必要な項目だけを取得・返却できました。
- 取得件数をURLから受け取り、検証できました。
- 一覧の0件と、詳細の404を区別できました。
- Client ComponentからGET APIを呼び出せました。
- 未取得・取得中・成功・0件・失敗を表示できました。
response.okでHTTPの結果を確認できました。- 再取得とReactのStateの関係を説明できます。
- Server Componentからは、サービスを直接呼べると理解しています。
- GETにも認証・認可や公開項目の設計が必要だと理解しています。
まとめ
Day 55では、GET APIを使って、データベースに保存したユーザーを取得しました。一覧取得では件数を制限し、詳細取得ではIDを検証して、存在しないユーザーと取得障害を区別しました。
今回の中心は、「取得条件を検証する」「必要な情報だけ取得する」「結果をHTTPで返す」「画面で状態を分けて扱う」という流れです。
Day 54のPOSTと今回のGETがそろうことで、登録したデータをAPI経由で読み取れるようになりました。対象が記事やタスクへ変わっても、この基本構造を土台にCRUDアプリを組み立てられます。
