エラーハンドリング

原則

• エラーは例外ではなく、予期されるものです。 ネットワーク呼び出しは失敗します。ユーザーは無効な入力を提供します。ディスクが満杯になります。障害を流れの正常な部分として扱ってください。
• 適切なレベルでエラーを処理します。 決定を下すのに十分なコンテキストを持つレイヤーがエラーを処理します。下位レイヤーはコンテキストとともに伝播させます。エラーを隠蔽したり、黙って無視したりしません。
• コンテキストを提供します。 「失敗しました」というエラーメッセージは無用です。どの操作が失敗したのか、入力は何であったのか、呼び出し元が何をすべきかを含めてください。
• エラーを隠蔽しません。 何も起きなかったかのように実行を続ける空の catch ブロックは、本番環境で表面化するのを待っているバグです。

---

システム境界での処理

システム境界は外部データがシステムに入る場所です。HTTPリクエスト、メッセージキューコンシューマー、CLI引数、ファイルアップロード。

• ビジネスロジックに触れる前に、すべての入力を検証します。 型、フォーマット、長さ、許可された値をチェックしてください。
• 構造化されたエラーレスポンスを返します。 クライアントは人間が読める形式のメッセージだけではなく、機械可読なエラーコードが必要です。

  { "error": "VALIDATION_FAILED", "field": "email", "message": "must be a valid email address" }
  

• エラーレスポンスで内部の詳細を決して公開しません。 スタックトレース、SQLエラー、内部パス、システムバージョン。
• 完全なエラーを内部的にログに記録します。 サニタイズされたレスポンスはクライアントに送信し、完全なコンテキスト(スタックトレース、リクエストID、入力)はロギングシステムに送信してください。

---

ビジネスロジック内での処理

ビジネスロジックはアプリケーションのコアです。ここでのエラーはドメインイベントであり、インフラストラクチャの予期しない問題ではありません。

• 型付きカスタムエラーを使用します。 ジェネリックな Error は呼び出し元に何も伝えません。InsufficientFundsError、OrderAlreadyShippedError、UserNotFoundError は意味を伝え、選択的に処理できます。
• コンテキストとともに伝播させます。 再スローする場合は、元のエラーをラップしてください:

  throw new PaymentProcessingError("failed to charge card", { cause: originalError, orderId })
  

• 早期に失敗させます。 関数の開始時に前提条件を検証してください。無効な状態をロジックの深くまで伝播させ、後で不可解に失敗させないでください。
• 不可能な状態を表現できなくします。 実行時にチェックするのではなく、型システムを使用して無効な組み合わせをコンパイル時に排除してください。

---

インフラストラクチャコード内での処理

インフラストラクチャコードはデータベース、外部API、メッセージキュー、ファイルシステムと通信します。これらのコンポーネントは一時的に失敗します。

• 指数バックオフを使用して一時的な障害を再試行します。 ネットワークの不具合、レート制限、一時的な利用不可は再試行可能です。認可エラーと検証エラーはそうではありません。
• サーキットブレーカーを使用します。 ダウンストリームサービスが一貫して失敗している場合、それを叩き続けるのをやめてください。サーキットをオープンにして、高速に失敗を返し、回復の時間を与えてください。
• すべての外部呼び出しにタイムアウトを設定します。 タイムアウトなしの呼び出しは永遠にハング可能性があります。すべてのネットワーク呼び出し、データベースクエリ、外部サービス呼び出しに明示的なタイムアウトが必要です。
• グレースフルに機能低下します。 重要でない依存関係が失敗した場合(レコメンデーションサービス、分析呼び出し)、メインの流れは完全に失敗するのではなく、機能を削減して継続すべきです。

---

アンチパターン

これらのパターンは避けてください。バグを見つけにくくし、本番環境のインシデント診断を困難にします。

アンチパターン	有害な理由
空の catch ブロック	エラーを黙って破棄します。プログラムは無効な状態で継続します。
コンテキストなしで catch して再 throw する	元のエラーメッセージとスタックトレースを失います。
失敗の場合 null または undefined を返す	すべての呼び出し元がチェックする必要があり、多くの場合そうしません。
ログして throw する	重複するログエントリと混乱したスタックトレースを生成します。ログまたは throw 、両方ではなく。
汎用的なエラーメッセージ	「何か問題が発生しました」はユーザーやオンコール エンジニアにとって実行不可能です。
Error をキャッチして特定のエラーを無視する	広すぎます。期待されたエラーとともに予期しないエラーも抑制します。