nodejs-best-practices

Node.js のベストプラクティス

2025 年における Node.js 開発の原則と意思決定。 コードパターンを暗記するのではなく、考え方を身につけましょう。

使用する場面

Node.js のアーキテクチャを決定するとき、フレームワークを選ぶとき、非同期パターンを設計するとき、またはセキュリティやデプロイのベストプラクティスを適用するときに、このスキルを使用してください。

---

⚠️ このスキルの使い方

このスキルでは、コピーして使う固定コードではなく、意思決定の原則を学びます。

• 不明点があれば、ユーザーに希望を尋ねてください
• コンテキストに基づいてフレームワークやパターンを選んでください
• 毎回同じ解決策を安易に選ばないでください

---

1. フレームワークの選択（2025 年）

判断ツリー

What are you building?
│
├── Edge/Serverless (Cloudflare, Vercel)
│   └── Hono (zero-dependency, ultra-fast cold starts)
│
├── High Performance API
│   └── Fastify (benchmark the actual workload)
│
├── Enterprise/Team familiarity
│   └── NestJS (structured, DI, decorators)
│
├── Legacy/Stable/Maximum ecosystem
│   └── Express (mature, most middleware)
│
└── Full-stack with frontend
    └── Next.js API Routes or tRPC

比較の原則

要素	Hono	Fastify	Express
最適な用途	エッジ、サーバーレス	パフォーマンス	レガシー、学習
コールドスタート	最速	速い	中程度
エコシステム	発展中	良好	最大規模
TypeScript	ネイティブ対応	優秀	良好
学習曲線	低い	中程度	低い

尋ねるべき選択時の質問：

1. デプロイ先はどこですか？
2. コールドスタート時間は重要ですか？
3. チームに既存の経験はありますか？
4. 保守する必要があるレガシーコードはありますか？

---

2. ランタイムに関する考慮事項（2025 年）

ネイティブ TypeScript

Node.js TypeScript support depends on the exact runtime version and syntax; verify the installed release before using type stripping
├── Run .ts files directly
├── No build step needed for simple projects
└── Consider for: scripts, simple APIs

モジュールシステムの選択

ESM (import/export)
├── Modern standard
├── Better tree-shaking
├── Async module loading
└── Use for: new projects

CommonJS (require)
├── Legacy compatibility
├── More npm packages support
└── Use for: existing codebases, some edge cases

ランタイムの選択

ランタイム	最適な用途
Node.js	汎用、最大規模のエコシステム
Bun	パフォーマンス、バンドラーを内蔵
Deno	セキュリティ優先、TypeScript を内蔵

---

3. アーキテクチャの原則

レイヤー構造の概念

Request Flow:
│
├── Controller/Route Layer
│   ├── Handles HTTP specifics
│   ├── Input validation at boundary
│   └── Calls service layer
│
├── Service Layer
│   ├── Business logic
│   ├── Framework-agnostic
│   └── Calls repository layer
│
└── Repository Layer
    ├── Data access only
    ├── Database queries
    └── ORM interactions

重要な理由：

• テスト容易性：レイヤーごとに独立してモックできます
• 柔軟性：ビジネスロジックに触れずにデータベースを切り替えられます
• 明瞭性：各レイヤーが単一の責任を担います

簡素化する場合：

• 小さなスクリプト → 単一ファイルで問題ありません
• プロトタイプ → 構造を簡略化してもかまいません
• 常に「これは成長するか？」と問いかけてください

---

4. エラー処理の原則

集約型エラー処理

Pattern:
├── Create custom error classes
├── Throw from any layer
├── Catch at top level (middleware)
└── Format consistent response

エラーレスポンスの考え方

Client gets:
├── Appropriate HTTP status
├── Error code for programmatic handling
├── User-friendly message
└── NO internal details (security!)

Logs get:
├── Full stack trace
├── Request context
├── User ID (if applicable)
└── Timestamp

ステータスコードの選択

状況	ステータス	場合
入力不正	400	クライアントが無効なデータを送信した
認証なし	401	認証情報がない、または無効
権限なし	403	認証は有効だが、許可されていない
見つからない	404	リソースが存在しない
競合	409	重複または状態の競合
バリデーション	422	スキーマは有効だが、ビジネスルールに違反している
サーバーエラー	500	内部障害。機密情報を除去した診断コンテキストを記録する

---

5. 非同期パターンの原則

使い分け

パターン	使用する場面
async/await	順次実行する非同期処理
Promise.all	独立した処理を並列実行する
Promise.allSettled	一部が失敗する可能性のある並列処理
Promise.race	最初に確定した結果。タイムアウトとの競争では、基盤となる処理はキャンセルされません

イベントループを意識する

I/O-bound (async helps):
├── Database queries
├── HTTP requests
├── File system
└── Network operations

CPU-bound (async doesn't help):
├── Crypto operations
├── Image processing
├── Complex calculations
└── → Use worker threads or offload

イベントループのブロックを防ぐ

• 本番環境では同期メソッドを決して使用しないでください（fs.readFileSync など）
• CPU 負荷の高い処理はオフロードしてください
• 大量のデータにはストリーミングを使用してください

---

6. バリデーションの原則

境界で検証する

Where to validate:
├── API entry point (request body/params)
├── Before database operations
├── External data (API responses, file uploads)
└── Environment variables (startup)

バリデーションライブラリの選択

ライブラリ	最適な用途
Zod	TypeScript を第一に考え、型推論を利用する場合
Valibot	バンドルサイズを小さくしたい場合（ツリーシェイキング可能）
ArkType	パフォーマンスが重要な場合
Yup	既存の React Form の使用

バリデーションの考え方

• 早期に失敗させる：早めに検証する
• 具体的にする：明確なエラーメッセージを表示する
• 信頼しない：「内部」のデータであっても信用しない

---

7. セキュリティの原則

セキュリティチェックリスト（コードではありません）

• 入力検証：すべての入力を検証します
• パラメーター化クエリ：SQL に文字列連結を使用しません
• パスワードのハッシュ化：bcrypt または argon2 を使用します
• JWT の検証：署名と有効期限を必ず検証します
• レート制限：不正利用を防ぎます
• セキュリティヘッダー：Helmet.js または同等のものを使用します
• HTTPS：本番環境では常に使用します
• CORS：適切に設定します
• シークレット：承認済みのシークレットストアまたは保護されたランタイム注入を使用します。シークレットをソース管理に含めないでください
• 依存関係：定期的に監査します

セキュリティ意識

Trust nothing:
├── Query params → validate
├── Request body → validate
├── Headers → verify
├── Cookies → validate
├── File uploads → scan
└── External APIs → validate response

---

8. テストの原則

テスト戦略の選択

種類	目的	ツール
ユニット	ビジネスロジック	node:test, Vitest
インテグレーション	API エンドポイント	Supertest
E2E	一連のフロー全体	Playwright

テスト対象（優先順位）

1. 重要な経路：認証、決済、コアビジネス
2. エッジケース：空の入力、境界値
3. エラー処理：失敗時に何が起きるか
4. テストする価値がないもの：フレームワークのコード、単純なゲッター

組み込みテストランナー（Node.js 22+）

node --test src/**/*.test.ts
├── No external dependency
├── Good coverage reporting
└── Watch mode available

---

9. 避けるべきアンチパターン

❌ しないこと：

• 新しいエッジプロジェクトに Express を使用する（Hono を使用してください）
• 本番コードで同期メソッドを使用する
• コントローラーにビジネスロジックを記述する
• 入力検証を省略する
• シークレットをハードコードする
• 検証せずに外部データを信頼する
• CPU 処理でイベントループをブロックする

✅ すること：

• コンテキストに基づいてフレームワークを選択する
• 不明な場合はユーザーに好みを尋ねる
• 成長するプロジェクトにはレイヤードアーキテクチャを使用する
• すべての入力を検証する
• シークレットには環境変数を使用する
• 最適化の前にプロファイリングを行う

---

10. 判断チェックリスト

実装する前に：

• ユーザーに技術スタックの好みを尋ねましたか？
• このコンテキストに適したフレームワークを選びましたか？（単に既定のものを選んだのではなく）
• デプロイ先を考慮しましたか？
• エラー処理の戦略を計画しましたか？
• 検証が必要な箇所を特定しましたか？
• セキュリティ要件を考慮しましたか？

---

覚えておいてください：Node.js のベストプラクティスは、パターンを暗記することではなく、意思決定に関するものです。すべてのプロジェクトで、要件に基づいて改めて検討する必要があります。

制限事項

• フレームワークの比較は定性的なものであり、バージョンやワークロードによって異なります。例はベンチマークの証拠ではありません。基盤となる I/O には明示的なキャンセルや期限を設定し、診断コンテキストからシークレットや個人を特定できる情報（PII）を除去してください。
• タスクが上記の説明された範囲に明確に当てはまる場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を中断して確認してください。