配置详解
📚 目录
快速开始
最简单的配置:
⚠️ 重要提示:
- 默认值
max: 100仅作为示例,请根据实际业务调整 - 登录等敏感接口建议设置为
5-10 - 公开API建议设置为
1000+(配合更长的时间窗口)
核心配置项
1. windowMs - 时间窗口(必需)
说明:限流的时间范围(毫秒)
推荐配置:
- 登录/注册:
15 * 60 * 1000(15分钟) - API查询:
60 * 1000(1分钟) - 数据修改:
60 * 60 * 1000(1小时)
默认值:60000(1分钟)
2. max - 最大请求数(必需)
说明:在时间窗口内允许的最大请求次数
推荐配置:
- 登录/注册:
5(严格限制,防暴力破解)⭐⭐⭐ - 敏感操作:
10(修改密码、支付等) - 数据修改:
50(创建、更新、删除) - API查询:
100(列表、详情等) - 高频查询:
200-500(搜索、统计等) - 公开API:
1000+(开放接口)
默认值:100(仅作示例,请根据业务调整)
3. algorithm - 限流算法(可选)
说明:选择限流算法,不同算法有不同特性
默认值:'sliding-window'(最精确)
快速对比
💡 算法对比文档:
算法详解
1. sliding-window(滑动窗口) - 默认推荐
工作方式:
- 每次请求都检查"往前推60秒"内的所有请求数
- 任意连续60秒内严格≤100次
- 0ms时刻100个请求全部允许,第101个拒绝
- 0ms的请求在60000ms时过期,此时可以再发新请求
特点:
- ✅ 最精确:任意时刻都精确限制
- ✅ 无边界问题:不会出现窗口切换时的超频
- ✅ 支持并发:瞬间100个请求全部允许(不是"不允许突发")
- ❌ 内存占用高:需要存储所有请求时间戳
适用:API限流、登录保护、需要精确控制的场景
2. fixed-window(固定窗口) - 高并发场景
工作方式:
- 时间分为固定的窗口:[0-60s)、[60-120s)、[120-180s)...
- 每个窗口内独立计数,最多100次
- 窗口切换时计数器重置为0
边界问题示例:
特点:
- ✅ 最快速:O(1)复杂度,内存占用最低
- ⚠️ 边界超频:窗口交界处可能瞬间允许2倍请求(200次)
- ⚠️ 不精确:不符合"任意连续60秒"的语义
适用:高并发场景(具体吞吐需压测确认),可接受边界超频
3. token-bucket(令牌桶) - 允许突发
工作方式:
- 桶初始有100个令牌(满)
- 每秒补充100个令牌(最多补到100)
- 每个请求消耗1个令牌
- 有令牌就立即处理,没有就拒绝
实际表现:
与 sliding-window 的区别:
核心差异:
- sliding-window:100次用完后要等60秒
- token-bucket:100次用完后按速率持续补充(每10ms补1个)
特点:
- ✅ 允许突发:桶满时可瞬间处理capacity个请求
- ✅ 持续可用:按refillRate持续补充令牌
- ✅ 用户体验好:不会长时间完全阻塞
适用:API网关、允许持续高频请求的场景
4. leaky-bucket(漏桶) - 平滑流量
当前实现的工作方式:
- 每次请求到达时,按
leakRate / windowMs计算桶内水位自然下降 - 水位未满则立即允许当前请求,并把水位加 1
- 水位已满则立即拒绝当前请求;库本身不会排队、延迟或后台匀速派发请求
实际表现:
"漏出速率"的具体值:
- 配置:leakRate: 100, windowMs: 1000
- 恒定速率 = 每秒漏出100个 = 每10ms漏1个
- 这里的漏出是计数水位衰减,不是请求处理队列
特点:
- ✅ 平滑准入:按水位衰减速度控制后续请求重新进入的节奏
- ✅ 低开销:不维护请求队列,允许/拒绝都在当前请求内完成
- ❌ 不提供排队:如果需要后台匀速处理任务,应结合消息队列或任务调度器
适用:保护后端系统、需要平滑请求准入但不需要排队处理的场景
📖 详细文档:
4. store - 存储后端(可选)
说明:存储限流数据的位置
默认值:'memory'
选择建议:
- 单服务器:使用
memory(快速、简单) - 多服务器:使用
Redis(分布式、数据共享) - 需要复用 cache-hub 原子状态能力:使用
CacheHubStore - 使用
store: 'redis://...'时,库会创建 Redis client;短生命周期进程结束前调用await limiter.close() - 使用
new RedisStore({ client })时,client 默认由调用方关闭;需要 store 代管时设置ownsClient: true
5. keyGenerator - 键生成器(可选)
说明:生成唯一的限流键,决定"按什么维度限流"
默认值:按IP限流
常见场景:
- 按IP:
keyGenerators.ip(公开API) - 按用户:
keyGenerators.userId(登录后API) - 按用户+路由:
keyGenerators.userAndRoute(业务锁,推荐)⭐
📖 详细说明:business-lock-guide.md
6. 其他配置项
完整配置示例
参数速查表
实战配置场景
场景1:登录保护(严格限制)⭐⭐⭐
场景2:敏感操作(中等限制)
场景3:数据修改(普通限制)
场景4:API查询(宽松限制)
场景5:公开API(高频限制)
场景6:用户等级分级
场景7:分布式系统(Redis)
推荐配置速查表
Redis 存储配置
📚 相关文档
下一步阅读:
相关主题:
返回:
- 📖 文档中心 - 查看所有文档和学习路径