CRUDアプリで重複レコードを防ぐ：実践的な対策

重複レコードとは何か、なぜ起きるのか

重複レコードとは、アプリが同じものを二度保存してしまうことです。たとえば同じチェックアウトに対する二つの注文、同じ内容のサポートチケットが二件、あるいは同じサインアップフローから作られた二つのアカウントなどです。CRUDアプリでは、個々の行は一見普通に見えますが、データ全体として見ると誤りです。

多くの重複は普通の操作から始まります。ページが遅く感じられて誰かがCreateを二回クリックしてしまう。モバイルではダブルタップは見落としやすい。ボタンがまだ有効に見えて「何も起きていない」ようなら、注意深いユーザーでも再度試します。

その後はさらにややこしい層が絡みます：ネットワークやサーバーです。リクエストがタイムアウトして自動的に再送されることがあります。クライアントライブラリが最初のPOSTが失敗したと判断して繰り返すこともあります。最初のリクエストは成功しているのにレスポンスが失われ、ユーザーが再試行して二重に作られる、ということも起きます。

これを一層だけで解決することはできません。各層は物語の一部分しか見ていないからです。UIは偶発的な二重送信を減らせますが、接続の再試やネットワーク障害を止めることはできません。サーバーは再送を検出できますが、「これは同じcreateだ」と認識する信頼できる方法が必要です。データベースはルールを強制できますが、「同じもの」が何かを定義しておく必要があります。

目標は単純です：同じリクエストが二度来ても作成が安全であること。二回目の試行は何もしない(no-op)、すでに作成済みであることを明確に返す、あるいは制御された競合を返すべきであり、二つ目の行が増えてはいけません。

どこで重複が入り込むか（クライアント、ネットワーク、サーバー）

多くのチームは重複をデータベースの問題だと考えがちです。しかし実際には、同じcreateアクションが複数回トリガーされたときに重複は生まれます。

クライアント側：ユーザーが二回送信する

ユーザーがCreateを押して何も起きないように見えると、再度押します。Enterを押してからすぐボタンをクリックすることもあります。モバイルでは短い間に二回タップが入ったり、タッチとクリックイベントが重なったり、ジェスチャが二重に記録されたりします。

ネットワークと輸送：リクエストが再送される

ユーザーが一回だけ送信しても、ネットワークが同じリクエストを繰り返すことがあります。タイムアウトがリトライを引き起こすことがあります。オフラインアプリは「保存」をキューに入れ、再接続時に再送します。HTTPライブラリの中には特定のエラーで自動的にリトライするものがあり、重複行ができるまで気付かないこともあります。

サーバー側：リトライ、Webhook、バックグラウンドワーカー

サーバーは意図的に作業を繰り返すことがあります。ジョブキューは失敗したジョブを再試行します。Webhookプロバイダは、エンドポイントが遅いか非2xxを返すと同じイベントを何度も届けることがよくあります。これらのイベントでcreateロジックが起動するなら、重複は起こると考えておくべきです。

同時実行：二つのリクエストが競合する

同時実行は最も厄介な重複を生みます。二つのタブが同じフォームをミリ秒単位で送信する場合、サーバーが「存在するか？」とチェックしてから挿入する処理を行うと、どちらのリクエストもチェックを通過してしまい、両方が挿入される可能性があります。

クライアント、ネットワーク、サーバーを別々の再送の原因とみなし、すべてに対する防御が必要です。

まずはデータベースの一意制約（最後の防衛線）

重複を阻止する信頼できる一箇所が欲しいなら、ルールをデータベースに置いてください。UIやサーバーのチェックは役に立ちますが、リトライや遅延、同時ユーザーの操作下では失敗することがあります。データベースの一意制約は最終的な権威です。

人々がレコードをどう認識するかに合う現実的な一意性ルールを選びましょう。一般的な例：

• ユーザーのメールアドレス
• 購入の注文番号
• 支払いプロバイダからの外部ID（external_id）

フルネームのように一意に見えるが実際は違うフィールドには注意してください。

ルールが決まったら、一意制約（または一意インデックス）で強制します。これにより、二つのリクエストが同時に来ても二回目の挿入が拒否されます。

制約が発動したらユーザーにどう見せるかを決めておきます。重複作成が常に誤りなら明確なメッセージで弾きます（「そのメールは既に使われています」）。リトライがよくあるケースでレコードが既に存在するなら、再試行を成功として既存レコードを返す方が良いことが多いです（「あなたの注文は既に作成済みです」）。

ルールに合う安全な書き込みパターンを使う

「作るか再利用する（create or reuse）」がビジネス上自然なら、upsertが最もきれいなパターンです。例：「メールで顧客を作る」は新しい行を挿入するか既存を返すようにできます。これはビジネス上妥当な場合にのみ使ってください。ほぼ同じキーに対して微妙に異なるペイロードが届く可能性があるなら、どのフィールドを更新してよいか、どれを不変にするかを決めておきます。

一意制約は冪等性キーや適切なUIに取って代わるものではありませんが、他が依存できる堅牢なストッパーを提供します。

冪等性キー：繰り返しのCreateを安全にする

冪等性キーは「この注文を一度だけ作る」といったユーザーの意図を表す一意のトークンです。同じリクエストが再度送られた場合（ダブルクリック、ネットワークリトライ、モバイルの再開など）、サーバーはそれを新しい作成ではなく再試行として扱います。

クライアントが最初の試行の成否を判断できない場合、Createエンドポイントを安全にする最も実用的な手段の一つです。

重複が高コストまたは混乱を招くエンドポイント（注文、請求書、支払い、招待、サブスクリプション、メールやWebhookをトリガーするフォームなど）は特に恩恵を受けます。

リトライ時には、サーバーは最初の成功時の結果を返すべきです。作成したレコードIDやステータスコードも同じにします。そのために、（ユーザーまたはアカウント）+エンドポイント+冪等性キーをキーにして小さな冪等性レコードを保存します。結果（レコードID、レスポンス本文）と、「進行中」の状態も保存しておくと、ほぼ同時の二つのリクエストが両方とも新規作成することを防げます。

冪等性レコードは実際に起こりうるリトライをカバーするだけの期間保存してください。一般的な基準は24時間、支払いでは48〜72時間が多いです。TTLを設定して保存を制限し、クライアントが再試行する可能性のある期間に合わせます。

チャット駆動のビルダでAPIを生成する場合でも（例：Koder.ai (koder.ai)）、冪等性を明示的に設計してください：クライアント送信のキー（ヘッダやフィールド）を受け付け、「同じキーなら同じ結果」をサーバーで保証します。

ステップバイステップ：Createエンドポイントに冪等性を追加する

冪等性によりCreateリクエストを繰り返し安全にできます。クライアントがタイムアウトで再試行したりユーザーが二回クリックしても、サーバーは二つ目の行を作らず最初と同じ結果を返します。

実用的な5ステップレシピ

1. ユーザーの操作ごとに1つの冪等性キーを作る（例：ユーザーが「請求書を作成」したとき）。クライアントで生成し、その操作中は安定に保持する。
2. その作成を試すたびにキーをリクエストに添える。Idempotency-Keyのようなヘッダが使いやすいが、JSON本文に入れてもよい。
3. サーバー側で、誰が呼んでいるか（user or account）、どのエンドポイントか、どのcreateを表すかという明確なスコープでキーを保存する。最終的なレスポンスペイロードも保存する。
4. 同じスコープで同じキーが再度来たら、何も作らず保存済みのレスポンス（元のレコードIDを含む）を返す。
5. 高負荷下でテストする：急速なクリック、クライアントのリトライ、偽のネットワークタイムアウトをシミュレートし、正確に1つだけレコードが作られることを確認する。

サーバーのロジックはこうなる

重要なのは「チェック＋保存」が並行性の下で安全であることです。実務では、冪等性レコードに対して (scope, key) の一意制約を付け、競合が起きたら既存を再利用するという扱いをします。

if idempotency_record exists for (user_id, key):
  return saved_response
else:
  begin transaction
  create the row
  save response under (user_id, key)
  commit
  return response

例：顧客が「請求書を作成」してアプリがキー abc123 を送ると、サーバーは請求書 inv_1007 を作ります。電話の電波が切れて再送されたとしても、サーバーは同じ inv_1007 を返し、inv_1008 は作りません。

テストでは「ダブルクリック」だけで満足してはいけません。クライアントでタイムアウトが起きてもサーバー側で処理が完了しているシナリオを再現し、同じキーで再試行したときに正しい動作を確認してください。

偶発的な二重送信を防ぐUIの工夫

サーバー側の防御は重要ですが、多くの重複は人間が同じ操作を繰り返すことから始まります。良いUIは安全な経路を明確にします。

送信と同時にボタンを無効化しましょう。最初のクリックで行い、バリデーション後やリクエスト開始後では遅すぎます。フォームがEnterとボタンなど複数のコントロールで送信できるなら、ボタンだけでなくフォーム全体の状態をロックしてください。

「動いているか？」という質問に答える明確な進行表示を出します。単純な「保存中…」ラベルやスピナーで十分です。レイアウトが変わってボタンが動くと、再度クリックを誘発するのでレイアウトは安定させます。

少ないルールでほとんどの二重送信を防げます：送信ハンドラの開始時に isSubmitting フラグを立て、真の間は新しい送信を無視し（クリックとEnterの両方）、本当に応答が返るまでフラグをクリアしない、という具合です。

遅いレスポンスが多くのアプリの落とし穴です。固定タイマー（たとえば2秒で再度有効にする）で再有効化すると、最初のリクエストがまだ完了していない間に再送されてしまいます。再有効化は試行が完了したときだけ行ってください。

成功後は再送を起こしにくくします。生成されたレコードページや一覧に遷移する、あるいは作成成功の明確な表示で作成済みであることを示すなど、同じ記入済みフォームをそのまま残してボタンを有効にしておかないでください。

タブ、リフレッシュ、モバイルなどのエッジケース

しつこい重複バグは、二つのタブ、リフレッシュ、電話の電波切れといった「よくある珍しい」振る舞いから来ます。

まず、一意性のスコープを正しく定義してください。「一意」は滅多に「データベース全体で一意」を意味しません。多くの場合はユーザーごと、ワークスペースごと、テナントごとなどのスコープが入ります。外部システムと同期する場合は、外部ソースごとの一意制約と外部IDの組を使う必要があるかもしれません。安全な方法は、自分が意味する文を一言で書き下すことです（例：「テナントごとに1年単位の請求書番号は1つ」）。それを強制してください。

マルチタブは古典的な落とし穴です。UIの読み込み状態は同一タブでは役立ちますが、タブをまたいだ動作は防げません。ここでサーバー側の防御が必要になります。

Backボタンやリフレッシュは偶発的な再送を引き起こします。成功後にユーザーが確認のためにリフレッシュしたり、戻るを押してまだ編集可能に見えるフォームを再送信することがあります。作成直後はフォームではなく作成後ビューを優先し、サーバーは安全なリプレイを処理するようにしましょう。

モバイルは中断が入りやすい：バックグラウンド化、回線の不安定さ、自動リトライなどです。リクエストは成功しているがアプリがレスポンスを受け取れず、再開時に再送されることがあります。

よくある誤りと罠

最も一般的な失敗はUIだけを頼りにすることです。ボタンを無効化しスピナーを出すことは助けになりますが、リフレッシュ、モバイルの不安定さ、複数タブ、クライアントバグをカバーしません。サーバーとデータベースが「このcreateは既に終わっている」と言えるようにする必要があります。

別の罠は、間違ったフィールドを一意にすることです。姓や丸めたタイムスタンプ、自由形式のタイトルのように本当は一意でないものに一意制約を置くと、有効なレコードがブロックされます。代わりに外部プロバイダIDのような実際の識別子や、スコープ付きのルール（ユーザーごと、日ごと、親レコードごと）を使ってください。

冪等性キーも誤って実装しやすい点があります。クライアントが毎回のリトライで新しいキーを生成していると、毎回新しい作成が発生します。最初のクリックからすべてのリトライにかけて同じキーを保持してください。

また、リトライ時に何を返すかにも注意してください。最初のリクエストがレコードを作成していた場合、リトライは同じ結果（少なくとも同じレコードID）を返し、ユーザーが再試行したくなるような曖昧なエラーを返してはいけません。

一意制約が重複を弾いたときは「何かが間違った」とだけ表示しないでください。平易な言葉で説明しましょう：「この請求書番号は既に存在します。元のレコードを保持し、二つ目は作成しませんでした。」

出荷前の簡単チェックリスト

リリース前に、重複作成経路だけを対象に簡単な確認を行ってください。複数の防御層を重ねることで、見落としやクリック、遅いネットワークによって二行できるのを防げます。

次の3点を確認してください：

• データベースのルールが現実に合っているか（一意制約が本番に存在し、正しくスコープされている）。
• 重要なCreateエンドポイントが繰り返し安全であるか（冪等性キーが同じ結果を返す）。
• UIが状態を明確に示しているか（送信を無効化、進行表示、作成後の明確なビュー）。

実用的な感覚チェック：フォームを開き、素早く2回送信してから送信中にリフレッシュして再度試してみてください。二つ作れてしまうなら、実際のユーザーも同じことをしてしまいます。

例：請求書を重複なく作る

小さな請求アプリを想像してください。ユーザーが新しい請求書を入力してCreateを押します。ネットワークが遅く、画面がすぐに変わらないので二度タップしてしまう場面です。

UIだけの保護なら、ボタンを無効化してスピナーを出すかもしれません。それでも十分とは言えません。デバイスによってはダブルタップが通ることもあり、タイムアウト後にリトライが来たり、別タブから送信されることもあります。

データベースの一意制約だけなら厳密な重複は止められますが、ユーザー体験が荒くなりがちです。最初のリクエストは成功しており、二回目が制約で弾かれるとユーザーにはエラーが表示されますが実際は既に作成済みという状況になります。

きれいな結果は冪等性＋一意制約です：

• クライアントはCreateアクションに対して冪等性キーを生成し、リトライ時に再利用する。
• サーバーはキーと結果を保存し、同じキーの再試行には同じ請求書IDを返す。
• 一意制約は、異なるキーが同じ請求書番号を作ろうとしたときの最後の保護として機能する。

二回目のタップに対するシンプルなUIメッセージ：「請求書を作成しました — 重複送信は無視して最初のリクエストを採用しました。」

次の一手：アプリが成長しても信頼性を保つ

ベースラインが整ったら、次の改善は可視化、クリーンアップ、整合性に関するものです。

作成パス周りに軽量のログを追加して、本当にユーザーがアクションを起こしたのかリトライなのかを判別できるようにします。ログには冪等性キー、関係する一意フィールド、結果（作成されたか既存を返したか、拒否されたか）を含めます。必ずしも重いツールは必要ありません。

既に重複がある場合は、明確なルールと監査証跡を用いてクリーンアップしてください。たとえば古いものを勝者とし、関連テーブル（支払い、行項目）を再接続し、他をマージ済みとしてマークする（削除ではなく）とサポートやレポートが楽になります。

一意性と冪等性のルールを一箇所に書き残してください：何が一意でどのスコープか、冪等性キーはどれくらい保持するか、エラーはどう見えるか、UIはリトライ時にどうするか。これにより新しいエンドポイントが安全性を回避するのを防げます。

CRUD画面を素早くKoder.ai (koder.ai)で作る場合でも、これらの振る舞いをデフォルトテンプレートに組み込む価値があります：スキーマに一意制約、APIに冪等性対応のCreateエンドポイント、UIに明確な読み込み状態を含めることで、速度がデータの混乱を招かないようにできます。