主题
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 DAO | idempotent/config/PmforgeIdempotentConfiguration.java |
IdempotentAspect | setIfAbsent 失败 → REPEATED_REQUESTS;异常时按 deleteKeyWhenException 删 key | idempotent/core/aop/IdempotentAspect.java |
IdempotentRedisDAO | key idempotent:%s,底层 setIfAbsent(key, "", timeout, unit) | idempotent/core/redis/IdempotentRedisDAO.java |
Default/User/ExpressionIdempotentKeyResolver | 默认 MD5(方法签名+参数);用户维度追加 userId+userType;表达式维度走 SpEL | idempotent/core/keyresolver/impl/ |
PmforgeRateLimiterConfiguration + RateLimiterAspect | 5 个 key 解析器(默认/用户/IP/节点/表达式) | ratelimiter/config/、ratelimiter/core/aop/ |
RateLimiterRedisDAO | key rate_limiter:%s,Redisson RRateLimiter,超限抛 TOO_MANY_REQUESTS | ratelimiter/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 |
ApiSignatureRedisDAO | appSecret(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 |
注解默认值:
| 注解 | 属性默认值 |
|---|---|
@Idempotent | timeout=1、timeUnit=SECONDS、message="重复请求,请稍后重试"、keyResolver=DefaultIdempotentKeyResolver、deleteKeyWhenException=true |
@RateLimiter | time=1、timeUnit=SECONDS、count=100、message=""(空则用 TOO_MANY_REQUESTS 的提示)、keyResolver=DefaultRateLimiterKeyResolver |
@ApiSignature | timeout=60(秒)、message="签名不正确";appId/timestamp/nonce/sign 默认就是同名请求头 |
4. 配置项
| 前缀 | 键 | 默认值 | 说明 |
|---|---|---|---|
| — | 无 | — | 本模块没有 @ConfigurationProperties |
lock4j | lock4j.* | 由 lock4j 依赖提供 | 锁超时、获取超时等走第三方库自己的配置项 |
签名相关的「配置」是 Redis 里的数据,不是 yaml:
| Redis key | 结构 | 说明 |
|---|---|---|
api_signature_app | HASH,field=appId,value=appSecret | 预加载、不过期;缺失时用 hutool Assert.notNull 直接抛 IllegalArgumentException |
api_signature_nonce:%s:%s | String(appId + nonce) | TTL = timeout * 2 秒,用于防重放 |
idempotent:%s | String(空值) | TTL = 注解的 timeout/timeUnit |
rate_limiter:%s | Redisson RRateLimiter | 首次按 count + time 创建,之后按需 setRate |
lock4j:%s | Redisson 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. 常见坑
@Idempotent的timeout不是「防重复执行」而是「执行窗口」:注解注释原话——方法执行时间超过timeout时,后续请求仍会进来。delKey属性被刻意移除:package-info说明「delKey=true本质是分布式锁,应改用 Lock4j」;实现也弃用了RMap,只用 Redis String。- 签名失败的错误码不统一:
appSecret不存在时ApiSignatureRedisDAO用 hutoolAssert.notNull抛IllegalArgumentException(最终 500),而其他签名问题抛ServiceException("签名不正确")(400 段),排查时容易误判为服务端 bug。 ApiSignatureRedisDAO的 Javadoc 与代码 key 不一致:注释写signature_nonce:%s,实际是api_signature_nonce:%s:%s,手工清 nonce 时按注释找会找不到。- nonce 长度必须 ≥ 10:不足直接判「签名不正确」,而不是提示 nonce 格式问题。
- 限流器的
count/time改了不会立刻生效:RateLimiterRedisDAO发现已有 limiter 且参数不同才setRate,窗口内的旧速率会被重置,压测时会看到跳变。
7. 关联页面
- starter-redis:
RedisTemplate与 Redisson 客户端来源 - starter-web:
ApiEncryptFilter与签名/加密的先后关系 - starter-security:跨租户权限跳过会影响加签接口的可见性
- 横切机制、配置项速查