idempotency-handling

Idempotency Handling

用途

实现幂等（idempotency），确保操作无论执行多少次都产生相同结果。用于避免重试、回调重复触发或消息重复投递带来重复副作用。

何时使用

支付处理
带重试的 API 端点
Webhook 与回调
消息队列消费者
分布式事务
银行转账
订单创建
邮件发送
资源创建

快速开始

文档提供一个基于 Express、ioredis 与 Node crypto 的最小示例：定义了 IdempotentRequest 接口（key、status：processing/completed/failed、response、error、createdAt、completedAt），以及 IdempotencyService 类，使用 Redis 存储，TTL 为 86400 秒（24 小时），通过 getRequest(key) 读取 idempotency:${key} 的缓存记录并解析。完整实现见参考指南。

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 Idempotency Middleware
Database-Based Idempotency
Stripe-Style Idempotency
Message Queue Idempotency

最佳实践

应做（DO）：

对变更类操作要求幂等键
请求与响应一起存储
为幂等记录设置合适的 TTL
校验请求体与已存请求是否匹配
优雅处理并发请求
对重复请求返回相同响应
清理旧的幂等记录
使用数据库约束保证原子性

不应做（DON'T）：

对 GET 请求应用幂等
永久存储幂等数据
跳过请求体校验
使用非唯一的幂等键
并发处理同一请求
为重复请求改变响应

限制

资料仅给出上述接口、存储方式、TTL 与参考指南目录，未提供具体安装命令、完整代码实现细节、支持平台或版本要求；相关内容暂未提供。