idempotency-handling

冪等性の処理

目次

• 概要
• 使用する場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

操作の実行回数にかかわらず同じ結果が得られるように、冪等性を実装します。

使用する場面

• 決済処理
• リトライを伴う API エンドポイント
• Webhook とコールバック
• メッセージキューのコンシューマー
• 分散トランザクション
• 銀行振込
• 注文の作成
• メールの送信
• リソースの作成

クイックスタート

最小限の動作例：

import express from "express";
import Redis from "ioredis";
import crypto from "crypto";

interface IdempotentRequest {
  key: string;
  status: "processing" | "completed" | "failed";
  response?: any;
  error?: string;
  createdAt: number;
  completedAt?: number;
}

class IdempotencyService {
  private redis: Redis;
  private ttl = 86400; // 24 hours

  constructor(redisUrl: string) {
    this.redis = new Redis(redisUrl);
  }

  async getRequest(key: string): Promise<IdempotentRequest | null> {
    const data = await this.redis.get(`idempotency:${key}`);
    return data ? JSON.parse(data) : null;
  }
// ... (see reference guides for full implementation)

リファレンスガイド

詳細な実装は references/ ディレクトリにあります。

ガイド	内容
Express 冪等性ミドルウェア	Express 冪等性ミドルウェア
データベースベースの冪等性	データベースベースの冪等性
Stripe スタイルの冪等性	Stripe スタイルの冪等性
メッセージキューの冪等性	メッセージキューの冪等性

ベストプラクティス

✅ 推奨事項

• 更新処理では冪等性キーを必須にします
• リクエストとレスポンスを一緒に保存します
• 冪等性レコードに適切な TTL を設定します
• リクエスト本文が保存済みのリクエストと一致することを検証します
• 同時リクエストを適切に処理します
• 重複リクエストには同じレスポンスを返します
• 古い冪等性レコードをクリーンアップします
• アトミック性を確保するためにデータベース制約を使用します

❌ 禁止事項

• GET リクエストに冪等性を適用しないでください
• 冪等性データを永久に保存しないでください
• リクエスト本文の検証を省略しないでください
• 一意でない冪等性キーを使用しないでください
• 同じリクエストを同時に処理しないでください
• 重複リクエストへのレスポンスを変更しないでください