分布式幂等（forge-starter-idempotent）

工程位置：forge-server/forge-framework/forge-starter-parent/forge-starter-idempotent。Maven artifactId 是 forge-starter-idempotent。src/main/java 里有 29 个 Java 文件。

引入

<dependency>
    <groupId>com.mdframe.forge</groupId>
    <artifactId>forge-starter-idempotent</artifactId>
</dependency>

自动装配

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports 登记了：

• com.mdframe.forge.starter.idempotent.config.IdempotentAutoConfiguration

配置属性

四个 @ConfigurationProperties 类都没有字段 javadoc。下表只写字段名和类内默认值，不编造注释。常量默认值来自 IdempotentConstant：DEFAULT_PREFIX = "idempotent:"，DEFAULT_EXPIRE = 600，DEFAULT_MESSAGE = "请勿重复提交"，CACHE_EXPIRE_DEFAULT = 3600。

forge.idempotent.token（com.mdframe.forge.starter.idempotent.properties.TokenProperties）

字段	类型	类内默认值	说明
enabled	boolean	true	源码无字段注释。
expire	int	300	源码无字段注释。Token 过期秒数，与 /api/idempotent/token/generate 返回的 expireSeconds 同源。
header	String	"X-Idempotent-Token"	源码无字段注释。请求头名，TokenRequiredStrategyHandler 从该头取 Token。

forge.idempotent（com.mdframe.forge.starter.idempotent.properties.IdempotentProperties）

字段	类型	类内默认值	说明
enabled	boolean	true	源码无字段注释。
prefix	String	"idempotent:"	源码无字段注释。与 IdempotentConstant.DEFAULT_PREFIX 相同。
expire	int	600	源码无字段注释。与 IdempotentConstant.DEFAULT_EXPIRE 相同。
message	String	"请勿重复提交"	源码无字段注释。与 IdempotentConstant.DEFAULT_MESSAGE 相同。
cache	CacheProperties	new CacheProperties()	嵌套 forge.idempotent.cache。
token	TokenProperties	new TokenProperties()	嵌套 forge.idempotent.token。
lock	LockProperties	new LockProperties()	嵌套 forge.idempotent.lock。

forge.idempotent.cache（com.mdframe.forge.starter.idempotent.properties.CacheProperties）

字段	类型	类内默认值	说明
enabled	boolean	true	源码无字段注释。
expire	int	3600	源码无字段注释。与 IdempotentConstant.CACHE_EXPIRE_DEFAULT 相同。
maxSize	int	10000	源码无字段注释。

forge.idempotent.lock（com.mdframe.forge.starter.idempotent.properties.LockProperties）

字段	类型	类内默认值	说明
enabled	boolean	true	源码无字段注释。
waitTime	long	3000	源码无字段注释。RedissonLockManager.tryLock 的等待毫秒。
leaseTime	long	5000	源码无字段注释。RedissonLockManager.tryLock 的租约毫秒。

类内默认值不是官方启动配置。各服务 application.yml 可以覆盖。

注解

@Idempotent

com.mdframe.forge.starter.idempotent.annotation.Idempotent，可标在方法或类上。

成员	类型	默认值	说明
prefix	String	IdempotentConstant.DEFAULT_PREFIX	幂等键前缀，用来区分业务场景，避免键冲突。默认 "idempotent:"。
expire	int	IdempotentConstant.DEFAULT_EXPIRE	幂等键过期秒数。过期后可再次提交。默认 600。
key	String	""	幂等键表达式。支持 SpEL，可引用方法参数。空则走默认键生成。
message	String	IdempotentConstant.DEFAULT_MESSAGE	触发幂等拦截时返回给客户端的提示。默认 "请勿重复提交"。
deleteKeyAfterSuccess	boolean	false	成功后是否删除幂等键。适合支付、转账这类一次性操作。
strategy	IdempotentStrategy	IdempotentStrategy.RETURN_CACHE	重复请求怎么处理，见下表。
cacheExpire	int	IdempotentConstant.CACHE_EXPIRE_DEFAULT	结果缓存过期秒数。只在 strategy=RETURN_CACHE 且 cacheResult=true 时生效。默认 3600。
cacheResult	boolean	true	是否缓存执行结果。true 重复请求返回缓存；false 只防重不缓存。仅 RETURN_CACHE 生效。
enableMetrics	boolean	true	是否记录拦截次数、耗时等监控指标。

源码示例：

@Idempotent(key = "'order:' + #orderId")
public Order createOrder(Long orderId) { ... }

@Idempotent(key = "'payment:' + #paymentId", strategy = IdempotentStrategy.STRICT)
public PaymentResult pay(PaymentRequest request) { ... }

@Idempotent(key = "'transfer:' + #requestId", strategy = IdempotentStrategy.TOKEN_REQUIRED)
public TransferResult transfer(TransferRequest request) { ... }

策略枚举

com.mdframe.forge.starter.idempotent.enums.IdempotentStrategy

常量	code	说明
STRICT	strict	同一幂等键的重复请求直接抛异常，不返回结果。
RETURN_CACHE	return_cache	返回上次执行的缓存结果。需要 cacheResult=true。fromCode 找不到时也回落到这个值。
TOKEN_REQUIRED	token_required	请求必须带有效幂等 Token。Token 由服务端生成再下发给客户端。

Token 接口

IdempotentTokenController 映射在 /api/idempotent/token。

方法	路径	参数	返回
POST	/api/idempotent/token/generate	prefix（可选）	RespInfo<TokenInfoDTO>
POST	/api/idempotent/token/batch-generate	count（必填，1–100），prefix（可选）	RespInfo<List<TokenInfoDTO>>。count 越界返回 "count参数必须在1-100之间"。
POST	/api/idempotent/token/validate	token（必填），prefix（可选）	RespInfo<Boolean>

TokenInfoDTO 字段：token、expireSeconds、createTime。源码无字段注释。

源码类型清单

下面只列 forge-starter-idempotent 自己的公开类型。

接口

• com.mdframe.forge.starter.idempotent.constant.IdempotentConstant
• com.mdframe.forge.starter.idempotent.generator.IdempotentKeyGenerator
• com.mdframe.forge.starter.idempotent.lock.LockManager
• com.mdframe.forge.starter.idempotent.service.IdempotentStorageService
• com.mdframe.forge.starter.idempotent.service.ResultCacheService
• com.mdframe.forge.starter.idempotent.service.TokenService
• com.mdframe.forge.starter.idempotent.strategy.IdempotentStrategyHandler

枚举

• IdempotentStrategy

类

• CacheProperties
• DefaultIdempotentKeyGenerator
• IdempotentAspect
• IdempotentAutoConfiguration
• IdempotentException
• IdempotentProperties
• IdempotentResult
• IdempotentTokenController
• LockProperties
• RedisIdempotentStorageService
• RedisResultCacheService
• RedisTokenService
• RedissonLockManager
• ReturnCacheStrategyHandler
• SpelUtil
• StrictStrategyHandler
• TokenInfoDTO
• TokenInvalidException
• TokenProperties
• TokenRequiredStrategyHandler

相关文档

• 后端模块总览
• 缓存