Java项目实现幂等性方案总结

幂等性(Idempotence)是分布式系统和API设计中一个重要的概念，指的是对同一个操作执行一次或多次，其产生的结果是相同的。在Java项目中实现幂等性可以避免重复操作带来的问题，如重复支付、重复下单等。

一、幂等性基础概念

1. 幂等性场景

用户重复点击提交按钮
消息队列重复消费
接口超时重试
分布式服务调用失败重试

2. 需要幂等的操作

创建操作（需防止重复创建）
更新操作（需防止重复更新）
删除操作（需防止重复删除）
支付/交易类操作

二、常见幂等性实现方案

1. 唯一索引/主键约束

适用场景：防止重复插入数据

// 数据库表添加唯一约束
ALTER TABLE orders ADD UNIQUE KEY (order_no);// Java代码
@Service
public class OrderService {@Transactionalpublic void createOrder(Order order) {try {orderDao.insert(order);} catch (DuplicateKeyException e) {// 捕获唯一键冲突异常log.warn("重复订单: {}", order.getOrderNo());throw new BusinessException("订单已存在");}}
}

2. 乐观锁

适用场景：更新操作幂等

// 数据库表添加version字段
ALTER TABLE products ADD COLUMN version INT DEFAULT 0;// Java代码
@Service
public class ProductService {@Transactionalpublic void updateStock(Long productId, int quantity) {Product product = productDao.selectById(productId);int affected = productDao.updateStock(productId, quantity, product.getVersion());if (affected == 0) {throw new OptimisticLockException("更新失败，请重试");}}
}// Mapper XML
<update id="updateStock">UPDATE products SET stock = stock - #{quantity}, version = version + 1 WHERE id = #{productId} AND version = #{version}
</update>

3. 分布式锁

适用场景：分布式环境下的幂等控制

@Service
public class PaymentService {@Autowiredprivate RedissonClient redissonClient;public void makePayment(String orderNo, BigDecimal amount) {String lockKey = "payment:" + orderNo;RLock lock = redissonClient.getLock(lockKey);try {// 尝试加锁，等待5秒，锁有效期30秒boolean locked = lock.tryLock(5, 30, TimeUnit.SECONDS);if (!locked) {throw new BusinessException("系统繁忙，请稍后再试");}// 检查是否已处理过if (paymentDao.existsByOrderNo(orderNo)) {return; // 已处理，直接返回}// 执行业务逻辑processPayment(orderNo, amount);} catch (InterruptedException e) {Thread.currentThread().interrupt();throw new BusinessException("支付处理被中断");} finally {lock.unlock();}}
}

4. Token机制

适用场景：防止表单重复提交

@RestController
public class OrderController {@Autowiredprivate RedisTemplate<String, String> redisTemplate;@GetMapping("/order/token")public String generateToken() {String token = UUID.randomUUID().toString();redisTemplate.opsForValue().set("order:token:" + token, "1", 5, TimeUnit.MINUTES);return token;}@PostMapping("/order/create")public ResponseEntity<?> createOrder(@RequestParam String token, Order order) {String key = "order:token:" + token;Boolean deleted = redisTemplate.delete(key);if (Boolean.FALSE.equals(deleted)) {return ResponseEntity.badRequest().body("无效或已使用的token");}orderService.createOrder(order);return ResponseEntity.ok().build();}
}

5. 状态机

适用场景：有状态流转的业务

@Service
public class OrderService {@Transactionalpublic void cancelOrder(Long orderId) {Order order = orderDao.findById(orderId).orElseThrow(() -> new BusinessException("订单不存在"));if (order.getStatus() == OrderStatus.CANCELLED) {return; // 已经是取消状态，直接返回}if (order.getStatus() != OrderStatus.PAID) {throw new BusinessException("当前状态不能取消订单");}order.setStatus(OrderStatus.CANCELLED);orderDao.update(order);}
}

6. 消息队列幂等

适用场景：消息队列消费幂等

@Component
@RabbitListener(queues = "order.queue")
public class OrderMessageListener {@Autowiredprivate OrderDao orderDao;@RabbitHandlerpublic void process(@Payload OrderMessage message, @Headers Map<String, Object> headers) {String messageId = (String) headers.get("message_id");// 检查是否已处理过该消息if (orderDao.existsByMessageId(messageId)) {return;}// 处理订单Order order = convertToOrder(message);order.setMessageId(messageId);orderDao.insert(order);}
}

三、分布式系统幂等方案

1. 全局唯一ID + 去重表

@Service
public class PaymentService {@Autowiredprivate DistributedIdGenerator idGenerator;@Transactionalpublic void processPayment(PaymentRequest request) {// 生成唯一业务IDString businessId = "pay_" + idGenerator.nextId();// 检查是否已处理if (paymentDao.existsByBusinessId(businessId)) {return;}// 记录处理标记paymentDao.insertProcessingRecord(businessId);try {// 执行业务逻辑doPayment(request);// 更新状态为成功paymentDao.updateStatus(businessId, "SUCCESS");} catch (Exception e) {// 更新状态为失败paymentDao.updateStatus(businessId, "FAILED");throw e;}}
}

2. 基于Redis的幂等控制

@Service
public class IdempotentService {@Autowiredprivate StringRedisTemplate redisTemplate;public boolean checkAndSet(String idempotentKey, long expireSeconds) {// setIfAbsent = SETNX + EXPIREBoolean success = redisTemplate.opsForValue().setIfAbsent(idempotentKey, "1", expireSeconds, TimeUnit.SECONDS);return Boolean.TRUE.equals(success);}public void release(String idempotentKey) {redisTemplate.delete(idempotentKey);}
}// 使用示例
@RestController
public class ApiController {@Autowiredprivate IdempotentService idempotentService;@PostMapping("/api/do-something")public ResponseEntity<?> doSomething(@RequestHeader("X-Request-Id") String requestId) {if (!idempotentService.checkAndSet("idempotent:" + requestId, 3600)) {return ResponseEntity.status(HttpStatus.CONFLICT).body("请求正在处理或已处理完成");}try {// 执行业务逻辑return ResponseEntity.ok().build();} finally {idempotentService.release("idempotent:" + requestId);}}
}