handling-failures

失敗の処理

必須の前提知識： principal-engineering スキル。

概要

握りつぶされたエラーは、証拠が失われたバグです。基本契約は次のとおりです。すべての失敗経路は、次の3つのうちいずれか1つだけを実行し、いずれも明確に表面化させます。 誤ったデータを提供しながら正常に見えるシステムは、クラッシュするシステムよりも悪質です。

契約

すべての catch と失敗経路は、次のいずれかを実行します。

1. WARN または ERROR でログを記録し、再スローする、または
2. ログを記録し、呼び出し元が処理しなければならない型付きの失敗を返す（結果型、sealed error、コンパイラーまたは契約によって後続コードが認識せざるを得ないステータス）、または
3. ログを記録し、明示的に文書化された縮退モードに入る（コードとそのドキュメントで名前が付けられ、システムが縮退状態であることを示す観測可能な情報がある）。

例外なく禁止：

• catch して何もせず続行すること。
• 失敗を隠す catch-and-return-default（空のリスト、null、0、キャッシュされたコピー）。
• プライマリ処理の失敗を隠す ?? fallback とその類似パターン。フォールバックを使う場合、欠如についても別の場所で明確に表面化させる必要があります。

帰結

• 必須のエントリーが欠けていたら、明確に失敗させます。 レジストリ、設定、カタログに何かが存在しない場合、それはビルドまたは起動の失敗であり、暗黙のデフォルトではありません。
• エラー状態を可視化します。 ワークフローが失敗中なのに正常に見えてはなりません。UI、メトリクス、または実際に誰かが確認しているログにエラー状態を表示します。
• 運用担当者向けの対処方法は具体的にします。 「接続に失敗しました。REDIS_URL と、redis が PING に応答するかを確認してください」は、「エラーが発生しました」よりも適切です。
• 再試行には上限を設け、観測可能にします。
• 副作用のある操作のリプレイは冪等にします。
• 縮退モードには上限を設けます。 スキップして続行する場合、縮退状態から中止に切り替える明示的なしきい値を、名前付きの運用担当者が調整可能な定数として設ける必要があります。ガードは必ず実装します。その値は、オーナーと相談して判断します。上限のない縮退モードは、時間をかけてゆっくりと失敗を握りつぶすようなものです。
• 失敗経路では、可観測性は最低限の要件であり、過剰な装飾ではありません。 ログ行、カウンター、アラートを修正と同時に提供します。これらのない失敗経路は、意図を良くしただけのサイレントな握りつぶしです。

既存の握りつぶし箇所に手を入れる場合

編集対象のコードにすでに握りつぶし箇所がある場合は、作業の一環として修正するか、何を隠しているのかを明記して、未対応事項として明示してください。黙って残すことは、その処理を容認することになります。レビューでは、新しいサイレントな握りつぶしは自動的に BLOCKER となります。既存の握りつぶし箇所に手を入れながら、指摘せずに残した場合は、その変更に対する WARNING となります。

よくある間違い

• 握りつぶす理由として「決して起きないはず」を挙げること。そのような経路こそ、発生したときに大きなアラームが必要です。
• DEBUG でログを記録して、処理済みとみなすこと。本番環境で誰にも見られないのであれば、それは手順を増やしただけの握りつぶしです。
• 狭い範囲を処理するために、広く (Exception、catch {}) catch すること。想定外の失敗が、想定内の失敗のそばで黙って消えてしまいます。
• 誰も文書化していない縮退モードを設けること。作成者しか知らない縮退は、運用担当者が診断できない障害です。
• 失敗をデフォルト値に置き換えてテストを通すこと。テストは成功し、欠陥は本番環境へと持ち越されます。