元記事: https://www.aceround.app/blog/backend-developer-interview-ai/ をもとに、REST API 面接でよく聞かれる「べき等性キー」を実装記事として再構成しました。この記事自体は Node.js の API 設計に絞っています。
この記事で作るもの
決済、注文作成、ジョブ投入のような 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 にすることが本質です。
面接での説明テンプレート
この設計を口頭で説明するなら、次の順番が通りやすいです。
-
POST /ordersはネットワークリトライで二重実行される可能性がある - クライアントに
Idempotency-Keyを送らせる - サーバーは key、リクエスト指紋、状態、レスポンス、TTL を保存する
- 初回は
processingを atomic に作って処理する - 同じ key + 同じ本文は処理中なら待ち、完了済みならキャッシュ済みレスポンスを返す
- 同じ key + 違う本文は
409 Conflict - 本番では Redis または SQL unique index で分散環境に対応する
これで「二重送信を防ぐ」だけでなく、「並行リクエスト」「本文差分」「TTL」「複数インスタンス」という面接官のフォローアップにも対応できます。
まとめ
Idempotency-Key は小さなヘッダーに見えますが、実際には API の信頼性設計です。実装で差がつくのは、キーの保存そのものではなく、リクエスト指紋、processing 状態、atomic な初回作成、TTL、失敗時ポリシーを一貫した状態機械として扱えるかどうかです。
この粒度で説明できると、単なる REST API の知識確認ではなく、システム設計として会話できます。
