# distributed-idempotency

**Repository Path**: xiaowugui521/distributed-idempotency

## Basic Information

- **Project Name**: distributed-idempotency
- **Description**: Distributed Idempotency Component for Java - Spring Boot Starter
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-04-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 分布式幂等组件

一个轻量级的分布式幂等解决方案，支持 Redis 和本地内存两种存储后端。

## 特性

- **零侵入**：通过注解方式使用，业务代码无需改造
- **多种存储后端**：Redis（分布式）/ LocalStorage（单机）
- **自动降级**：Redis 不可用时自动降级到本地存储
- **结果缓存**：重复请求可返回缓存结果
- **多种等待策略**：FAIL_FAST（快速失败）/ WAIT（等待结果）
- **SpEL 表达式**：支持动态生成幂等键

## 快速开始

### 1. 添加依赖

```xml
<dependency>
    <groupId>com.xiaogui</groupId>
    <artifactId>distributed-idempotency</artifactId>
    <version>1.0.0</version>
</dependency>
```

### 2. 启用组件

```java
@SpringBootApplication
@EnableConfigurationProperties(IdempotencyConfig.class)
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

### 3. 在需要幂等的方法上添加注解

```java
@Service
public class OrderService {
    
    @Autowired
    private IdempotencyManager idempotencyManager;
    
    @Idempotent(
        key = "'order:create:' + #orderId",
        expireTime = 30,
        unit = TimeUnit.SECONDS,
        desc = "订单创建幂等"
    )
    public Order createOrder(String orderId, CreateOrderDTO dto) {
        // 业务逻辑，只会被执行一次
        return orderRepository.save(dto.toOrder());
    }
}
```

## 配置项

```yaml
idempotency:
  enabled: true                    # 是否启用，默认 true
  storage: redis                   # 存储类型：redis / local
  default-expire-time: 30          # 默认过期时间（秒）
  default-wait-timeout: 3          # 默认等待超时（秒）
```

## 注解说明

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| key | String | - | **必填**，幂等键，支持 SpEL 表达式 |
| expireTime | long | 30 | 过期时间 |
| unit | TimeUnit | SECONDS | 时间单位 |
| desc | String | "" | 描述（用于日志） |
| deleteAfter | boolean | false | 是否在响应后删除锁 |
| waitStrategy | WaitStrategy | FAIL_FAST | 等待策略 |
| waitTimeout | long | 3 | 等待超时（秒） |

## 使用示例

### 订单创建

```java
@Idempotent(
    key = "'order:create:' + #orderId",
    expireTime = 30,
    unit = TimeUnit.SECONDS,
    desc = "订单创建幂等"
)
public Order createOrder(String orderId, CreateOrderRequest request) {
    // 业务逻辑
    return orderRepository.save(convert(request));
}
```

### 支付回调

```java
@Idempotent(
    key = "'payment:callback:' + #transactionId",
    expireTime = 3600,
    unit = TimeUnit.SECONDS,
    desc = "支付回调幂等"
)
public PaymentResult handleCallback(String transactionId, PaymentDTO payment) {
    // 处理支付回调
    return paymentService.process(payment);
}
```

### 等待策略

```java
// FAIL_FAST：检测到重复直接抛异常
@Idempotent(key = "'order:' + #orderId", waitStrategy = FAIL_FAST)
public void submitOrder(String orderId) { }

// WAIT：等待直到获取结果或超时
@Idempotent(
    key = "'order:' + #orderId", 
    waitStrategy = WAIT,
    waitTimeout = 5
)
public Result<Order> submitOrder(String orderId) {
    // 返回缓存结果
}
```

### 手动模式

```java
@Service
public class OrderService {
    
    @Autowired
    private IdempotencyManager idempotencyManager;
    
    public void manualIdempotent(String orderId) {
        String key = "order:manual:" + orderId;
        
        // 手动检查
        if (!idempotencyManager.tryAcquireSimple(key, 60, TimeUnit.SECONDS)) {
            throw new IdempotentException("正在处理中，请勿重复提交");
        }
        
        try {
            // 业务逻辑
            doProcess(orderId);
        } finally {
            idempotencyManager.releaseSimple(key);
        }
    }
}
```

## 架构设计

```
┌─────────────────────────────────────────────────────────────┐
│                     @Idempotent 注解                        │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                   IdempotencyInterceptor                    │
│                   (AOP 拦截器)                              │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    IdempotencyManager                       │
│                    (核心管理器)                             │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│  RedisStorage   │ │  LocalStorage   │ │  其他存储...    │
│  (分布式环境)    │ │  (单机/测试)    │ │                │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```

## 工作原理

1. **首次请求**：SETNX 获取锁 → 执行业务逻辑 → 存储结果 → 返回
2. **重复请求**：SETNX 返回 false → 检测到重复 → 返回缓存结果或抛异常

## License

MIT License