冪等性の設計 - 安全なAPI・処理を実現する

冪等性とは

冪等性（べきとうせい、Idempotency）は、同じ操作を何度実行しても結果が変わらない性質です。分散システムやAPI設計において、信頼性を確保するための重要な概念です。

数学的定義: f(f(x)) = f(x) 同じ関数を複数回適用しても、1回適用したときと同じ結果になる

なぜ冪等性が重要か

ネットワーク通信では、以下のような問題が発生します。

sequenceDiagram
 participant C as クライアント
 participant S as サーバー

 C->>S: リクエスト
 Note over C,S: タイムアウト<br/>(レスポンスが届かなかった)
 Note over C: リクエストは処理された？<br/>リトライすべき？

冪等な操作であれば、安全にリトライできます。

HTTPメソッドと冪等性

PUT vs POST

冪等性キー（Idempotency Key）

POSTリクエストでも冪等性を実現するための手法です。

POST /payments
Idempotency-Key: pay_abc123xyz
Content-Type: application/json

{
 "amount": 5000,
 "currency": "JPY"
}

実装例

async function processPayment(req, res) {
 const idempotencyKey = req.headers['idempotency-key'];

 if (!idempotencyKey) {
 return res.status(400).json({ error: 'Idempotency-Key required' });
 }

 // 既存の処理結果を確認
 const existing = await redis.get(`idempotency:${idempotencyKey}`);
 if (existing) {
 return res.status(200).json(JSON.parse(existing));
 }

 // ロックを取得（同時実行を防ぐ）
 const lock = await acquireLock(idempotencyKey);
 if (!lock) {
 return res.status(409).json({ error: 'Request in progress' });
 }

 try {
 // 処理を実行
 const result = await executePayment(req.body);

 // 結果を保存（24時間有効）
 await redis.setex(
 `idempotency:${idempotencyKey}`,
 86400,
 JSON.stringify(result)
 );

 return res.status(201).json(result);
 } finally {
 await releaseLock(idempotencyKey);
 }
}

冪等性の実装パターン

1. 一意識別子による重複チェック

async function createOrder(orderData, requestId) {
 // 既存チェック
 const existing = await db.orders.findByRequestId(requestId);
 if (existing) {
 return existing; // 同じ結果を返す
 }

 // 新規作成
 const order = await db.orders.create({
 ...orderData,
 requestId // 一意識別子を保存
 });

 return order;
}

2. 状態チェック

async function cancelOrder(orderId) {
 const order = await db.orders.findById(orderId);

 // 既にキャンセル済みなら何もしない
 if (order.status === 'cancelled') {
 return order; // 冪等
 }

 // キャンセル可能な状態か確認
 if (order.status === 'shipped') {
 throw new Error('Cannot cancel shipped order');
 }

 return await db.orders.update(orderId, { status: 'cancelled' });
}

3. 楽観的ロック

async function updateInventory(productId, quantity, version) {
 const result = await db.query(
 `UPDATE inventory
 SET quantity = quantity - $1, version = version + 1
 WHERE product_id = $2 AND version = $3`,
 [quantity, productId, version]
 );

 if (result.rowCount === 0) {
 throw new Error('Concurrent modification detected');
 }
}

冪等でない操作を冪等にする

インクリメント操作

// 冪等でない
UPDATE balance SET amount = amount + 100 WHERE user_id = 123

// 冪等にする（絶対値で設定）
UPDATE balance SET amount = 5100 WHERE user_id = 123

// または、トランザクションIDで管理
INSERT INTO transactions (id, user_id, amount)
VALUES ('tx_abc', 123, 100)
ON CONFLICT (id) DO NOTHING;

UPDATE balance
SET amount = (SELECT SUM(amount) FROM transactions WHERE user_id = 123)
WHERE user_id = 123;

メール送信

async function sendWelcomeEmail(userId, requestId) {
 // 送信済みチェック
 const sent = await db.emailLogs.findOne({
 userId,
 type: 'welcome',
 requestId
 });

 if (sent) {
 return { status: 'already_sent' };
 }

 // 送信
 await emailService.send(/* ... */);

 // ログ記録
 await db.emailLogs.create({
 userId,
 type: 'welcome',
 requestId,
 sentAt: new Date()
 });

 return { status: 'sent' };
}

リトライ戦略

指数バックオフ

async function retryWithBackoff(fn, maxRetries = 3) {
 for (let i = 0; i < maxRetries; i++) {
 try {
 return await fn();
 } catch (error) {
 if (i === maxRetries - 1) throw error;

 // 指数バックオフ + ジッター
 const delay = Math.pow(2, i) * 1000 + Math.random() * 1000;
 await sleep(delay);
 }
 }
}

リトライすべきエラー

まとめ

冪等性は、分散システムやAPIの信頼性を確保するための重要な設計原則です。冪等性キーの導入、状態チェック、楽観的ロックなどのパターンを活用し、安全にリトライできる操作を設計しましょう。

参考リソース

• RFC 9110 - HTTP Semantics: Idempotent Methods
• IETF Draft - The Idempotency-Key HTTP Header Field
• Stripe - Idempotent Requests
• AWS - Making retries safe with idempotent APIs

×

PR

×

PR