# @convex-dev/action-retrier 中文文档

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

版本：0\.3\.1
npm 元数据更新时间：2026-10-07T00:51:35.658Z
中文译文更新时间：2026-11-10T17:31:51.612Z
软件包许可：Apache-2\.0

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

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

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

- 包体积（解压后）：150 kB，59 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：convex ^1\.24\.8
- 首次发布：2024-09-20T15:50:47.982Z
- 最新版本发布：2026-06-25T00:07:04.183Z
- 近 30 天下载量：1218917（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 2 个）

## 中文简介

用于重试偶能动作的 Convex 组件 .

## 安装

```sh
npm install @convex-dev/action-retrier
```

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

## README

# Convex 动作检索器

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

动作有时会因网络错误、服务器重启或问题而失败 加上第3个政党API,经常可以重试. 行动检索器 组件使得这真的容易.

```ts
import { ActionRetrier } from "@convex-dev/action-retrier";
import { components } from "./convex/_generated/server";

const retrier = new ActionRetrier(components.actionRetrier);

// `retrier.run` will automatically retry your action up to four times before giving up.
await retrier.run(ctx, internal.module.myAction, { arg: 123 });
```

反射器组件将运行动作,并在失败时重试,与 指数后退, 直至动作成功或重复的最大次数 已经到达.

## 预先要求: Convex

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

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

## 安装

第一,添加 `@convex-dev/action-retrier` 作为国家预防机制的依赖:

```sh
npm install @convex-dev/action-retrier
```

然后,将组件安装到您的 Convex 工程中 `convex/convex.config.ts` 配置文件 :

```ts
// convex/convex.config.ts
import { defineApp } from "convex/server";
import actionRetrier from "@convex-dev/action-retrier/convex.config.js";

const app = defineApp();
app.use(actionRetrier);
export default app;
```

最后,创建一个新的 `ActionRetrier` 在您的 Convex 项目中, 并指示它 至已安装组件:

```ts
// convex/index.ts
import { ActionRetrier } from "@convex-dev/action-retrier";
import { components } from "./_generated/api";

export const retrier = new ActionRetrier(components.actionRetrier);
```

您可以在 `ActionRetrier` 建筑师.

```ts
const retrier = new ActionRetrier(components.actionRetrier, {
  initialBackoffMs: 10000,
  base: 10,
  maxFailures: 4,
});
```

-   `initialBackoffMs` 是重试前失败后的初始延迟 (默认:250).
-   `base` 是指数后退的基数( 默认: 2) .
-   `maxFailures` 是重试动作的最大次数( 默认 4) .

## API 密码

### 开始运行

在安装组件后,使用 `run` 从变异或 行动启动行动.

```ts
export const kickoffExampleAction = mutation({
  handler: async (ctx) => {
    const runId = await retrier.run(ctx, internal.index.exampleAction, {
      foo: "bar",
    });
    // ... optionally persist or pass along the runId
  },
});

export const exampleAction = internalAction({
  args: { foo: v.string() },
  handler: async (ctx, args) => {
    return operationThatMightFail(args);
  },
});
```

返回值为 `retrier.run` 不是行动的结果,而是 用于查询其状态或取消其状态的ID。 动作的返回值 当它成功时,随状态一起保存.

您可以在选项中选择指定对后退参数的覆盖 参数.

```ts
export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(
    ctx,
    internal.index.exampleAction,
    { failureRate: 0.8 },
    {
      initialBackoffMs: 125,
      base: 2.71,
      maxFailures: 3,
    },
  );
});
```

您可以指定一个 `onComplete` 选项参数中的突变回调 不错 这种突变可以保证最终精确运行一次.

```ts
// convex/index.ts

import { runResultValidator, runIdValidator } from "@convex-dev/action-retrier";

export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(
    ctx,
    internal.index.exampleAction,
    { failureRate: 0.8 },
    {
      onComplete: internal.index.exampleCallback,
    },
  );
});

export const exampleCallback = internalMutation({
  args: { id: runIdValidator, result: runResultValidator },
  handler: async (ctx, args) => {
    if (args.result.type === "success") {
      console.log(
        "Action succeeded with return value:",
        args.result.returnValue,
      );
    } else if (args.result.type === "failed") {
      console.log("Action failed with error:", args.result.error);
    } else if (args.result.type === "canceled") {
      console.log("Action was canceled.");
    }
  },
});
```

### 运行状态

这个 `run` 方法返回 a `RunId`,然后可用于查询运行的 状态.

```ts
export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(ctx, internal.index.exampleAction, {
    failureRate: 0.8,
  });
  while (true) {
    const status = await retrier.status(ctx, runId);
    if (status.type === "inProgress") {
      await new Promise((resolve) => setTimeout(resolve, 1000));
      continue;
    } else {
      console.log("Run completed with result:", status.result);
      break;
    }
  }
});
```

### 取消运行

您可以使用 `cancel` 方法.

```ts
export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(ctx, internal.index.exampleAction, {
    failureRate: 0.8,
  });
  await new Promise((resolve) => setTimeout(resolve, 1000));
  await retrier.cancel(ctx, runId);
});
```

正在执行的运行将被取消, 因此可能 仍在执行。 一个成功的呼吁 `cancel`不过 保证以后 `status` 电话将表示取消.

### 清理已完成的运行

运行占用了数据库中的空间,因为它们存储了返回值. 之后 运行完成后,您可立即使用 `retrier.cleanup(ctx, runId)`。系统将自动清理完成 7天后运行.

```ts
export const kickoffExampleAction = action(async (ctx) => {
  const runId = await retrier.run(ctx, internal.index.exampleAction, {
    failureRate: 0.8,
  });
  try {
    while (true) {
      const status = await retrier.status(ctx, runId);
      if (status.type === "inProgress") {
        await new Promise((resolve) => setTimeout(resolve, 1000));
        continue;
      } else {
        console.log("Run completed with result:", status.result);
        break;
      }
    }
  } finally {
    await retrier.cleanup(ctx, runId);
  }
});
```

## 日志

你可以设置 `ACTION_RETRIER_LOG_LEVEL` 改为 `DEBUG` 拥有回溯日志 更多的内部信息,然后你可以查看 Convex 仪表板.

```sh
npx convex env set ACTION_RETRIER_LOG_LEVEL DEBUG
```

默认日志级别为 `INFO`但你也可以设置它 `ERROR` 对偶数 木头少.

## 常见问题

### @convex-dev/action-retrier 是什么？

用于重试偶能动作的 Convex 组件 \.

### 如何安装 @convex-dev/action-retrier？

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

### @convex-dev/action-retrier 支持 TypeScript 吗？

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

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

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

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

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

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

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

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

最新版本 0\.3\.1 发布于 2026/06/25（4 个月前）；至今共发布 11 个版本，其中过去 12 个月发布了 2 个；首次发布于 2024/09/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。