nodejs-best-practices

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

Nearform が管理する、Node.js および Fastify アプリケーション向けの包括的なガイドです。8 つのカテゴリにわたる 48 のルールを収録し、影響度に基づいて優先順位を付けることで、自動リファクタリングやコード生成を支援します。

適用する場面

次のような場合は、これらのガイドラインを参照してください。

• 新しい Node.js API や Fastify のルートを作成するとき
• データベース操作を実装するとき
• パフォーマンスやセキュリティの問題についてコードをレビューするとき
• 既存の Node.js／Fastify コードをリファクタリングするとき
• API の応答時間を最適化するとき
• エラー処理やログ記録を行うとき
• モニタリングとオブザーバビリティを設定するとき

優先度別のルールカテゴリ

優先度	カテゴリ	影響度	プレフィックス
1	パフォーマンスとセキュリティ	CRITICAL	perf-
2	API 設計とデータベース	CRITICAL	api-
3	エラー処理とログ記録	HIGH	error-
4	Fastify の最適化	MEDIUM-HIGH	fastify-
5	非同期パターン	MEDIUM	async-
6	キャッシュと状態	MEDIUM	cache-
7	コード構成	LOW-MEDIUM	code-
8	モニタリングと診断	LOW	monitor-

クイックリファレンス

1. パフォーマンスとセキュリティ（CRITICAL）

• perf-block-event-loop - イベントループのブロックを検出し、防止する
• perf-security-headers - 必須のセキュリティヘッダーを実装する
• perf-input-validation - すべての入力を検証してサニタイズする
• perf-streaming - 大きなペイロードにはストリームを使用する
• perf-memory-leaks - メモリリークを防止する
• perf-compression - 圧縮戦略を実装する

2. API 設計とデータベース（CRITICAL）

• api-rest-design - RESTful 設計の原則に従う
• api-pagination - 効率的なページネーションを実装する
• api-connection-pooling - コネクションプーリングを使用する
• api-query-optimization - データベースクエリを最適化する
• api-n-plus-one - N+1 クエリ問題を防止する
• api-transactions - トランザクションを適切に処理する

3. エラー処理とログ記録（HIGH）

• error-middleware - エラー処理を一元化する
• error-structured-logging - 構造化ログ（Pino）を使用する
• error-async-errors - 非同期エラーを適切に処理する
• error-sensitive-data - エラーに機密データを含めない
• error-unhandled-rejection - 未処理の拒否を処理する
• error-request-logging - リクエストを効率的にログに記録する

4. Fastify の最適化（MEDIUM-HIGH）

• fastify-schema-validation - JSON スキーマ検証を使用する
• fastify-hooks - フックの使用を最適化する
• fastify-plugins - 再利用可能なプラグインを設計する
• fastify-decorators - デコレーターを効果的に使用する
• fastify-serialization - JSON シリアライズを最適化する
• fastify-content-type - コンテンツタイプを適切に処理する

5. 非同期パターン（MEDIUM）

• async-parallel - 独立した操作を並列化する
• async-error-handling - 非同期エラーを適切に処理する
• async-backpressure - ストリームのバックプレッシャーを処理する
• async-rate-limiting - レート制限を実装する
• async-queue-management - バックグラウンドジョブにキューを使用する
• async-timeout - 操作にタイムアウトを設定する

6. キャッシュと状態（MEDIUM）

• cache-lru - メモリ内の LRU キャッシュを使用する
• cache-redis - Redis キャッシュを実装する
• cache-http-headers - HTTP キャッシュヘッダーを使用する
• cache-invalidation - キャッシュ無効化を実装する
• cache-stale-revalidate - stale-while-revalidate パターンを使用する
• cache-database - データベースクエリをキャッシュする

7. コード構成（LOW-MEDIUM）

• code-module-structure - 機能ごとにコードを整理する
• code-dependency-injection - 依存性注入を使用する
• code-config-management - 設定を適切に管理する
• code-env-variables - 環境変数を扱う
• code-testing - テスト可能なコードを書く
• code-typescript - TypeScript を効果的に使用する

8. モニタリングと診断（LOW）

• monitor-health-check - ヘルスチェックエンドポイントを実装する
• monitor-metrics - アプリケーションのメトリクスを収集する
• monitor-apm - APM ツールを統合する
• monitor-memory - メモリ使用量をモニタリングする
• monitor-cpu - CPU 使用率をプロファイルする
• monitor-distributed-tracing - 分散トレーシングを実装する

使用方法

詳しい説明とコード例については、各ルールファイルをお読みください。

rules/perf-block-event-loop.md
rules/api-n-plus-one.md
rules/_sections.md

各ルールファイルには、次の内容が含まれています。

• 重要である理由の簡単な説明
• 説明付きの誤ったコード例
• 説明付きの正しいコード例
• 追加の背景情報と参考資料

完全版ドキュメント

すべてのルールを詳しくまとめたガイドは、AGENTS.md をご覧ください。