アイデンポテンシー処理

目次

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

概要

アイデンポテンシーを実装して、オペレーションが実行回数に関わらず同じ結果を生み出すようにします。

使用場面

• 決済処理
• リトライ機能を備えた 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 リクエストにアイデンポテンシーを適用する
• アイデンポテンシーデータを永遠に保存する
• リクエストボディの検証をスキップする
• 一意でないアイデンポテンシーキーを使用する
• 同じリクエストを並行処理する
• 重複したリクエストに対してレスポンスを変更する