ChAbdulWahhab/flowcap
GitHub: ChAbdulWahhab/flowcap
一个零依赖、框架无关的 Node.js HTTP 速率限制中间件，基于内存滑动窗口算法提供高性能请求频率控制。
Stars: 1 | Forks: 0
# @chabdulwahab/flowcap
一个适用于 Node.js 的零依赖、框架无关的 HTTP 速率限制中间件。
[](https://www.npmjs.com/package/@chabdulwahab/flowcap)
[](https://www.npmjs.com/package/@chabdulwahab/flowcap)
[](https://www.npmjs.com/package/@chabdulwahab/flowcap)
[](#)
[](https://nodejs.org/)
[](https://opensource.org/licenses/MIT)
## 功能
- **框架无关：** 与 Express、Fastify、Koa 以及原生 Node.js HTTP 模块无缝集成。
- **零依赖：** 没有外部运行时依赖，最大程度降低安全风险并减小打包体积。
- **人类可读的时间窗口：** 使用直观的字符串（如 `'15m'`、`'30s'` 或 `'1h'`）来配置持续时间。
- **高性能：** 采用带有 O(1) 自动清理机制的内存滑动窗口算法。
- **内置预设：** 针对常见场景包含预配置的规则集（login、api、strict、loose）。
- **符合标准：** 遵循 RateLimit 标头的 IETF draft-8 标准。
- **一流的 TypeScript 支持：** 包含开箱即用的类型声明。
## 安装说明
```
npm install @chabdulwahab/flowcap
```
## 使用方法
### Express
```
const express = require('express');
const flowcap = require('@chabdulwahab/flowcap');
const app = express();
// Apply a global rate limit of 100 requests per minute
app.use(flowcap({ limit: 100, window: '1m' }));
```
### 内置预设
预设为常见用例提供了默认配置。这些设置可以被覆盖。
```
// Protect login route (5 req / 15m)
app.post('/login', flowcap.login());
// Standard API limit (100 req / 1m)
app.use('/api', flowcap.api());
// Strict limit for administrative routes (20 req / 1m)
app.post('/admin', flowcap.strict());
// Loose limit for public assets (500 req / 1m)
app.get('/public', flowcap.loose());
// Override a preset configuration
app.post('/login', flowcap.login({ limit: 3 }));
```
## 框架支持
### Fastify
```
const fastify = require('fastify')();
const flowcap = require('@chabdulwahab/flowcap');
fastify.use(flowcap());
```
### Koa
```
const Koa = require('koa');
const flowcap = require('@chabdulwahab/flowcap');
const app = new Koa();
app.use(async (ctx, next) => {
return new Promise((resolve) => {
flowcap()(ctx.req, ctx.res, () => resolve(next()));
});
});
```
## API 参考
### 配置选项
| 选项 | 类型 | 默认值 | 描述 |
| --- | --- | --- | --- |
| `limit` | `number` | `100` | 每个时间窗口允许的最大请求数。 |
| `window` | `string` | `number` | `'1m'` | 时间窗口持续时间。接受可读字符串（例如 `'15m'`、`'30s'`）或毫秒数。 |
| `keyBy` | `function` | `req => req.ip` | 提取发起请求的客户端的唯一标识符。 |
| `skip` | `function` | `null` | 返回 `true` 以无条件跳过速率限制。 |
| `onLimit` | `function` | `null` | HTTP 429 响应的自定义处理器：`(req, res, next)`。 |
| `legacyHeaders` | `boolean` | `true` | 在 IETF draft-8 标准之外，附加传统的 `X-RateLimit-*` 标头。 |
| `store` | `Store` | `Memory` | 自定义状态存储的实例。 |
### 高级配置
#### 自定义客户端识别
```
app.use(flowcap({
limit: 200,
window: '1h',
keyBy: (req) => req.headers['x-api-key'] || req.ip
}));
```
#### 条件跳过
```
app.use(flowcap({
limit: 100,
window: '1m',
skip: (req) => req.path === '/health'
}));
```
#### 自定义速率限制响应
```
app.use(flowcap({
limit: 50,
window: '30s',
onLimit: (req, res, next) => {
res.status(429).json({ error: 'Rate limit exceeded. Please try again later.' });
}
}));
```
### 自定义存储实现
对于分布式环境（例如 Redis），请实现 `FlowcapStore` 接口并将该实例传递给 `options.store`。
```
interface FlowcapStore {
count(key: string, windowMs: number): number;
add(key: string, windowMs: number): void;
resetTime(key: string, windowMs: number): number;
}
```
## 资源
* **深度解析 / 文章：** 阅读 [dev.to](https://dev.to/chabdulwahhab310/why-i-stopped-writing-15-60-1000-in-every-project-4gb) 上的详细文章，了解 Flowcap 背后的设计决策和实现细节。
## 许可证
MIT标签：Express, Fastify, GNU通用公共许可证, Koa, MITM代理, Node.js, Syscall, Web开发, 中间件, 自定义脚本, 限流