Skip to content

starter-protection ​

1. 职责 ​

把「接口防刷」的四件套做成注解:@Idempotent 幂等(同一请求在窗口内只放行一次)、@RateLimiter 限流(按 key 计数)、@Lock4j 分布式锁(锁失败抛业务异常)、@ApiSignature 加签(时间戳 + nonce + sha256,防篡改与重放)。

四个能力共用 Redis:幂等与签名用 StringRedisTemplate,限流与锁用 Redisson 客户端。它们都是方法级 AOP,不改业务代码。

它不解决:网关级限流、IP 黑名单(网关/运维)、JWT 令牌校验(starter-security)、应用层幂等的业务唯一键设计。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-protection/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
PmforgeIdempotentConfiguration幂等切面 + 3 个 key 解析器 + Redis DAOidempotent/config/PmforgeIdempotentConfiguration.java
IdempotentAspectsetIfAbsent 失败 → REPEATED_REQUESTS;异常时按 deleteKeyWhenException 删 keyidempotent/core/aop/IdempotentAspect.java
IdempotentRedisDAOkey idempotent:%s,底层 setIfAbsent(key, "", timeout, unit)idempotent/core/redis/IdempotentRedisDAO.java
Default/User/ExpressionIdempotentKeyResolver默认 MD5(方法签名+参数);用户维度追加 userId+userType;表达式维度走 SpELidempotent/core/keyresolver/impl/
PmforgeRateLimiterConfiguration + RateLimiterAspect5 个 key 解析器(默认/用户/IP/节点/表达式)ratelimiter/config/、ratelimiter/core/aop/
RateLimiterRedisDAOkey rate_limiter:%s,Redisson RRateLimiter,超限抛 TOO_MANY_REQUESTSratelimiter/core/redis/RateLimiterRedisDAO.java
PmforgeLock4jConfiguration + DefaultLockFailureStrategy锁失败抛 GlobalErrorCodeConstants.LOCKED(423)lock4j/config/、lock4j/core/
Lock4jRedisKeyConstants锁 key 前缀 lock4j:%s(Redisson RLock)lock4j/core/Lock4jRedisKeyConstants.java
PmforgeApiSignatureAutoConfiguration + ApiSignatureAspect验签:时间戳窗口、nonce 去重、sha256 比对signature/config/、signature/core/aop/ApiSignatureAspect.java
ApiSignatureRedisDAOappSecret(HASH api_signature_app)与 nonce(api_signature_nonce:%s:%s)signature/core/redis/ApiSignatureRedisDAO.java

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeIdempotentConfiguration@AutoConfiguration(after = PmforgeRedisAutoConfiguration.class)IdempotentRedisDAO、IdempotentAspect、3 个 IdempotentKeyResolver
PmforgeLock4jConfiguration@ConditionalOnClass(name = "com.baomidou.lock.annotation.Lock4j");@AutoConfiguration(before = LockAutoConfiguration.class)DefaultLockFailureStrategy(锁失败转业务异常)
PmforgeRateLimiterConfiguration@AutoConfiguration(after = PmforgeRedisAutoConfiguration.class)RateLimiterRedisDAO(Redisson)、RateLimiterAspect、5 个 RateLimiterKeyResolver
PmforgeApiSignatureAutoConfiguration@AutoConfiguration(after = PmforgeRedisAutoConfiguration.class)ApiSignatureRedisDAO、ApiSignatureAspect

注解默认值:

注解属性默认值
@Idempotenttimeout=1、timeUnit=SECONDS、message="重复请求,请稍后重试"、keyResolver=DefaultIdempotentKeyResolver、deleteKeyWhenException=true
@RateLimitertime=1、timeUnit=SECONDS、count=100、message=""(空则用 TOO_MANY_REQUESTS 的提示)、keyResolver=DefaultRateLimiterKeyResolver
@ApiSignaturetimeout=60(秒)、message="签名不正确";appId/timestamp/nonce/sign 默认就是同名请求头

4. 配置项 ​

前缀键默认值说明
—无—本模块没有 @ConfigurationProperties
lock4jlock4j.*由 lock4j 依赖提供锁超时、获取超时等走第三方库自己的配置项

签名相关的「配置」是 Redis 里的数据,不是 yaml:

Redis key结构说明
api_signature_appHASH,field=appId,value=appSecret预加载、不过期;缺失时用 hutool Assert.notNull 直接抛 IllegalArgumentException
api_signature_nonce:%s:%sString(appId + nonce)TTL = timeout * 2 秒,用于防重放
idempotent:%sString(空值)TTL = 注解的 timeout/timeUnit
rate_limiter:%sRedisson RRateLimiter首次按 count + time 创建,之后按需 setRate
lock4j:%sRedisson RLock由 lock4j 库读写

5. 扩展点 ​

  • 自定义幂等 key:实现 IdempotentKeyResolver 并注册 Bean(自动配置注入的是 List<IdempotentKeyResolver>),注解上 keyResolver = MyResolver.class。
  • 自定义限流维度:实现 RateLimiterKeyResolver;内置 5 个已覆盖默认/用户/IP/单节点/SpEL。
  • 表达式维度:@Idempotent(keyArg = "#req.orderNo")、@RateLimiter(keyArg = "#userId"),走 SpEL,参数名依赖编译期 -parameters。
  • 换锁实现:lock4j 支持 Redisson/ZooKeeper 等,换实现只改依赖与 lock4j.* 配置。
  • 签名算法:写死在 ApiSignatureAspect(sha256Hex + TreeMap 排序),没有 SPI 扩展点;要换算法得改代码。

6. 常见坑 ​

  1. @Idempotent 的 timeout 不是「防重复执行」而是「执行窗口」:注解注释原话——方法执行时间超过 timeout 时,后续请求仍会进来。
  2. delKey 属性被刻意移除:package-info 说明「delKey=true 本质是分布式锁,应改用 Lock4j」;实现也弃用了 RMap,只用 Redis String。
  3. 签名失败的错误码不统一:appSecret 不存在时 ApiSignatureRedisDAO 用 hutool Assert.notNull 抛 IllegalArgumentException(最终 500),而其他签名问题抛 ServiceException("签名不正确")(400 段),排查时容易误判为服务端 bug。
  4. ApiSignatureRedisDAO 的 Javadoc 与代码 key 不一致:注释写 signature_nonce:%s,实际是 api_signature_nonce:%s:%s,手工清 nonce 时按注释找会找不到。
  5. nonce 长度必须 ≥ 10:不足直接判「签名不正确」,而不是提示 nonce 格式问题。
  6. 限流器的 count/time 改了不会立刻生效:RateLimiterRedisDAO 发现已有 limiter 且参数不同才 setRate,窗口内的旧速率会被重置,压测时会看到跳变。

7. 关联页面 ​