1. 背景目标

近期运营团队反馈，飞书消息接收者出现明显的消息疲劳现象。经分析发现，各业务消息的发送必要性需结合具体场景判断，仅依靠发送量无法准确识别冗余消息。

为了解决这种消息疲劳问题，除了从业务层面进行规范外，还可以从技术角度出发，通过滑动窗口限流机制来控制消息发送频率

2. 滑动窗口理解

结合飞书消息场景，用图的方式进一步理解滑动窗口。

例如：x 轴表示时间，单位为秒。下图是从第1秒到第15秒，绿色表示发送给某一个人的消息时刻。

那么如何定义发送消息是否频率过高呢？

#技术分享在 TCP 网络传输中，采用滑动窗口来控制流量。(下图为网络传输)

那么也可以按照这种思想，将窗口大小定位为 5s。在窗口5s 内，最多接收1条消息，如果多了就表示接收频率过高了。

时间:1-5s，接收到 1 条消息，频率合理

时间:2-6s，接收到 2 条消息，超过 1 条，频率不合理。

时间:4-8s, 接收到 2 条消息，超过 1 条，频率不合理。

时间:7-11s, 接收到 2 条消息，超过 1 条，频率不合理。

以5秒为时间窗口，最多仅允许接收1条消息。第6秒、第8秒、第11秒的发送行为被判定为频率过高。

我们继续以5秒窗口、最多1条消息的规则为例，给出一个符合该规则的健康发送时间序列（只要在任意时间窗口内只包含1条消息即可，图中粉色标记为发送时刻）

通过动态滑动的5秒窗口进行持续检测，确保任意连续5秒内消息不超过1条，即可实现平滑的消息控制。

3. 场景应用

这样的场景还有很多，举一些例子。

| 场景情况举例 | 规则抽象 | | ---

| 最近1小时，最多收到1条飞书消息 | 窗口：1h，阈值：1 | | 最近1天，最多重试3次 | 窗口：1d，阈值：3 | | 最近1h，如果发生3次，则发出警告 | 窗口: 1h, 阈值：3 | | ...... | ...... |

通过场景抽象，编写了一套简易的 API 以支持上面场景。

4. API规范

该 API 规范基于 Redis 底层接口实现，提供了一套简易的滑动窗口限流机制。下面是简易流程图：根据唯一 Key，内部生成一个计数器。每次请求，会判断计数是否达到阈值。

详细接口如下：

public interface SlidingWindowLimitService {

boolean calculate(String key, long windowLenInSeconds, long threshold);

boolean calculate(String key, String scene); }

核心 API 能力 ：boolean calculate(String key, long windowLenInSeconds, long threshold) ;

• key： 业务场景唯一标准，比如xxx模版下的飞书消息发送
• windowLenInSeconds：时间窗口大小，单位秒
• threshold：阈值

--- 使用案例：给用户 A 发送告警消息，窗口1h 小时，最多收到2条。

• key：user_id_123_ alarm
• windowLenInSeconds：3600
• threshold：2

当在窗口1h 内，如果达到3次，boolean 返回值为 false。业务可以根据 false 这个接口阻止消息的发送。

--- 命名建议: Key 采用"业务模块:用户标识:场景"结构（例：
alert:user123:high_priority）

boolean calculate(String key, String scene); scene 目前封装了场景。可以从 nacos 中动态配置规则。

--- 补充部分细节

基于 Redis 中 ZSet 实现滑动窗口机制

• 每次发送消息时，将当前时间戳插入ZSet；
• 删除窗口外的旧时间戳；
• 判断当前窗口内元素数量是否超过阈值

更多细节可以参考上一篇文章：juejin.cn/post/733954…

5. 如何使用

该项目是一个 Spring Boot Starter 模块，可作为公共依赖引入使用。

**特别注意：该项目依赖 RedisTemplate，需要配置 redis，如果需要使用 scene，需要添加 nacos **

使用案例如下：

@RestController
@RequestMapping("/test")
public class SlidingWindowLimitTestController {

@Autowired private SlidingWindowLimitService slidingWindowLimitService;

@GetMapping("/calculate") public boolean slidingWindowCalculate(@RequestParam("key") String key, @RequestParam("scene") String scene) { return slidingWindowLimitService.calculate(key, scene); }

@GetMapping("/calculateLimit") public boolean slidingWindowCalculate(@RequestParam("key") String key, @RequestParam("windowLenInSeconds") long windowLenInSeconds, @RequestParam("threshold") long threshold ) { return slidingWindowLimitService.calculate(key, windowLenInSeconds, threshold); } }

使用案例参考：module: sliding-window-starter 代码地址：github.com/uzong/slidi…

6. 注意事项

1. 本SDK依赖Redis，请确保Redis服务可用。（如果使用 ZSet 的计算压力过高，会再单独申请一个 Redis 实例，专职专用）
2. 合理设置时间窗口和阈值，避免过度限制正常用户
3. key 的命名应尽量添加业务前缀，以提升唯一性，确保全局唯一
4. 滑动窗口不同于固定窗口，它会随着时间进行滑动。滑动窗口对时间更敏感，能避免“窗口边缘突增”问题

7. 补充细节

redis 中 zset 的部分 API 的时间复杂度

• ZADD：时间复杂度：O(M*log(N))，其中 M 是成功添加的成员数，N 是有序集合的基数
• ZRANGEBYSCORE：时间复杂度：O(log(N)+M)，其中 N 是有序集合的基数，M 是符合条件的成员数量
• ZSCAN：迭代有序集合中的元素。时间复杂度：O(1) 随着迭代次数的增加而增加