# @convex-dev/ratelimiter 中文文档

规范地址：https://npmcn.com/package/%40convex-dev/ratelimiter/

版本：0\.1\.7
npm 元数据更新时间：2026-10-07T00:51:45.868Z
中文译文更新时间：2026-11-10T18:16:05.705Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40convex-dev/ratelimiter
原文对照：https://npmcn.com/package/%40convex-dev/ratelimiter/?lang=original
项目主页：https://github.com/get-convex/ratelimiter#readme
源码仓库：https://github.com/get-convex/ratelimiter

弃用说明：Package has been renamed to @convex-dev/rate-limiter

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：198 kB，83 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：convex ~1\.16\.5 \|\| ~1\.17\.0
- 首次发布：2024-09-20T23:00:58.361Z
- 最新版本发布：2024-10-17T00:37:06.563Z
- 近 30 天下载量：4805（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：8（近 12 个月 0 个）

## 中文简介

Convex 的限速器组件 。 定义并使用应用层率限制. 类型安全,交易性,公平性,安全性,可塑性硬化到规模.

## 安装

```sh
npm install @convex-dev/ratelimiter
```

也可以使用：`pnpm add @convex-dev/ratelimiter`、`yarn add @convex-dev/ratelimiter`、`bun add @convex-dev/ratelimiter`

## README

# Convex 限速器组件

[![npm version](https://badge.fury.io/js/@convex-dev%2Fratelimiter.svg)](https://badge.fury.io/js/@convex-dev%2Fratelimiter)

**注: Convex 组件目前在β中**

应用级别税率限制.

-   类型安全
-   用于固定窗口或符号桶算法的配置
-   高效存储和计算
-   可伸缩性可配置硬化
-   交易评价
-   通过信用"保留"获得公平性担保
-   通过“token buckle”配置的“滚动”或“burst”津贴
-   失败已关闭, 不打开

定义:

```ts
const rateLimiter = new RateLimiter(components.ratelimiter, {
  // One global / singleton rate limit, using a "fixed window" algorithm.
  freeTrialSignUp: { kind: "fixed window", rate: 100, period: HOUR },
  // A per-user limit, allowing one every ~6 seconds.
  // Allows up to 3 in quick succession if they haven't sent many recently.
  sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
  failedLogins: { kind: "token bucket", rate: 10, period: HOUR },
  // Use sharding to increase throughput without compromising on correctness.
  llmTokens: { kind: "token bucket", rate: 40000, period: MINUTE, shards: 100 },
  llmRequests: { kind: "fixed window", rate: 3, period: MINUTE },
});
```

用法 :

```ts
// Restrict how fast free users can sign up to deter bots
const status = await rateLimiter.limit(ctx, "freeTrialSignUp");

// Limit how fast a user can send messages
const status = await rateLimiter.limit(ctx, "sendMessage", { key: userId });

// Automatically throw an error if the rate limit is hit
await rateLimiter.limit(ctx, "failedLogins", { key: userId, throws: true });

// Consume multiple in one request to prevent rate limits on an LLM API.
const status = await rateLimiter.limit(ctx, "llmTokens", { count: tokens });

// Reserve future capacity instead of just failing now
if (!args.skipCheck) {
  const status = await rateLimiter.limit(ctx, "llmRequests", { reserve: true });
  if (status.retryAfter) {
    return ctx.scheduler.runAfter(status.retryAfter, internal.foo.bar, {
      skipCheck: true,
    });
  }
}

// Check a rate limit without consuming it
const status = await rateLimiter.check(ctx, "failedLogins", { key: userId });

// Reset a rate limit on successful login
await rateLimiter.reset(ctx, "failedLogins", { key: userId });

// Use a one-off rate limit config (when not named on initialization)
const config = { kind: "fixed window", rate: 1, period: SECOND };
await rateLimiter.limit(ctx, "oneOffName", { config, throws: true });
```

见 [本条](https://stack.convex.dev/rate-limiting) 更多信息.

## 预先要求: Convex

你需要一个现有的 Convex 项目来使用组件. Convex是一个主机后端平台,包括数据库,无服务器功能, 还要多学一吨 [这里](https://docs.convex.dev/get-started)。 。 。 .

运行 `npm create convex` 或遵循其中任何一条 [快速启动](https://docs.convex.dev/home) 来设置一个.

## 安装

安装组件包 :

```ts
npm install @convex-dev/ratelimiter
```

创建一个 `convex.config.ts` 应用程序中的文件 `convex/` 通过调用文件夹并安装组件 `use`数字 :

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import ratelimiter from "@convex-dev/ratelimiter/convex.config";

const app = defineApp();
app.use(ratelimiter);

export default app;
```

## 使用量

定义利率限制 :

```ts
import { RateLimiter } from "@convex-dev/ratelimiter";
import { components } from "./_generated/api";

const rateLimiter = new RateLimiter(components.ratelimiter, {
  // One global / singleton rate limit
  freeTrialSignUp: { kind: "fixed window", rate: 100, period: HOUR },
  sendMessage: { kind: "token bucket", rate: 10, period: MINUTE, capacity: 3 },
});
```

-   如果您想要定义不同的 不同地点的费率.

使用从突变或动作:

```ts
const { ok, retryAfter } = await rateLimiter.limit(ctx, "freeTrialSignUp");
```

或者如果您想要根据密钥进行评分限制 :

```ts
await rateLimiter.limit(ctx, "sendMessage", { key: user._id, throws: true });
```

此调用也会发出例外,所以不需要检查返回值.

[看看这里的完整例子](https://npmcn.com/package/%40convex-dev/ratelimiter/example/convex/example.ts)。 。 。 .

见 [本条](https://stack.convex.dev/rate-limiting) 更多信息 关于使用和先进模式.

## 常见问题

### @convex-dev/ratelimiter 是什么？

Convex 的限速器组件 。 定义并使用应用层率限制\. 类型安全,交易性,公平性,安全性,可塑性硬化到规模\.注意：该包已被作者标记为弃用——Package has been renamed to @convex-dev/rate-limiter

### 如何安装 @convex-dev/ratelimiter？

在项目目录运行 npm install @convex-dev/ratelimiter，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：convex（~1\.16\.5 \|\| ~1\.17\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @convex-dev/ratelimiter 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @convex-dev/ratelimiter 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @convex-dev/ratelimiter 可以商用吗？

@convex-dev/ratelimiter 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @convex-dev/ratelimiter 的下载量有多少？

根据 npm 官方下载统计，@convex-dev/ratelimiter 在 2026/10/11 – 2026/11/09 这 30 天内被下载 4,805 次，日均约 160 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @convex-dev/ratelimiter 还在维护吗？

最新版本 0\.1\.7 发布于 2024/10/17（2 年前）；至今共发布 8 个版本，其中过去 12 个月发布了 0 个；首次发布于 2024/09/21。作者已将其标记为弃用，新项目建议寻找替代方案。