nodejs-backend

Node.js バックエンド

実装前に確認してください：フレームワーク固有の API（Express 5、Fastify 5、Node.js 22 以降の組み込み機能）を使う場合は、コードを書く前に、現在のバージョンに対応した公式ドキュメントを確認してください。利用できる場合は、Context7 の query-docs を優先してください。それ以外の場合は、利用可能なウェブツールでフレームワークの公式ドキュメントを参照するか、Node.js の組み込み機能については Node.js API ドキュメントを参照してください。学習データは最新リリースに追いついていない可能性があります。

作業ルール

• リクエストやサードパーティーからのデータは、使用前に検証してください。レスポンスのシリアライズとエラーエンベロープは明示してください。
• 回復性やフォールバックを追加する際は、呼び出し元から見える契約と認可を維持してください。
• 同時実行数に上限を設け、タイムアウトを設定し、本番環境のリクエスト処理をブロックしないでください。
• 再利用したクライアントの結果を解析またはキャッシュする前に、リソースの実際の識別情報を確認してください。
• 成功時の戻り値だけでなく、運用テレメトリと障害時の経路も検証してください。

アーキテクチャ

src/
├── routes/          # HTTP: parse request, call service, format response
├── middleware/       # Auth, validation, rate limiting, logging
├── services/        # Business logic (no HTTP types)
├── repositories/    # Data access only (queries, ORM)
├── config/          # Env, DB pool, constants
└── types/           # Shared TypeScript interfaces

• ルートにビジネスロジックを含めないでください。
• サービスから Request／Response をインポートしないでください。
• リポジトリから HTTP エラーをスローしないでください。
• 依存関係は内側に向けてください（クリーンアーキテクチャの原則）：ルート -> サービス -> リポジトリ。逆方向は禁止です。
• スクリプトやプロトタイプでは、単一ファイルで問題ありません。「これは大きくなるか？」と考えてください。

TypeScript のルール

• 型専用のインポートには import type { } を使ってください。実行時のオーバーヘッドをなくせます。
• オブジェクトの形状には interface を優先してください（交差型より型解決が 2～5 倍高速です）。
• any より unknown を優先してください。明示的な型の絞り込みが必要になります。
• z.infer<typeof Schema> を唯一の信頼できる情報源として使ってください。型とスキーマを重複して定義しないでください。
• as によるアサーションは最小限にし、代わりに型ガードを使ってください。
• エクスポートする関数には明示的な戻り値の型を追加してください（宣言の出力が高速になります）。
• 型定義のないパッケージの場合は、types/ambient.d.ts に declare module 'pkg' { const v: unknown; export default v; } を追加してください。

規律

• まずはシンプルに：変更はできるだけ単純にし、影響を及ぼすコードを最小限にしてください。
• 必要な箇所だけを変更し、無関係な変更を持ち込まないでください。
• その場しのぎの回避策は使わないでください。修正が不適切に感じられたら、一度立ち止まり、適切な解決策を実装してください。
• 新しい抽象化を追加する前に、それが 3 か所以上で使われるか確認してください。そうでなければインライン化してください。
• 修正に TypeScript の迂回（as any、信頼できないデータへの非 null アサーション、// @ts-ignore）が必要な場合は、設計上の問題として扱い、型安全な解決策を見つけてください。

検証

• tsc --noEmit がエラーなしで成功すること
• npm test が失敗なしで成功すること
• 新しいコードに TypeScript の迂回（as any、@ts-ignore）がないこと

参考資料

• TypeScript の設定：tsconfig、ESM、ブランド型、コンパイラーのパフォーマンス
• セキュリティ：JWT、パスワードのハッシュ化、レート制限、OWASP
• API 設計パターン：ページネーション、フィルタリング、ソート、非推奨化、冪等性キーの申請と保持
• データベースと本番環境：コネクションプーリング、トランザクション、Docker、ロギング

タスク別の参考資料

該当する動作を実装またはレビューする前に、関連する参考資料を読んでください。

• フレームワークの選定、入力検証、API 契約、またはエラーについては、api-boundaries.md を参照してください。
• 同時実行、ネットワーク、起動、キャッシュ、ライフサイクルのクリーンアップ、またはテレメトリについては、async-and-production.md を参照してください。
• スパンの種類、HTTP ステータスからスパンステータスへのルール、サンプリングの配置、メトリクスのカーディナリティ、またはテレメトリデータのガバナンスについては、observability-tracing.md を参照してください。

該当するトピックに応じて、既存の専門的な参考資料も確認してください。