0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Node.jsでIdempotency-Keyを実装する:二重送信に強いAPI設計を面接で説明する

0
Posted at

元記事: https://www.aceround.app/blog/backend-developer-interview-ai/ をもとに、REST API 面接でよく聞かれる「べき等性キー」を実装記事として再構成しました。この記事自体は Node.js の API 設計に絞っています。

Idempotency-Key API State Machine

この記事で作るもの

決済、注文作成、ジョブ投入のような POST API では、クライアントがタイムアウト後に同じリクエストを再送することがあります。このときサーバー側が何も考えずに再実行すると、注文や課金が二重に作られます。

Idempotency-Key は、この問題を「同じキー + 同じリクエスト本文なら同じ結果を返す」という契約に落とし込む設計です。面接で説明するときの要点は、単にキーを保存することではありません。

  • リクエスト本文の指紋を保存する
  • 処理中の重複リクエストを同じ結果に合流させる
  • 完了済みなら保存したレスポンスを返す
  • 同じキーで別の本文が来たら 409 Conflict にする
  • TTL を設けてストアを無限に増やさない

以下は外部依存なしで動く Node.js の最小実装です。本番では Map の部分を Redis や SQL に置き換えます。

状態遷移

まず、保存するレコードを状態機械として考えます。

状態 意味 次の挙動
なし 初回リクエスト processing を作って処理を始める
processing 先行リクエストがまだ完了していない 同じ本文なら先行 Promise を待つ
completed 処理済み 保存済みレスポンスを返す
conflict 同じ key だが本文が違う 409 Conflict を返す

ここで重要なのは、processing を先に保存してから実処理に入ることです。そうしないと、同時に飛んできた2本のリクエストが両方とも「初回」と判断してしまいます。

実装

idempotency-demo.mjs として保存し、node idempotency-demo.mjs で実行できます。

import { createHash } from 'node:crypto';

const store = new Map();
const ttlMs = 60_000;

function stableJson(value) {
  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
  if (value && typeof value === 'object') {
    return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
  }
  return JSON.stringify(value);
}

function fingerprint({ method, path, body }) {
  return createHash('sha256')
    .update(`${method.toUpperCase()} ${path}\n${stableJson(body)}`)
    .digest('hex');
}

function replay(response) {
  return {
    ...response,
    headers: { ...response.headers, 'Idempotent-Replayed': 'true' },
  };
}

async function withIdempotency(request, handler) {
  if (!request.key) {
    return { status: 400, body: { error: 'Idempotency-Key is required' } };
  }

  const requestHash = fingerprint(request);
  const now = Date.now();
  const existing = store.get(request.key);

  if (existing && existing.expiresAt <= now) store.delete(request.key);
  const record = store.get(request.key);

  if (record) {
    if (record.requestHash !== requestHash) {
      return { status: 409, body: { error: 'idempotency_key_conflict' } };
    }
    if (record.status === 'completed') return replay(record.response);
    return replay(await record.promise);
  }

  const promise = handler();
  store.set(request.key, {
    status: 'processing',
    requestHash,
    promise,
    expiresAt: now + ttlMs,
  });

  try {
    const response = await promise;
    store.set(request.key, {
      status: 'completed',
      requestHash,
      response,
      expiresAt: Date.now() + ttlMs,
    });
    return response;
  } catch (error) {
    store.delete(request.key);
    throw error;
  }
}

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
let writes = 0;

async function createOrder(body) {
  await delay(80);
  writes += 1;
  return { status: 201, body: { orderId: `ord_${writes}`, ...body } };
}

const request = {
  key: 'checkout-20260707-001',
  method: 'POST',
  path: '/orders',
  body: { sku: 'book', quantity: 1 },
};

const [first, duplicated] = await Promise.all([
  withIdempotency(request, () => createOrder(request.body)),
  withIdempotency(request, () => createOrder(request.body)),
]);

const replayed = await withIdempotency(request, () => createOrder(request.body));
const conflict = await withIdempotency(
  { ...request, body: { sku: 'book', quantity: 2 } },
  () => createOrder({ sku: 'book', quantity: 2 }),
);

console.log(JSON.stringify({ first, duplicated, replayed, conflict, writes }, null, 2));

実行すると、writes が 1 のままになります。並行して2回呼んでも、後続の再送をしても、注文作成そのものは一度しか走っていません。

{
  "first": { "status": 201, "body": { "orderId": "ord_1", "sku": "book", "quantity": 1 } },
  "duplicated": { "status": 201, "body": { "orderId": "ord_1", "sku": "book", "quantity": 1 }, "headers": { "Idempotent-Replayed": "true" } },
  "replayed": { "status": 201, "body": { "orderId": "ord_1", "sku": "book", "quantity": 1 }, "headers": { "Idempotent-Replayed": "true" } },
  "conflict": { "status": 409, "body": { "error": "idempotency_key_conflict" } },
  "writes": 1
}

実装上のポイント

1. key だけではなく本文の指紋を見る

Idempotency-Key はクライアントが生成する値なので、同じキーで別の操作が送られる可能性があります。そのため method + path + body をハッシュ化し、保存済みの指紋と比較します。

本文が違うのに保存済みレスポンスを返すと、クライアントは「数量2で注文したのに数量1の結果が返った」ような壊れ方をします。ここは明確に 409 Conflict にした方がデバッグしやすいです。

2. processing を保存してから handler を呼ぶ

面接でよく突っ込まれるのはここです。

悪い実装は、処理が終わってから key を保存します。その場合、同時到着したリクエストはどちらも保存済み key を見つけられず、二重実行になります。

良い実装は、先に processing レコードを作ります。同じ key と同じ指紋のリクエストが来たら、先行処理の Promise を待って同じレスポンスを返します。

3. 失敗時に保存するか消すかを決める

上のコードでは handler が例外を投げた場合、レコードを消しています。これは一時的な 500 エラーやネットワーク障害なら再試行してほしいからです。

ただし、業務によっては失敗レスポンスも保存すべきです。例えば「カード拒否」のような確定的な失敗は、同じリクエストで再試行しても成功しません。この場合は failed 状態を保存し、同じエラーを返す設計もあります。

4. 本番では atomic な store が必要

このサンプルは単一プロセスなので Map で十分ですが、複数 Node.js インスタンスでは壊れます。本番で必要なのは次のどちらかです。

  • Redis: SET key value NX PX <ttl> で processing を一度だけ作る
  • SQL: idempotency_key に unique index を張り、insert 競合を読み取りに変える

どちらでも、初回判定と processing 作成を一つの atomic operation にすることが本質です。

面接での説明テンプレート

この設計を口頭で説明するなら、次の順番が通りやすいです。

  1. POST /orders はネットワークリトライで二重実行される可能性がある
  2. クライアントに Idempotency-Key を送らせる
  3. サーバーは key、リクエスト指紋、状態、レスポンス、TTL を保存する
  4. 初回は processing を atomic に作って処理する
  5. 同じ key + 同じ本文は処理中なら待ち、完了済みならキャッシュ済みレスポンスを返す
  6. 同じ key + 違う本文は 409 Conflict
  7. 本番では Redis または SQL unique index で分散環境に対応する

これで「二重送信を防ぐ」だけでなく、「並行リクエスト」「本文差分」「TTL」「複数インスタンス」という面接官のフォローアップにも対応できます。

まとめ

Idempotency-Key は小さなヘッダーに見えますが、実際には API の信頼性設計です。実装で差がつくのは、キーの保存そのものではなく、リクエスト指紋、processing 状態、atomic な初回作成、TTL、失敗時ポリシーを一貫した状態機械として扱えるかどうかです。

この粒度で説明できると、単なる REST API の知識確認ではなく、システム設計として会話できます。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?