Next.js App Router における Server Actions と Route Handlers の使い分け、セキュリティ、および実装規約。
Next.js のサーバーサイド通信において、一貫性・セキュリティ・開発効率を担保するためのルールです。
基本的には Server Actions を第一選択 とし、Route Handlers は特殊なケースに限定します。
| 通信方式 | 推奨される用途 | 配置パス / 命名 |
|---|---|---|
| Server Actions | CRUD操作、フォーム送信、状態変更。クライアントからの一般的なリクエストに優先使用。 | src/server/actions/*.actions.ts |
| Route Handlers | SSE (ストリーミング)、外部 Webhook、Cron ジョブ、特定の HTTP メソッド/ヘッダーが必要な場合。 | app/api/**/route.ts |
'use server'; を記述します。関数レベルでの宣言は避け、 ファイルに集約してください。.actions.ts[feature].actions.ts とします。zod スキーマを使用して parse または safeParse し、型安全を保証します。chat.actions.ts）では、名前衝突回避や明示性のために export const MyActionSA = MyAction; のようなエイリアスを定義している場合がありますが、新規実装において必須ではありません。liffAccessToken を authMiddleware に渡して検証。ensureAuthenticated 等の共通ロジックで検証。viewMode (閲覧モード) が有効な場合、データの「書き込み」や「管理者操作」を拒否し、VIEW_MODE_ERROR_MESSAGE を返却する必要があります。ChatResponse）を定義して返却データをフィルタリングします。app/api/ 内の route.ts に 'use server'; を記述する（不要かつ誤解を招く）。prisma や supabase (Service Role) を呼び出すコードを Server Actions 外に書く。Service Role による DB 操作を行う（重大なセキュリティリスク）。viewMode の際に破壊的操作が制限されているか？zod で入力値を検証しているか？