幂等性处理指南：实现API、支付、消息队列的可靠操作 | 最佳实践与代码示例

idempotency-handling by aj-geddes/useful-ai-prompts

148 周安装量

162 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/aj-geddes/useful-ai-prompts --skill idempotency-handling

Node.js 分布式系统 API

🇨🇳中文介绍

幂等性处理

概述

实现幂等性以确保无论操作执行多少次，都能产生相同的结果。

使用场景

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

快速开始

最小工作示例：

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;
  }
// ... (完整实现请参阅参考指南)

参考指南

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

指南	内容
Express 幂等性中间件	Express 幂等性中间件
基于数据库的幂等性	基于数据库的幂等性
Stripe 风格幂等性	Stripe 风格幂等性
消息队列幂等性	消息队列幂等性

🇺🇸English

Idempotency Handling

Overview
When to Use
Quick Start
Reference Guides
Best Practices

Overview

Implement idempotency to ensure operations produce the same result regardless of how many times they're executed.

When to Use

Payment processing
API endpoints with retries
Webhooks and callbacks
Message queue consumers
Distributed transactions
Bank transfers
Order creation
Email sending
Resource creation

Quick Start

Minimal working example:

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)

Reference Guides

Detailed implementations in the references/ directory:

Guide	Contents
Express Idempotency Middleware	Express Idempotency Middleware
Database-Based Idempotency	Database-Based Idempotency
Stripe-Style Idempotency	Stripe-Style Idempotency
Message Queue Idempotency	Message Queue Idempotency

Best Practices

✅ DO

Require idempotency keys for mutations
Store request and response together
Set appropriate TTL for idempotency records
Validate request body matches stored request
Handle concurrent requests gracefully
Return same response for duplicate requests
Clean up old idempotency records
Use database constraints for atomicity

❌ DON'T

Apply idempotency to GET requests
Store idempotency data forever
Skip validation of request body
Use non-unique idempotency keys
Process same request concurrently
Change response for duplicate requests

Weekly Installs

106

Repository

aj-geddes/usefu…-prompts

GitHub Stars

116

First Seen

Jan 21, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

opencode90

gemini-cli88

codex86

claude-code85

cursor80

github-copilot73