「やり直し」に強いシステム

このトピックについて

業務システムで最も困るのは、操作ミスやエラーからの復旧です。「同じ請求書が2枚できてしまった」「途中でエラーになったけど、どこまで処理されたかわからない」といった問題は、現場を混乱させます。

このプロジェクトでは、さまざまな「うっかり」に対応できる設計にしました。

同じ請求書を2回送っても大丈夫

「べき等性（Idempotency）」という仕組みで、重複処理を防止しています。

べき等性キーの設計

各リクエストには一意のキーを付与します。同じキーで2回目の送信があった場合は「すでに作成済み」として処理をスキップします。

7日間の記憶

結果は7日間キャッシュに保持されます。1週間以内であれば、「この請求書は作成済みかどうか」を確認できます。

通信エラー時の自動リトライ

ネットワークの一時的な不調や、サーバーの混雑時には、自動的に少し待ってから再試行します。

指数バックオフとジッター

「指数バックオフ」は、リトライの間隔を徐々に長くする手法です。「ジッター」は、ランダムな遅延を加えることで、複数のクライアントが同時にリトライして再び混雑することを防ぎます。

リトライ可能なエラー

すべてのエラーでリトライするわけではありません。一時的なエラーのみリトライします。

詳細なログで問題を特定

いつ・誰が・何を実行して・どうなったかを記録します。エラーが発生した場合も、どの行でどんな問題が起きたかが明確にわかります。

構造化ログの例

{
  "event": "row_processed_error",
  "docType": "invoice",
  "rowNumber": 5,
  "idempotencyKey": "comp1:invoice:001",
  "httpStatus": 422,
  "error": "partner_code not found",
  "timestamp": "2025-01-24T10:30:00.000Z"
}

ログから読み取れること

エラー発生時のフロー

この設計で実現できること

運営側にとって

• 重複請求の防止: 同じ請求書が2枚作成されることはない
• 一時的障害への耐性: 自動リトライで回復
• 原因特定の容易さ: 構造化ログで問題箇所を即座に把握

現場担当者にとって

• 安心して操作できる: ミスしても大丈夫という安心感
• すぐに状況がわかる: ステータス表示で結果を確認
• 簡単に再実行できる: 修正して再送信するだけ

関連するトピック

• べき等性制御の詳細
• 指数バックオフの詳細