封装 Redis + Lua 多维度分布式限流组件

封装 Redis + Lua 多维度分布式限流组件

目标是用 AOP + 注解 + Redis + Lua 封装一个支持多维度、分布式、Redis Cluster 兼容的限流组件。


一、单机限流 vs 分布式限流

在实际业务中,限流通常有两种实现思路:单机限流 和 分布式限流。

对比维度 单机限流(如 Guava RateLimiter) 分布式限流(如 Redis + Lua)
实现原理 进程内存维护计数器 Redis 作为共享存储
适用场景 单实例应用 多实例集群部署
性能开销 极低(纯内存操作) 中等(包含网络 I/O)
数据一致性 实例间独立,无法协同 全局统一限流
运维成本 无需额外组件 需要 Redis 服务

结论

  • 如果服务是 单实例,单机限流足够简单高效。
  • 如果服务是 多实例 / 微服务集群,就需要分布式限流来保证全局一致性。

二、整体架构设计

本项目通过 AOP + 自定义注解 + Redisson + Lua 脚本 实现分布式限流。

设计目标

  1. 业务无侵入:业务方法只需要加注解,不需要手写限流逻辑。
  2. 支持多维度限流:可以按全局、IP、用户等维度组合限流。
  3. 保证原子性:通过 Lua 脚本一次性完成校验和扣减。
  4. 兼容 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 是整个限流逻辑的核心,负责:

  1. 拦截带 @RateLimit 的方法
  2. 解析注解参数
  3. 动态生成 Redis Key
  4. 调用 Lua 脚本进行原子限流
  5. 根据结果决定放行、降级还是拦截

核心流程代码

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

脚本逻辑拆解

第一阶段:预检查

对每个维度依次做三件事:

  1. 初始化当前可用令牌数
  2. 回收窗口外的过期令牌
  3. 判断当前令牌是否足够

只要有任意一个维度不足,就立即返回 0,整个请求失败。

第二阶段:统一扣减

只有当所有维度都校验通过时,才会真正执行扣减:

  1. 往 ZSet 中记录本次请求
  2. 从 value_key 中扣减可用令牌
  3. 设置过期时间,避免脏数据长期堆积

设计亮点

  • 两阶段处理:先检查、后扣减,避免只扣了一部分维度。
  • 原子执行: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,同一毫秒内多个请求可能发生覆盖,导致限流失效。


九、整体执行流程

一次请求进入系统后,大致会经历以下步骤:

  1. 业务方法被 AOP 切面拦截
  2. 读取 @RateLimit 注解配置
  3. 计算时间窗口
  4. 按维度生成 Redis Key
  5. 调用 Lua 脚本做原子校验和扣减
  6. 如果返回 1,说明限流通过,继续执行原方法
  7. 如果返回 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 的问题。

最后编辑于 :
©著作权归作者所有,转载或内容合作请联系作者
【社区内容提示】社区部分内容疑似由AI辅助生成,浏览时请结合常识与多方信息审慎甄别。
平台声明:文章内容(如有图片或视频亦包括在内)由作者上传并发布,文章内容仅代表作者本人观点,简书系信息发布平台,仅提供信息存储服务。

相关阅读更多精彩内容

友情链接更多精彩内容