封装 Redis + Lua 多维度分布式限流组件
目标是用 AOP + 注解 + Redis + Lua 封装一个支持多维度、分布式、Redis Cluster 兼容的限流组件。
一、单机限流 vs 分布式限流
在实际业务中,限流通常有两种实现思路:单机限流 和 分布式限流。
| 对比维度 | 单机限流(如 Guava RateLimiter) |
分布式限流(如 Redis + Lua) |
|---|---|---|
| 实现原理 | 进程内存维护计数器 | Redis 作为共享存储 |
| 适用场景 | 单实例应用 | 多实例集群部署 |
| 性能开销 | 极低(纯内存操作) | 中等(包含网络 I/O) |
| 数据一致性 | 实例间独立,无法协同 | 全局统一限流 |
| 运维成本 | 无需额外组件 | 需要 Redis 服务 |
结论
- 如果服务是 单实例,单机限流足够简单高效。
- 如果服务是 多实例 / 微服务集群,就需要分布式限流来保证全局一致性。
二、整体架构设计
本项目通过 AOP + 自定义注解 + Redisson + Lua 脚本 实现分布式限流。
设计目标
- 业务无侵入:业务方法只需要加注解,不需要手写限流逻辑。
- 支持多维度限流:可以按全局、IP、用户等维度组合限流。
- 保证原子性:通过 Lua 脚本一次性完成校验和扣减。
- 兼容 Redis Cluster:通过 Hash Tag 确保相关 Key 落在同一 Slot。
核心优势
1. 关注点分离(AOP)
限流本质上属于横切逻辑,不应该和业务代码强耦合。
使用 AOP 后,可以把限流逻辑统一收敛到切面中管理。
2. 声明式使用(Annotation)
开发者只需要在方法上加 @RateLimit 注解并配置参数,就能完成限流接入。
3. 分布式支持
所有实例共享 Redis 中的限流状态,因此可以实现真正意义上的全局限流。
4. 原子性保证
Lua 脚本在 Redis 中执行,可以确保“检查额度 + 扣减额度”是一个原子操作,避免并发下超发。
三、限流注解设计
@RateLimit 是整个组件的入口,用于定义限流规则。
package interview.guide.common.annotation;
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface RateLimit {
/**
* 限流维度枚举
*/
enum Dimension {
/** 全局限流:对所有请求统一限流 */
GLOBAL,
/** IP 限流:按客户端 IP 地址限流 */
IP,
/** 用户限流:按用户 ID 限流 */
USER
}
/**
* 限流维度配置。
* 支持多维度组合,只有所有维度都满足条件时才允许请求通过。
*/
Dimension[] dimensions() default {Dimension.GLOBAL};
/**
* 在指定时间窗口内允许的最大请求数。
* 例如:count = 10, interval = 1, timeUnit = SECONDS,表示每秒最多 10 次。
*/
double count();
/** 时间窗口大小,默认 1 */
long interval() default 1;
/** 时间单位,默认为秒 */
TimeUnit timeUnit() default TimeUnit.SECONDS;
/**
* 等待令牌的超时时间。
* 0 表示不等待,直接尝试获取令牌,失败则拒绝。
*/
long timeout() default 0;
/**
* 降级方法名。
* 支持无参方法,或与原方法参数列表一致的方法。
*/
String fallback() default "";
enum TimeUnit {
MILLISECONDS, SECONDS, MINUTES, HOURS, DAYS
}
}
设计要点
-
count + interval + timeUnit:比单纯的permitsPerSecond更灵活,表达能力更强。 -
dimensions:支持多维度组合,例如“全局 + IP + 用户”同时生效。 -
fallback:被限流时可走降级逻辑,而不是直接抛异常。
四、AOP 切面实现思路
RateLimitAspect 是整个限流逻辑的核心,负责:
- 拦截带
@RateLimit的方法 - 解析注解参数
- 动态生成 Redis Key
- 调用 Lua 脚本进行原子限流
- 根据结果决定放行、降级还是拦截
核心流程代码
package interview.guide.common.aspect;
MethodSignature signature = (MethodSignature) joinPoint.getSignature();
Method method = signature.getMethod();
String className = method.getDeclaringClass().getSimpleName();
String methodName = method.getName();
// 1. 计算时间窗口(毫秒)
long intervalMs = calculateIntervalMs(rateLimit.interval(), rateLimit.timeUnit());
// 2. 根据配置维度动态生成 Redis Keys
List<String> keys = generateKeys(className, methodName, rateLimit.dimensions());
// 3. 调用 Lua 脚本执行原子限流
RScript script = redissonClient.getScript(StringCodec.INSTANCE);
List<Object> keysList = new ArrayList<>(keys);
Object[] args = {
String.valueOf(System.currentTimeMillis()), // ARGV[1]: 当前时间戳
String.valueOf(1), // ARGV[2]: 申请令牌数(默认 1 个)
String.valueOf(intervalMs), // ARGV[3]: 时间窗口
String.valueOf(rateLimit.count()), // ARGV[4]: 最大令牌数
UUID.randomUUID().toString() // ARGV[5]: 请求唯一标识
};
Object resultObj = script.evalSha(
RScript.Mode.READ_WRITE,
luaScriptSha,
RScript.ReturnType.VALUE,
keysList,
args
);
Long result = convertToLong(resultObj);
// 4. 处理限流结果
if (result == null || result == 0) {
return handleRateLimitExceeded(joinPoint, rateLimit, keys);
}
// 5. 执行原方法
return joinPoint.proceed();
时间窗口换算
private long calculateIntervalMs(long interval, RateLimit.TimeUnit unit) {
return switch (unit) {
case MILLISECONDS -> interval;
case SECONDS -> interval * 1000;
case MINUTES -> interval * 60 * 1000;
case HOURS -> interval * 3600 * 1000;
case DAYS -> interval * 86400 * 1000;
};
}
关键点说明
- SHA 预加载:启动时把 Lua 脚本加载到 Redis,后续通过 SHA 调用,减少脚本内容重复传输。
-
StringCodec:确保参数以字符串形式传给 Redis,避免序列化或类型转换问题。 - 切面统一拦截:业务代码只关注功能本身,不关心限流实现细节。
五、为什么要用 Hash Tag
在 Redis Cluster 模式下,多个 Key 不一定落在同一个节点上。
而 Lua 脚本、多 Key 原子操作都要求这些 Key 位于同一個 Slot。
关键结论:如果 Redis Key 中包含
{...},Redis Cluster 会只对大括号里的内容计算槽位。
1. Redis Cluster 为什么有这个问题
Redis Cluster 会把所有 Key 映射到 16384 个槽位之一:
slot = CRC16(key) % 16384
然后每个节点负责其中一部分 Slot。
如果多个 Key 落在不同 Slot,就可能出现以下问题:
- Lua 脚本无法同时操作这些 Key
- 多 Key 命令会失败
- 事务 / 原子性操作受限
常见报错如下:
CROSSSLOT Keys in request don't hash to the same slot
2. Hash Tag 的原理
默认情况:整个 Key 参与 hash
例如:
ratelimit:OrderController:createOrder:global
ratelimit:OrderController:createOrder:user:10086
虽然前缀相似,但由于完整 Key 不同,计算出的 Slot 也可能不同。
使用 Hash Tag 后:只对 {} 中内容做 hash
例如:
ratelimit:{OrderController:createOrder}:global
ratelimit:{OrderController:createOrder}:user:10086
ratelimit:{OrderController:createOrder}:ip:192.168.1.10
Redis Cluster 只会拿 OrderController:createOrder 去计算 Slot,因此这些 Key 一定会落在同一个 Slot。
3. 这里为什么选 {className:methodName}
因为需要把“同一个接口”的所有限流 Key 放在一起。
也就是说:
- 同一个方法下的
global / ip / user等维度都放在同一组 - 不同方法之间则各自独立
这样既能支持 Lua 脚本原子执行,也方便做逻辑分组和问题排查。
六、Redis Key 生成逻辑
下面这段代码用于根据维度动态生成限流 Key:
/**
* 生成限流键列表
*/
private List<String> generateKeys(String className, String methodName, RateLimit.Dimension[] dimensions) {
List<String> keys = new ArrayList<>();
// 使用 {} 包含类名和方法名作为 Hash Tag
// 确保该方法的所有限流 Key 落在同一个 Redis Slot
// 从而适配 Redis Cluster 模式
String hashTag = "{" + className + ":" + methodName + "}";
String keyPrefix = "ratelimit:" + hashTag;
for (RateLimit.Dimension dimension : dimensions) {
switch (dimension) {
case GLOBAL -> keys.add(keyPrefix + ":global");
case IP -> keys.add(keyPrefix + ":ip:" + getClientIp());
case USER -> keys.add(keyPrefix + ":user:" + getCurrentUserId());
}
}
return keys;
}
生成后的 Key 示例
假设:
- 类名:
UserController - 方法名:
login - 客户端 IP:
10.1.2.3 - 用户 ID:
9527
那么会生成:
ratelimit:{UserController:login}:global
ratelimit:{UserController:login}:ip:10.1.2.3
ratelimit:{UserController:login}:user:9527
这样设计的好处
- 同一个接口的所有限流维度都能放在一个 Slot 中
- 可以被同一个 Lua 脚本原子处理
- 避免
CROSSSLOT错误 - Key 语义清晰,便于排查和监控
七、Lua 脚本:原子化多维度限流核心
Lua 脚本负责实现“先检查,再统一扣减”的原子逻辑。
参数说明
-
ARGV[1]:当前时间戳(毫秒) -
ARGV[2]:本次申请的令牌数 -
ARGV[3]:时间窗口(毫秒) -
ARGV[4]:窗口内允许的最大请求数 -
ARGV[5]:请求唯一标识
Lua 脚本实现
-- 原子化多维度限流脚本
-- ARGV[1]: 当前时间戳(毫秒)
-- ARGV[2]: 申请令牌数
-- ARGV[3]: 时间窗口(毫秒)
-- ARGV[4]: 最大令牌数(窗口内允许的总数)
-- ARGV[5]: 请求唯一标识
local now_ms = tonumber(ARGV[1])
local permits = tonumber(ARGV[2])
local interval = tonumber(ARGV[3])
local max_tokens = tonumber(ARGV[4])
local request_id = ARGV[5]
-- ========== 第一阶段:预检查 ==========
-- 检查所有维度是否有足够令牌
for i, key in ipairs(KEYS) do
local value_key = key .. ":value"
local permits_key = key .. ":permits"
-- 初始化 value_key(如果不存在)
if redis.call("exists", value_key) == 0 then
redis.call("set", value_key, max_tokens)
end
-- 回收过期令牌:清理过期的 permit 记录,并回收配额到 value_key
local expired_values = redis.call("zrangebyscore", permits_key, 0, now_ms - interval)
if #expired_values > 0 then
local expired_count = 0
for _, v in ipairs(expired_values) do
local p = tonumber(string.match(v, ":(%d+)$"))
if p then
expired_count = expired_count + p
end
end
-- 删除过期记录
redis.call("zremrangebyscore", permits_key, 0, now_ms - interval)
-- 回收配额
if expired_count > 0 then
local curr_v = tonumber(redis.call("get", value_key) or max_tokens)
local next_v = math.min(max_tokens, curr_v + expired_count)
redis.call("set", value_key, next_v)
end
end
-- 核心检查:当前可用令牌是否足够
local current_val = tonumber(redis.call("get", value_key) or max_tokens)
if current_val < permits then
-- 任意一个维度配额不足,直接失败
return 0
end
end
-- ========== 第二阶段:统一扣减 ==========
-- 只有所有维度都通过检查后,才真正扣减
for i, key in ipairs(KEYS) do
local value_key = key .. ":value"
local permits_key = key .. ":permits"
-- 记录本次令牌分配(格式:request_id:permits)
local permit_record = request_id .. ":" .. permits
redis.call("zadd", permits_key, now_ms, permit_record)
-- 扣减令牌
local current_v = tonumber(redis.call("get", value_key) or max_tokens)
redis.call("set", value_key, current_v - permits)
-- 设置过期时间,确保过期令牌能被正常回收
-- 过期时间为窗口的 2 倍,至少 1 秒
local expire_time = math.ceil(interval * 2 / 1000)
if expire_time < 1 then
expire_time = 1
end
redis.call("expire", value_key, expire_time)
redis.call("expire", permits_key, expire_time)
end
-- 成功获取所有维度的令牌
return 1
脚本逻辑拆解
第一阶段:预检查
对每个维度依次做三件事:
- 初始化当前可用令牌数
- 回收窗口外的过期令牌
- 判断当前令牌是否足够
只要有任意一个维度不足,就立即返回 0,整个请求失败。
第二阶段:统一扣减
只有当所有维度都校验通过时,才会真正执行扣减:
- 往 ZSet 中记录本次请求
- 从
value_key中扣减可用令牌 - 设置过期时间,避免脏数据长期堆积
设计亮点
- 两阶段处理:先检查、后扣减,避免只扣了一部分维度。
- 原子执行:Lua 脚本在 Redis 中串行执行,天然具备原子性。
- 支持多维度组合:一份脚本即可同时处理多个限流维度。
八、Redis 数据结构设计
为了实现精准限流,每个维度配合使用两种数据结构:
1. String:{key}:value
作用:记录当前剩余令牌数。
特点:
- 读写复杂度低,接近
O(1) - 适合快速判断当前是否还有可用配额
2. Sorted Set:{key}:permits
作用:记录每次请求申请令牌的时间轴流水。
设计如下:
-
Member:
request_id:permits - Score:毫秒级时间戳
这样设计的原因:
- 可以通过时间范围快速找到过期记录
- 可以统计需要回收多少令牌
- 能避免同一毫秒内 Member 覆盖的问题
这里的
request_id很关键。
如果不用唯一 ID,而是直接把permits当成 Member,同一毫秒内多个请求可能发生覆盖,导致限流失效。
九、整体执行流程
一次请求进入系统后,大致会经历以下步骤:
- 业务方法被 AOP 切面拦截
- 读取
@RateLimit注解配置 - 计算时间窗口
- 按维度生成 Redis Key
- 调用 Lua 脚本做原子校验和扣减
- 如果返回
1,说明限流通过,继续执行原方法 - 如果返回
0,说明配额不足,执行降级逻辑或直接拦截
可以把它理解为:
请求进来
-> AOP 拦截
-> 解析注解
-> 生成多维度 Key
-> Lua 原子判断
-> 任一维度不足:拒绝
-> 全部维度足够:统一扣减
-> 执行业务方法
十、面试时可以重点强调的点
如果在面试中讲这个项目,可以重点突出下面这些关键词:
1. 为什么不用单机限流
因为服务是多实例部署,单机内存限流无法做到全局一致,必须借助 Redis 这类共享存储。
2. 为什么用 Lua
因为限流涉及多个 Redis Key 的检查和扣减,必须保证原子性。Lua 脚本可以把这几步合并成一个不可分割的操作。
3. 为什么要支持多维度
单一维度容易被绕过。例如:
- 只做全局限流,无法控制单个热点用户
- 只做用户限流,无法限制恶意 IP 攻击
所以通常需要组合维度一起控制。
4. 为什么要用 Hash Tag
因为 Redis Cluster 下多 Key 操作要求这些 Key 位于同一个 Slot。
通过 {className:methodName} 可以把同一个接口下的所有限流 Key 固定到同一个 Slot。
5. 这个方案的代价是什么
- 比单机限流多一次 Redis 网络开销
- 热点接口可能集中打到某一个 Slot
- 脚本和 Key 设计复杂度更高
但换来的收益是:
- 分布式一致性
- 多维度扩展能力
- 原子性保障
- 集群兼容性
十一、一句话总结
这个限流组件的核心思想是:
用 注解 提供声明式接入,用 AOP 做统一拦截,用 Redis + Lua 实现多维度原子限流,再通过 Hash Tag 解决 Redis Cluster 下多 Key 同 Slot 的问题。