cn-rdms/rdms-framework/rdms-spring-boot-starter-protection/README.md

rdms-spring-boot-starter-protection

模块定位

rdms-spring-boot-starter-protection 用于提供一组服务保护能力，减少业务代码里重复编写“防重复提交、限流、分布式锁、接口签名校验”这类横切逻辑。

当前模块实际包含四块能力：

1. 幂等：防止同一请求在短时间内被重复执行，例如重复提交、重复点击
2. 分布式锁：在并发场景下保证同一业务动作同一时间只有一个线程或节点执行
3. 限流：限制单位时间内的访问次数，避免接口被刷爆或高频调用
4. HTTP API 签名：校验调用方身份、请求时效和随机数，防止伪造请求和重放攻击

它的目标不是提供复杂的治理平台，而是把常见保护能力做成可声明、可复用、可分布式生效的基础设施。

设计思路

1. 用注解声明保护规则，用 AOP 统一执行

模块里的幂等、限流、签名校验都不是要求业务手写 Redis 判断逻辑，而是通过注解声明规则，再由 AOP 统一拦截执行：

1. @Idempotent
2. @RateLimiter
3. @ApiSignature

这样业务代码只负责说明“这个方法需要什么保护”，具体的 Redis Key 生成、重复请求判断、限流判断、签名验证由框架层统一处理。

2. 把状态统一放到 Redis，面向分布式部署

这个模块的保护能力不是单机内存级别，而是默认面向多实例部署场景：

1. 幂等使用 StringRedisTemplate
2. API 签名防重放使用 StringRedisTemplate
3. 限流使用 Redisson 的 RRateLimiter
4. 分布式锁接入 lock4j-redisson-spring-boot-starter

这意味着它的核心价值不是“本机防抖”，而是“多个节点共享保护状态”。

3. 单一能力单独建模，避免职责混杂

从实现上看，模块有一个比较明确的边界划分：

1. 幂等用于“同一请求短时间内只允许执行一次”
2. 分布式锁用于“并发竞争下只允许一个线程/节点进入”
3. 限流用于“单位时间窗口内限制请求次数”
4. API 签名用于“校验调用方身份、请求时效和防重放”

例如幂等组件没有扩展成“成功后立即删 Key”的锁语义，而是把这类能力交给 Lock4j 处理。

区分这两类能力时，可以抓住一个核心点：

1. 幂等控制的是“短时间内不要重复执行同一类请求”
2. 分布式锁控制的是“同一时间谁有资格进入临界区执行”

例如：

1. 用户连续点击两次“提交订单”，更适合用幂等
2. 两个线程同时刷新同一份缓存，只允许一个线程进入执行，更适合用分布式锁

一个常见误区是把长耗时任务也交给幂等处理。假设幂等窗口配置为 3 秒，但某个任务实际执行了 20 秒：

1. 第一个请求在第 0 秒进入
2. 幂等 Key 在第 3 秒过期
3. 第二个请求在第 5 秒再次进入
4. 此时第一个任务还没执行完，但第二个请求已经有机会再次执行

所以幂等更偏“防重复请求”，而不是“在整个执行期间控制线程执行权”。如果真正关心的是执行过程中的互斥，应优先使用分布式锁。

4. 用 KeyResolver 抽象不同粒度的保护范围

幂等和限流都没有把 Key 生成规则写死，而是抽成了 KeyResolver：

1. 默认级别：方法名 + 参数
2. 用户级别：方法名 + 参数 + 当前用户
3. IP 级别：方法名 + 参数 + 客户端 IP
4. 节点级别：方法名 + 参数 + 当前服务节点
5. 表达式级别：通过 SpEL 自定义 Key

这样模块能在“全局、按用户、按 IP、按节点、按业务字段”之间切换，而不是只能支持一种固定粒度。

5. 自动装配按功能块拆分

自动配置入口见： META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

当前注册了四个自动配置类：

1. RdmsIdempotentConfiguration
2. RdmsLock4jConfiguration
3. RdmsRateLimiterConfiguration
4. RdmsApiSignatureAutoConfiguration

这说明模块是按能力块拆分装配的，而不是堆在一个总配置类里。

功能说明

1. 幂等

核心类：

1. Idempotent
2. IdempotentAspect
3. IdempotentRedisDAO

实现方式：

1. AOP 拦截带 @Idempotent 的方法
2. 通过 IdempotentKeyResolver 解析 Redis Key
3. 调用 SETNX + EXPIRE 语义的 setIfAbsent
4. 锁定失败时抛出“重复请求”异常
5. 业务异常时可按配置删除 Key，允许后续重试

适合场景：

1. 防止用户双击按钮
2. 防止表单重复提交
3. 防止短时间内重复触发同一个业务动作

典型案例：

1. 创建工单时，前端连续点击两次“提交”，只允许创建一次
2. 导入任务提交后，用户刷新页面再次点击“开始导入”，短时间内不允许重复发起
3. 审批流提交节点时，浏览器因为网络抖动自动重发请求，后端只执行一次

边界说明：

1. 这里的幂等更偏“短时间窗口防重复请求”，不适合作为支付、退款这类长期业务幂等的唯一方案
2. 对于支付回调、订单状态推进这类场景，更可靠的做法仍然是基于业务唯一号和持久化状态做幂等判断，必要时再配合分布式锁

可选 KeyResolver：

1. DefaultIdempotentKeyResolver
2. UserIdempotentKeyResolver
3. ExpressionIdempotentKeyResolver

示例：

@Idempotent(timeout = 3, message = "请勿重复提交")
public Long createOrder(OrderCreateReqVO reqVO) {
    return orderService.createOrder(reqVO);
}

如果需要按某个参数做幂等，可以使用表达式：

@Idempotent(
        keyResolver = ExpressionIdempotentKeyResolver.class,
        keyArg = "#reqVO.no",
        timeout = 10
)
public void submit(OrderReqVO reqVO) {
}

如果接口已经完成登录鉴权，也可以按“当前登录用户 + 接口参数”做幂等：

@Idempotent(
        keyResolver = UserIdempotentKeyResolver.class,
        timeout = 3,
        message = "请勿重复提交"
)
public CommonResult<Long> createOrder(OrderCreateReqVO reqVO) {
    return success(orderService.createOrder(reqVO));
}

这种方式不要求把 userId 显式放在请求参数里，而是从当前登录上下文中获取用户信息，适合“同一个用户短时间内不能重复提交同一类请求”的场景。

2. 限流

核心类：

1. RateLimiter
2. RateLimiterAspect
3. RateLimiterRedisDAO

实现方式：

1. AOP 在方法执行前拦截
2. 通过 RateLimiterKeyResolver 解析限流 Key
3. 使用 Redisson 的 RRateLimiter 设置速率
4. 超过限制时抛出“请求过于频繁”异常

适合场景：

1. 接口防刷
2. 高频查询保护
3. 短时间内限制短信、验证码、导出等高成本操作
4. 对开放接口或公网接口做基础流量保护

典型案例：

1. 短信验证码接口限制“1 分钟内最多发送 1 次”
2. 导出 Excel 接口限制“10 分钟内最多导出 3 次”
3. 登录接口按 IP 限制访问频率，防止暴力尝试
4. 某个开放查询接口按调用方或用户维度限制 QPS，避免被刷爆

可选 KeyResolver：

1. DefaultRateLimiterKeyResolver
2. UserRateLimiterKeyResolver
3. ClientIpRateLimiterKeyResolver
4. ServerNodeRateLimiterKeyResolver
5. ExpressionRateLimiterKeyResolver

示例：

@RateLimiter(count = 5, time = 1, timeUnit = TimeUnit.MINUTES, message = "请求过于频繁")
public CommonResult<Boolean> sendSmsCode(String mobile) {
    return success(true);
}

如果希望按用户限流：

@RateLimiter(
        count = 10,
        time = 1,
        timeUnit = TimeUnit.MINUTES,
        keyResolver = UserRateLimiterKeyResolver.class
)
public PageResult<OrderRespVO> pageMyOrders(OrderPageReqVO reqVO) {
    return orderService.pageMyOrders(reqVO);
}

3. HTTP API 签名

核心类：

1. ApiSignature
2. ApiSignatureAspect
3. ApiSignatureRedisDAO

实现方式：

1. 从请求头中读取 appId、timestamp、nonce、sign
2. 校验时间戳是否过期
3. 校验 nonce 是否已使用，防止重放
4. 根据 appId 从 Redis 中获取 appSecret
5. 按“请求参数 + 请求体 + 请求头 + 密钥”构建签名字符串
6. 使用 SHA-256 计算服务端签名并比对

适合场景：

1. 开放接口
2. 系统间调用
3. 对请求来源和重放攻击有要求的 HTTP 接口

典型案例：

1. 第三方系统调用内部开放 API 时，使用 appId + appSecret 做签名校验
2. 支付平台、供应商平台、合作方系统调用回调接口时，先校验签名再进入业务处理
3. 对外提供的 B2B 接口要求请求在 60 秒内有效，并且 nonce 只能使用一次

示例：

@ApiSignature(timeout = 60)
public CommonResult<String> callback() {
    return success("ok");
}

当前切面是按 @annotation(signature) 拦截的，因此实操上应优先加在方法上。

4. 分布式锁

核心类：

1. RdmsLock4jConfiguration
2. DefaultLockFailureStrategy

这部分没有重复实现分布式锁，而是接入 Lock4j，并补了一层默认失败策略：

1. 如果类路径存在 Lock4j，则启用配置
2. 在获取锁失败时，统一抛出项目内的 ServiceException
3. 保持锁失败时的错误处理风格一致

适合场景：

1. 防止同一业务动作并发执行
2. 串行化关键资源操作
3. 抢占式处理任务

典型案例：

1. 同一个用户同时触发两次“刷新缓存”，只允许一个线程进入
2. 定时任务集群部署时，同一时间只允许一个节点执行清理任务
3. 库存扣减、状态迁移、批量结算这类关键动作，在并发场景下需要串行处理

示例：

@Lock4j(keys = "#userId", expire = 30000, acquireTimeout = 1000)
public void refreshUserCache(Long userId) {
}

自动装配链路

1. Spring Boot 自动配置入口

META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

1. com.njcn.rdms.framework.idempotent.config.RdmsIdempotentConfiguration
2. com.njcn.rdms.framework.lock4j.config.RdmsLock4jConfiguration
3. com.njcn.rdms.framework.ratelimiter.config.RdmsRateLimiterConfiguration
4. com.njcn.rdms.framework.signature.config.RdmsApiSignatureAutoConfiguration

2. 各配置类负责的事情

配置类	作用
RdmsIdempotentConfiguration	注册幂等切面、幂等 Redis DAO、幂等 KeyResolver
RdmsLock4jConfiguration	在 Lock4j 存在时注册默认加锁失败策略
RdmsRateLimiterConfiguration	注册限流切面、限流 Redis DAO、限流 KeyResolver
RdmsApiSignatureAutoConfiguration	注册 API 签名切面、签名 Redis DAO

如何使用

1. 引入依赖

业务模块通常直接依赖：

<dependency>
    <groupId>com.njcn</groupId>
    <artifactId>rdms-spring-boot-starter-protection</artifactId>
</dependency>

2. 基础前提

这个模块依赖 Redis，因此至少需要可用的 Redis 配置。

其中：

1. 幂等依赖 StringRedisTemplate
2. API 签名依赖 StringRedisTemplate
3. 限流依赖 RedissonClient
4. 分布式锁依赖 Lock4j + Redisson

3. 选择合适的保护手段

1. 防重复提交，优先使用 @Idempotent
2. 控制访问频率，优先使用 @RateLimiter
3. 控制并发进入，优先使用 Lock4j
4. 保护开放接口，优先使用 @ApiSignature

不要把它们混成一类能力：

1. 幂等不等于分布式锁
2. 限流不等于幂等
3. API 签名不等于权限校验

4. KeyResolver 的选择建议

1. 默认对全局请求做保护，使用默认 Resolver
2. 需要按登录用户隔离保护，使用 User Resolver
3. 需要按 IP 控制访问，使用 ClientIp Resolver
4. 需要按业务字段控制粒度，使用 Expression Resolver

注意事项

1. 幂等的 timeout 只是保护窗口，不是业务执行超时时间。如果方法执行时间长于这个窗口，后续请求仍可能进入。
2. 幂等在异常时默认删除 Key，这是为了允许业务失败后重新提交；如果追求的是“执行期间只允许一个线程进入”，更适合使用分布式锁。
3. 限流底层使用 Redisson 的 RRateLimiter，运行环境需要有 RedissonClient。
4. API 签名依赖 Redis 中预先存在 appId -> appSecret 的映射，否则签名校验无法通过。
5. API 签名当前实操上应加在方法上，避免把类级注解误认为一定会生效。
6. 这个模块的保护能力都是方法级横切逻辑，适合放在 Controller 或 Service 的明确边界上使用，不适合到处滥加。

总结

这个模块的核心价值，是把服务保护相关的高频横切问题统一沉到框架层：

1. 如何防止重复提交
2. 如何限制单位时间的访问频率
3. 如何在分布式环境下串行化关键操作
4. 如何校验开放接口的请求签名和防重放

如果把它理解成一个“请求保护与并发保护能力集合”的 starter，这个模块的设计会比较清晰。