エラーハンドリング設計ガイド retry・idempotency・fallbackの実践パターン

function isRetryable(statusCode: number): boolean {
  // 4xx は原則リトライ不可（クライアント側の問題）
  // ただし 429 (Too Many Requests) と 408 (Request Timeout) は例外
  if (statusCode === 429 || statusCode === 408) return true;
  if (statusCode >= 400 && statusCode < 500) return false;

  // 5xx は原則リトライ可能（サーバー側の一時的問題）
  // ただし 501 (Not Implemented) は永続的
  if (statusCode === 501) return false;
  if (statusCode >= 500) return true;

  return false;
}

function isNetworkRetryable(error: Error): boolean {
  // DNS 解決失敗は一時的な場合がある
  if (error.message.includes('ENOTFOUND')) return true;
  // 接続リセット・タイムアウトはリトライ可能
  if (error.message.includes('ECONNRESET')) return true;
  if (error.message.includes('ETIMEDOUT')) return true;
  // 接続拒否は一時的過負荷の可能性
  if (error.message.includes('ECONNREFUSED')) return true;
  return false;
}

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  options: {
    maxAttempts?: number;
    baseDelayMs?: number;
    maxDelayMs?: number;
  } = {}
): Promise<T> {
  const { maxAttempts = 3, baseDelayMs = 100, maxDelayMs = 30_000 } = options;

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (attempt === maxAttempts) throw error;
      if (!isRetryable(error)) throw error;

      const delay = Math.min(baseDelayMs * 2 ** (attempt - 1), maxDelayMs);
      await sleep(delay);
    }
  }
  throw new Error('unreachable');
}

function calcBackoffWithJitter(attempt: number, baseMs: number, maxMs: number): number {
  const exponential = baseMs * 2 ** attempt;
  const capped = Math.min(exponential, maxMs);
  // full jitter: 0 〜 cap の間でランダムに選択
  return Math.random() * capped;
}

import { randomUUID } from 'crypto';

async function createOrderIdempotent(
  orderData: OrderInput,
  idempotencyKey: string = randomUUID()
): Promise<Order> {
  const response = await fetch('/api/orders', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Idempotency-Key': idempotencyKey, // 冪等キーをヘッダに付与
    },
    body: JSON.stringify(orderData),
  });

  if (!response.ok) {
    if (response.status === 409) {
      // Conflict: 同じキーでの重複リクエスト → 前回の結果を返す
      return response.json();
    }
    throw new Error(`Order creation failed: ${response.status}`);
  }

  return response.json();
}

// PostgreSQL + Prisma の例
async function handleOrderCreate(idempotencyKey: string, data: OrderInput): Promise<Order> {
  // idempotency_key テーブルで重複チェック
  const existing = await prisma.idempotencyRecord.findUnique({
    where: { key: idempotencyKey },
  });

  if (existing) {
    // 既に処理済み → キャッシュした結果を返す
    return JSON.parse(existing.responseBody) as Order;
  }

  // 新規処理
  const order = await prisma.$transaction(async (tx) => {
    const newOrder = await tx.order.create({ data: mapToOrder(data) });
    // 冪等レコードを同一トランザクションで保存
    await tx.idempotencyRecord.create({
      data: {
        key: idempotencyKey,
        responseBody: JSON.stringify(newOrder),
        expiresAt: new Date(Date.now() + 24 * 60 * 60 * 1000), // 24時間保持
      },
    });
    return newOrder;
  });

  return order;
}

// 冪等な upsert（同じ external_id なら更新、なければ挿入）
await prisma.payment.upsert({
  where: { externalId: payment.externalId },
  update: { status: payment.status, updatedAt: new Date() },
  create: {
    externalId: payment.externalId,
    amount: payment.amount,
    status: payment.status,
  },
});

Closed（通常） → エラー率が閾値超過 → Open（遮断）
Open → 一定時間後 → Half-Open（試験）
Half-Open → 成功 → Closed
Half-Open → 失敗 → Open に戻る

type CircuitState = 'closed' | 'open' | 'half-open';

class CircuitBreaker {
  private state: CircuitState = 'closed';
  private failureCount = 0;
  private lastFailureTime: number | null = null;

  constructor(
    private readonly threshold: number = 5,       // 失敗回数の閾値
    private readonly recoveryTimeMs: number = 60_000 // 回復待機時間（1分）
  ) {}

  async call<T>(fn: () => Promise<T>): Promise<T> {
    if (this.state === 'open') {
      const elapsed = Date.now() - (this.lastFailureTime ?? 0);
      if (elapsed < this.recoveryTimeMs) {
        throw new Error('Circuit breaker is OPEN — request rejected');
      }
      this.state = 'half-open';
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  private onSuccess(): void {
    this.failureCount = 0;
    this.state = 'closed';
  }

  private onFailure(): void {
    this.failureCount++;
    this.lastFailureTime = Date.now();
    if (this.failureCount >= this.threshold) {
      this.state = 'open';
    }
  }
}

async function getRecommendations(userId: string): Promise<Recommendation[]> {
  try {
    // プライマリ: リアルタイムレコメンドサービス
    return await recommendationBreaker.call(() =>
      recommendationApi.get(userId)
    );
  } catch {
    // fallback 1: Redis キャッシュから古い結果を返す
    const cached = await redis.get(`recommendations:${userId}`);
    if (cached) {
      return JSON.parse(cached);
    }

    // fallback 2: 人気記事の固定リストを返す（機能縮退）
    return POPULAR_ARTICLES_FALLBACK;
  }
}