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 请求应用幂等性
• 永久存储幂等数据
• 跳过请求正文验证
• 使用不唯一的幂等键
• 并发处理相同的请求
• 为重复请求更改响应