API利用時の注文重複：原因と防止策

1回の操作で重複が発生する理由

パネルの管理者がボタンを1回押しただけなのに、フォロワー、再生回数、リアクション、その他のサービスで同一の注文が複数表示されることがあります。通常、問題はクリック自体ではなく、クライアント、API、データベース、サプライヤーの間の連携にあります。

サーバーの観点では、「1回のリクエスト」が常に1回とは限りません。クライアントが応答を受け取れず再送信し、その間に最初の処理がすでに保存されていた可能性があります。パネルのデータベースには1回だけ注文が作成されたのに、サプライヤーには2回送信されることもあります。これらは異なるシナリオであり、修正方法も異なります。

タイムアウトは注文が作成されていないことを意味しない

最も多い原因は、クライアントが一定時間だけ応答を待つことです。サーバーはリクエストを受け取り注文を作成しますが、設定されたタイムアウトより後に応答します。クライアントは操作が失敗したと判断し、再送信します。

その結果、最初の注文はすでにデータベースに存在し、2回目のリクエストがさらに1件作成します。特に、外部APIの応答が遅い場合、キューが過負荷の場合、サービス間の接続が不安定な場合によく発生します。

タイムアウトは応答がないことだけを示し、リクエストが処理されていないことを示すものではありません。

クライアント側での自動リトライ

HTTPリクエスト用ライブラリ、バックグラウンドタスク、連携サービスは、しばしばリクエストを自動的に再試行します。きっかけは、接続エラー、サーバーの応答コード、ネットワーク切断、応答の遅延などです。

再試行自体は有用です。一時的な障害時に失われる注文を減らすからです。このアプローチの欠点は、再処理への対策がないと、あらゆるネットワークの不安定さが重複に変わってしまうことです。

• 再試行はサイトやボットのコードで実行される場合があります。
• キューがタスクを再起動する場合があります。
• プロキシや連携モジュールがリクエストを再試行する場合があります。
• オペレーターがエラー後に手動で注文を再送信する場合があります。

再リクエストが最初の応答より先に届く

2つの同一リクエストがほぼ同時にAPIに到達することもあります。例えば、ユーザーがフォームを2回送信した、フロントエンドがボタンを無効化しなかった、バックグラウンドタスクが最初の完了前に再起動した、などです。

ハンドラーがまず注文の有無を確認してから作成する場合、2つの並列処理が同時にチェックを通過する可能性があります。どちらも注文がまだないと判断し、それぞれが新しいレコードを追加します。

この状況は競合状態と呼ばれます。コード内の単純な事前チェックでは完全には防げません。データベースレベルでの制約がないチェックの欠点は、並列負荷時に破綻することです。

注文は記録されたがAPIの応答が失われた

リクエストは複数の段階を経ます。サーバーがデータを受信し、レコードを作成し、タスクをキューに入れ、応答を送信します。障害はこれらの間のどこでも起こり得ます。例えば、データベースが注文の作成をすでに確定したものの、クライアントへの応答送信前に接続が切断された場合です。

クライアントは注文が受け付けられたか分からず、操作を繰り返します。個別のチェック機構がないAPIは、リクエストを新規として扱います。ログ上では、サービスが「自ら」2件の注文を作成したように見えることがよくありますが、実際には2件の受信リクエストがあったのです。

注文作成用の冪等キー

作成操作には一意の冪等キーが必要です。クライアントは最初の送信前にこれを生成し、注文パラメータとともに送信します。タイムアウトやエラーによる再試行時には同じキーを使用します。

APIはキーを処理結果とともに保存します。既知のキーを持つリクエストが届いた場合、サーバーは新しい注文を作成せず、最初のリクエストの結果（注文ID、ステータス、または以前に生成されたエラー）を返します。

1つのキーは1つのHTTP接続ではなく、1つのビジネス操作に対応する必要があります。

この方法の欠点は、キーの保存、ルールに基づく削除、API側での検証が必要なことです。再試行のたびに新しいキーを生成すると、保護は機能しません。異なる注文に同じキーを使用すると、一部の新規操作が誤って拒否されます。

一意性はデータベースで制御すべき

冪等性はデータベースの一意制約で補完するのが望ましいです。そのために、注文を一意に識別する組み合わせを選択します。内部クライアントID、冪等キー、サービスタイプ、その他の必要なフィールドです。

2つのハンドラーが同時に作成処理に到達した場合でも、データベースは2番目のレコードを拒否する必要があります。競合後、APIは説明のないエラーではなく、既存の注文を返します。

厳格な一意制約の欠点は、リンクやユーザー名だけに基づいて構築できないことです。クライアントは同じチャンネルに対して同じサービスを意図的に複数回注文する場合があります。制約が広すぎると、正常な再購入がブロックされます。

キューはタスクを複数回配信する場合がある

タスクキューはしばしば「少なくとも1回の配信」という原則で動作します。ワーカーがタスクを処理したものの、完了を確認できなかった場合、キューは同じタスクを別のワーカーに再配信する可能性があります。

キューにとってはタスクを失わないための正常な方法です。冪等性のない注文作成にとっては重複の原因となります。タスクIDまたは個別の操作キーを、サプライヤーへの注文送信モジュールを含む最終ハンドラーまで渡す必要があります。

再配信を無効にする欠点は、ワーカーが停止した際に一部の注文が失われる可能性があることです。発生し得る再配信を受け入れ、ハンドラーをそれに対して堅牢にする方が安全です。

重複はパネルとサプライヤーの間で発生する

内部注文は1回だけ作成されたのに、外部APIへのリクエストが2回送信されることがあります。原因は同じです。パネルがサプライヤーから応答を受け取れず、送信を繰り返すことを決定したのです。サプライヤーが最初のリクエストを受け付けていた場合、サプライヤー側に同一の申請が2件表示されます。

内部注文と外部注文を個別に紐付ける必要があります。送信ID、冪等キー、または保存されたサプライヤーの応答です。自社パネルへの入力時の保護が、発信呼び出しを自動的に保護すると考えることはできません。

外部APIとの照合の欠点は、すべてのサプライヤーが外部キーによる検索をサポートしているわけではないことです。その場合、送信試行を記録し、不確定なステータスを個別に調査する必要があります。

Webhookは新しい注文を作成すべきではない

Webhookは変更を通知します。注文が受け付けられた、開始された、完了した、キャンセルされた、または確認が必要である、といった内容です。エラーは、Webhookハンドラーが通知を注文を再作成するコマンドとして解釈した場合に発生します。

同じWebhookが再送される場合があります。送信者は確認を受け取れない場合に配信を繰り返し、通知が順不同で届くこともあります。ハンドラーは外部IDで既存の注文を検索し、ステータスを更新する必要があります。

受信時刻だけでWebhookを処理する欠点は、遅れて届いた通知が最新のステータスを古いもので上書きする可能性があることです。イベントID、ステータスのバージョン、または明確な遷移ルールが必要です。

重複の原因特定に役立つ記録

調査には2つの注文番号だけでは不十分です。各処理段階のデータが必要です。リクエスト時刻、冪等キー、クライアントID、注文パラメータ、バックグラウンドタスク番号、外部APIの応答、再送信の試行などです。

• 重複はリンクだけでなく操作キーで照合してください。
• 受信APIのログに同一リクエストがあったか確認してください。
• キューでタスクが繰り返されたか確認してください。
• 内部注文の作成とサプライヤーへの送信を区別してください。
• 応答受信後すぐに外部申請IDを保存してください。

ログが短すぎる欠点は、問題の原因が調査される前に消えてしまうことです。過剰なログ記録の欠点は、トークン、個人データ、その他の機密フィールドが記録に含まれる可能性があるため、マスクする必要があることです。

不確定なリクエスト結果の処理方法

タイムアウト後、すぐに新しいデータで注文を再作成してはいけません。まずAPIは冪等キーまたはクライアントIDで操作を確認する必要があります。注文が見つかれば、その現在の状態を返します。処理がまだ進行中であれば、クライアントは待機ステータスを受け取ります。

1. 最初のリクエスト前に操作キーを生成します。
2. 再試行のたびに同じキーを送信します。
3. キーと注文をデータベースの1つの保護された操作で保存します。
4. 操作IDをキューと外部APIに渡します。
5. 再リクエスト時に以前作成された注文を返します。

このシナリオにはAPIとクライアント連携の改修が必要です。欠点はデバッグが複雑になり注文の状態が増えることですが、リクエストの再配信が自動的に再購入を意味しなくなります。