決済のような API を、二重に送られても困らないように作るには、どうしますか

なぜ二重に届くのか

送った側は、応答が返ってこないとき、「サーバーに届かなかった」のか「届いて処理されたが、応答だけが失われた」のかを見分けられません。だから安全のために送り直します。後者だったとき、サーバーに何の備えも無いと、支払いが 2 回行われます。

HTTP では、GET や PUT や DELETE は何回送っても結果が同じになる (冪等) と決められていますが、POST はそう決められていません。決済や注文のような「新しく作る」操作は POST が多いので、自分で冪等にする仕組みが要ります。

冪等キーの流れ

送る側は、ボタンを押したときなど、1 回の操作の初めに一意の値 (UUID など) を作り、リクエストヘッダーに付けます。Idempotency-Key という名前のヘッダーで送る形が広く使われていて、標準にするための草案も出ています。

受ける側の動きを、メモリの Map で小さく書くと次の通りです。

const saved = new Map();
let balance = 1000;

function pay(key, amount) {
  if (saved.has(key)) {
    return saved.get(key);
  }
  balance -= amount;
  const result = "支払い済み 残高 " + balance;
  saved.set(key, result);
  return result;
}

console.log(pay("order-1-a", 300));
console.log(pay("order-1-a", 300));
console.log(pay("order-2-b", 200));

支払い済み 残高 700
支払い済み 残高 700
支払い済み 残高 500

2 回目の呼び出しは同じ鍵なので、残高を引かずに 1 回目と同じ結果を返します。実際のサービスでは Map ではなく DB に保存します。サーバーが何台あっても、再起動しても、同じ鍵を見つけられるようにするためです。

抜けやすい 3 つの場面

• 処理の途中に同じ鍵が来る 1 回目がまだ終わっていないのに 2 回目が来ることがあります。鍵の列に一意の制約を付け、先に「処理中」として鍵を入れた側だけが進み、後から来た側には「処理中です」と返して、少し待ってから送り直してもらいます
• 同じ鍵で違う中身が来る送る側の不具合で、金額の違うリクエストに同じ鍵が付くことがあります。鍵と一緒にリクエストの中身のハッシュも保存し、中身が違えばエラーで返します。黙って前の結果を返すと、利用者は別の支払いをしたつもりになります
• 鍵の保存と本体の処理がずれる支払いの記録だけ書けて鍵が書けないと、再試行でまた支払いが走ります。鍵と結果の保存は、本体の書き込みと同じトランザクションで行います

外の決済サービスを呼ぶときは、その先にも同じ考えで鍵を渡します。自分のサーバーだけ冪等でも、外への呼び出しが 2 回走れば、お金は 2 回動きます。

トレードオフ

鍵を保存する表が増え、処理中の扱いや中身の照らし合わせのぶん、作りは複雑になります。鍵はいつまでも持たず、再試行が起こりうる期間だけ持って消します。その期間を過ぎた再試行は、新しい操作として扱われることを、送る側と取り決めておきます。

注文番号のように、もともと一意に決まる値があるなら、その列に一意の制約を付けるだけで十分なこともあります。冪等キーは、そうした自然な一意の値が無い操作で使います。

話す例は架空の例で構いません。「購入のボタンを二度押しされても注文が 1 つだけできるように、鍵の列に一意の制約を付けた」のように、どこで止めたかを 1 つ話せると伝わります。