---
description: 分布式幂等注解 @Idempotent 使用规范，基于Redis实现微服务防重复提交
globs: ["**/controller/**/*.java"]
alwaysApply: false
---
# 冲突优先级声明
Controller三层规范、Java编码规范优先级高于本文件。

# 分布式幂等防重复提交规范
## 一、注解基础说明
使用项目自定义 `@Idempotent` 注解，基于Redis实现分布式幂等控制，防止用户快速重复点击、网络重试造成重复新增、重复扣款、重复生成数据问题，适配微服务多实例集群环境。

## 二、注解属性配置规范
1. expireTime：幂等key过期时间，单位秒；
    - 新增、编辑表单：默认5秒；
    - 提交复杂业务、导出任务：设置30~60秒；
2. message：重复提交时返回的提示文案，示例："请勿重复提交表单"；
3. keyType：幂等key生成策略：
    - TOKEN：基于用户登录Token + 接口路径（表单页面通用）；
    - PARAM：基于指定请求参数（唯一编码、订单号等唯一性字段）。

## 三、强制添加幂等注解的接口
1. POST /create 新增业务数据接口；
2. PUT /update 修改核心业务数据接口；
3. 状态变更、数据生成、批量处理接口；
4. APP端表单提交、订单创建类接口；

## 四、使用约束
1. 注解仅添加在Controller接口方法上；
2. 所有面向用户提交、可重复点击的写接口，必须配置@Idempotent；
3. 读接口（分页查询、详情查询、导出）无需添加幂等注解；
4. Redis统一使用国产化分布式缓存，不依赖境外Redis商业版本；
5. 幂等key自动绑定当前登录用户，用户之间互不干扰。

## 五、禁止事项
❌ 新增、编辑、业务提交接口不添加幂等注解，存在重复提交风险；
❌ 自定义本地内存锁替代分布式Redis幂等，集群多实例失效；
❌ 幂等提示文案使用技术术语，必须使用通俗易懂业务提示；
❌ 导出、单纯查询接口滥用@Idempotent注解，浪费Redis资源。
