majiayu000 Server Actions & Routes 技術規約
Next.js のサーバーサイド通信において、一貫性・セキュリティ・開発効率を担保するためのルールです。
1. 使い分けの基準
基本的には Server Actions を第一選択 とし、Route Handlers は特殊なケースに限定します。
| 通信方式 | 推奨される用途 | 配置パス / 命名 |
|---|---|---|
| Server Actions | CRUD操作、フォーム送信、状態変更。クライアントからの一般的なリクエストに優先使用。 | src/server/actions/*.actions.ts |
| Route Handlers | SSE (ストリーミング)、外部 Webhook、Cron ジョブ、特定の HTTP メソッド/ヘッダーが必要な場合。 | app/api/**/route.ts |
2. Server Actions 実装ルール
- ファイルレベルの宣言: ファイルの先頭に必ず
'use server';を記述します。関数レベルでの宣言は避け、.actions.tsファイルに集約してください。 - 命名規則: ファイル名は必ず
[feature].actions.tsとします。 - バリデーション: 入力引数は
zodスキーマを使用してparseまたはsafeParseし、型安全を保証します。 - クライアント用インポート: 既存の一部実装（例:
chat.actions.ts）では、名前衝突回避や明示性のためにexport const MyActionSA = MyAction;のようなエイリアスを定義している場合がありますが、新規実装において必須ではありません。
3. セキュリティ & 認証
- 認証の必須化: 認証が必要な全てのアクション/ルートにおいて、処理の先頭で認証チェックを実施します。
- Server Actions: 引数の
liffAccessTokenをauthMiddlewareに渡して検証。 - Route Handlers: ヘッダー（Bearer）または Cookie からトークンを取得し、
ensureAuthenticated等の共通ロジックで検証。
- Server Actions: 引数の
- 特権操作の制限:
viewMode(閲覧モード) が有効な場合、データの「書き込み」や「管理者操作」を拒否し、VIEW_MODE_ERROR_MESSAGEを返却する必要があります。 - エラーハンドリング:
- Server Actions では、ユーザーフレンドリーなエラーメッセージを含むオブジェクトを返却します。
- Route Handlers では、適切な HTTP ステータスコード（401, 403, 429 等）と JSON データを返却します。
- 情報のカプセル化: 内部 ID や不必要な機密情報（API キー等）をクライアントに返さないよう、専用のレスポンス型（例:
ChatResponse）を定義して返却データをフィルタリングします。
4. 実装のアンチパターン
-
app/api/内のroute.tsに'use server';を記述する（不要かつ誤解を招く）。 - クライアントから直接
prismaやsupabase(Service Role) を呼び出すコードを Server Actions 外に書く。 - 認証チェックなしで
Service Roleによる DB 操作を行う（重大なセキュリティリスク）。
セルフレビュー項目
- その機能は Server Action で実装可能か？（SSE 等が必要ないなら Action を選択）
- 経路に応じた適切な共通認証ロジックで検証を行っているか？
-
viewModeの際に破壊的操作が制限されているか？ -
zodで入力値を検証しているか？