Node.jsの「死」を飼い慣らす：堅牢なプロダクション環境のための例外ハンドリング・アーキテクチャ
Node.jsの`uncaughtException`は、単なるエラーイベントではない。それは「プロセスの腐敗」の宣言である。
多くのエンジニアが「取り敢えずログを出して終了させる」だけで満足し、再起動の責任をPM2やKubernetesに丸投げしている。だが、真のテックリードは知っているはずだ。中途半端に終了したプロセスは、DBのトランザクションを宙吊りにし、コネクションプールを汚染し、クリーンアップされないテンポラリファイルを残す。これが、後の障害の連鎖（カスケード）を引き起こす最大の要因だ。
本稿では、プロセスが「予期せぬ死」を迎える際に、システム全体へのダメージを最小化し、クリーンな状態で次へバトンを渡すための「Graceful Shutdownアーキテクチャ」を伝授する。
—
1. なぜ「死」の設計が必要なのか
Node.jsのイベントループが例外で停止した瞬間、メモリ上の状態は「信頼できないもの」に変わる。これを無理やり継続させるのは自殺行為だ。我々が目指すべきは、「死ぬ準備が整うまで死なない」ことである。
プロセスのライフサイクルを制御するシグナル処理
OSからの終了シグナル（SIGTERM）と、内部例外（uncaughtException）を同一のフローで処理する設計が重要だ。
/
- 堅牢なシャットダウン・コントローラー
/
const shutdown = async (signal) => {
console.error(`[SYSTEM] ${signal} 受信。クリーンアップを開始します…`);
// 1. 新規リクエストの受け入れを停止（重要）
server.close(async (err) => {
if (err) {
console.error(‘[SYSTEM] サーバー終了時にエラー発生’, err);
process.exit(1);
}
// 2. データベース接続の解放（コネクションリークを防ぐ）
await db.pool.end();
// 3. 全てのキュー処理の完了を待つ（または中断処理）
await queue.flush();
console.log(‘[SYSTEM] クリーンアップ完了。プロセス終了。’);
process.exit(0);
});
// 万が一のデッドロック防止（一定時間後に強制終了）
setTimeout(() => {
console.error(‘[SYSTEM] シャットダウンがタイムアウトしました。強制終了します。’);
process.exit(1);
}, 10000);
};
// 予期せぬエラーの補足
process.on(‘uncaughtException’, (err) => {
console.error(‘[FATAL] 未捕捉の例外:’, err);
// 状態ダンプの実行
dumpState(err);
shutdown(‘uncaughtException’);
});
// OSからのSIGTERM (Kubernetesのローリングアップデート等)
process.on(‘SIGTERM’, () => shutdown(‘SIGTERM’));
—
2. チーム開発を加速させる「設定の神聖化」
個人の環境に依存した設定は、不具合の温床だ。Node.jsプロジェクトにおいて、環境設定は「コードの一部」としてリポジトリに含めるべきである。
.vscode/settings.json による開発ルールの強制
チームメンバーのIDE設定を統一することで、インデントのズレや不要な警告を排除する。
{
“editor.formatOnSave”: true, // 保存時に自動整形
“editor.codeActionsOnSave”: {
“source.fixAll.eslint”: “explicit” // ESLintによる自動修正を強制
},
“javascript.preferences.importModuleSpecifier”: “non-relative”, // 相対パス地獄を回避
“eslint.validate”: [“javascript”, “typescript”]
}
プロの隠れショートカット：生産性を10倍にする
- Cmd+Shift+P (Win: Ctrl+Shift+P) -> “Restart TS Server”: TypeScriptの型推論がバグったとき、再起動するより速い。
- Cmd+P -> :: ファイル内の特定の行へ即座にジャンプ。
- Cmd+Shift+F (Global Search): `TODO` や `FIXME` で検索をかけ、技術負債を可視化する習慣をつけよ。
—
3. なぜ「ツール」を疑うべきなのか：npmの活用と罠
多くのエンジニアが「なんとなく」入れている `npm` だが、その裏側にあるロックファイル（`package-lock.json`）の重要性を理解しているか？
チーム開発のベストプラクティス
1. `npm ci` をCI/CDで絶対使う: `npm install` はロックファイルを更新してしまう可能性がある。CI/CDパイプラインでは必ず `npm ci` を使用し、再現性を保証せよ。
2. Huskyによるコミット前フック: コミットする前に、必ずテストとリントを通す。汚れたコードをリモートにプッシュさせないことこそ、最高効率のアーキテクチャだ。
huskyの導入例
npx husky-init && npm install
npx husky add .husky/pre-commit “npm run lint && npm test”
—
4. 現場のテックリードからの提言
アーキテクチャとは、単にコードを書くことではない。「何が起きてもシステムが壊れない、あるいは壊れても即座に回復する」という信頼そのものを設計することだ。
今回紹介した `uncaughtException` ハンドラは、あくまで保険である。本質的な解決策は、エラーを「予期できる状態（ResultパターンやTypeScriptのUnion Types）」に昇華させ、例外をスローさせないコードを書くことにある。
ツールやプラグインは、その設計を補助する「義手」に過ぎない。しかし、その義手を使いこなせれば、君たちの開発スピードは次元が変わる。
今すぐ `.vscode` 設定をチームで共有し、`SIGTERM` のハンドリングを実装せよ。それが、明日からの君たちのコードを「信頼されるプロダクト」へと変える最初の一歩だ。