# @bernierllc/retry-policy 中文文档

规范地址：https://npmcn.com/package/%40bernierllc/retry-policy/

版本：0\.7\.0
npm 元数据更新时间：2026-05-20T04:08:43.905Z
中文译文更新时间：2026-11-07T23:13:42.667Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40bernierllc/retry-policy
原文对照：https://npmcn.com/package/%40bernierllc/retry-policy/?lang=original
项目主页：https://github.com/bernier-llc/tools#readme
源码仓库：https://github.com/bernier-llc/tools

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

- 包体积（解压后）：71.1 kB，23 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：p-retry ^5\.0\.0
- 首次发布：2025-07-28T03:15:55.757Z
- 最新版本发布：2026-05-20T04:08:43.734Z
- 近 30 天下载量：2481（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：10（近 12 个月 8 个）

## 中文简介

原子复试政策公用设施,具有指数反弹和焦虑

## 安装

```sh
npm install @bernierllc/retry-policy
```

也可以使用：`pnpm add @bernierllc/retry-policy`、`yarn add @bernierllc/retry-policy`、`bun add @bernierllc/retry-policy`

## README

# @bernierllc/retry-policy (英语)

原子重试政策公用设施,提供指数后退和紧张的支持.

## 概览

`@bernierllc/retry-policy` 提供原子能设施,以实施可配置的后退策略和紧张的再试验逻辑。 这个包被设计成一个核心构件,可以被更高级别的再试管理者和服务使用.

## 特征

-   **多个后退战略**: 指数、线性、和常数后退
-   **可配置的抖动**: 完全, 平等, 装饰相关, 并且没有焦虑选项
-   **自定义重试条件**: 灵活错误评价逻辑
-   **类型安全 API**: 完整类型脚本支持并严格打字
-   **零依赖关系**: 没有外部依赖性的纯函数
-   **综合测试**: 95+q测试覆盖率

## 安装

```bash
npm install @bernierllc/retry-policy
```

## 快速启动

```typescript
import { RetryPolicy, createRetryPolicy } from '@bernierllc/retry-policy';

// Create a retry policy with default settings
const policy = new RetryPolicy();

// Evaluate if an operation should be retried
const result = policy.evaluateRetry(1, new Error('Network error'));
console.log(result);
// {
//   shouldRetry: true,
//   delay: 2000,
//   attempt: 1,
//   isFinalAttempt: false
// }
```

## API 参考

### 重试策略类

管理再试政策的主要班级.

#### 构造器

```typescript
new RetryPolicy(options?: Partial<RetryPolicyOptions>, backoffConfig?: Partial<BackoffConfig>)
```

#### 方法

-   `evaluateRetry(attempt: number, error: any): RetryPolicyResult`
-   `calculateDelay(attempt: number): number`
-   `getOptions(): Required<RetryPolicyOptions>`
-   `getBackoffConfig(): BackoffConfig`
-   `updateOptions(options: Partial<RetryPolicyOptions>): void`
-   `updateBackoffConfig(config: Partial<BackoffConfig>): void`

### 工具函数

-   `createRetryPolicy(options?, backoffConfig?): RetryPolicy`
-   `calculateRetryDelay(attempt, options?, backoffConfig?): number`
-   `shouldRetry(attempt, error, options?): boolean`

## 用法实例

### 基本用途

```typescript
import { RetryPolicy } from '@bernierllc/retry-policy';

const policy = new RetryPolicy({
  maxRetries: 3,
  initialDelayMs: 1000,
  shouldRetry: (error) => error.code === 'NETWORK_ERROR'
});

// In your retry loop
for (let attempt = 0; attempt <= 3; attempt++) {
  try {
    const result = await someOperation();
    break; // Success, exit retry loop
  } catch (error) {
    const retryResult = policy.evaluateRetry(attempt, error);
    
    if (!retryResult.shouldRetry) {
      throw error; // Don't retry, re-throw error
    }
    
    // Wait before next attempt
    await new Promise(resolve => setTimeout(resolve, retryResult.delay));
  }
}
```

### 自定义后退策略

```typescript
import { RetryPolicy } from '@bernierllc/retry-policy';

const policy = new RetryPolicy(
  { maxRetries: 5 },
  {
    type: 'exponential',
    baseDelay: 500,
    factor: 3,
    maxDelay: 10000,
    jitter: {
      type: 'full',
      factor: 0.1
    }
  }
);

// This will use exponential backoff with full jitter
const delay = policy.calculateDelay(2); // ~4500ms with jitter
```

### 不同的后退类型

```typescript
import { RetryPolicy } from '@bernierllc/retry-policy';

// Exponential backoff (default)
const exponential = new RetryPolicy(undefined, {
  type: 'exponential',
  baseDelay: 1000,
  factor: 2
});
// Delays: 1000ms, 2000ms, 4000ms, 8000ms...

// Linear backoff
const linear = new RetryPolicy(undefined, {
  type: 'linear',
  baseDelay: 1000
});
// Delays: 1000ms, 2000ms, 3000ms, 4000ms...

// Constant backoff
const constant = new RetryPolicy(undefined, {
  type: 'constant',
  baseDelay: 1000
});
// Delays: 1000ms, 1000ms, 1000ms, 1000ms...
```

### 抖动类型

```typescript
import { RetryPolicy } from '@bernierllc/retry-policy';

// Full jitter: random value between 0 and delay
const fullJitter = new RetryPolicy(undefined, {
  jitter: { type: 'full', factor: 0.1 }
});

// Equal jitter: random value between delay/2 and delay
const equalJitter = new RetryPolicy(undefined, {
  jitter: { type: 'equal', factor: 0.1 }
});

// Decorrelated jitter: random value between delay and delay * 3
const decorrelatedJitter = new RetryPolicy(undefined, {
  jitter: { type: 'decorrelated', factor: 0.1 }
});

// No jitter: exact delay values
const noJitter = new RetryPolicy(undefined, {
  jitter: { type: 'none' }
});
```

### 自定义重试条件

```typescript
import { RetryPolicy } from '@bernierllc/retry-policy';

const policy = new RetryPolicy({
  maxRetries: 5,
  shouldRetry: (error) => {
    // Only retry on network errors or 5xx server errors
    if (error.code === 'NETWORK_ERROR') return true;
    if (error.status >= 500 && error.status < 600) return true;
    return false;
  },
  onRetry: (attempt, delay, error) => {
    console.log(`Retry attempt ${attempt} after ${delay}ms due to:`, error.message);
  },
  onFailure: (error) => {
    console.log('All retry attempts exhausted:', error.message);
  }
});
```

## 配置

### 重试政策选项

```typescript
interface RetryPolicyOptions {
  maxRetries: number;           // Maximum number of retry attempts
  initialDelayMs: number;       // Initial delay in milliseconds
  maxDelayMs?: number;          // Maximum delay in milliseconds
  backoffFactor?: number;       // Exponential backoff factor
  jitter?: boolean;             // Whether to apply jitter
  shouldRetry?: (error: any) => boolean;  // Custom retry condition
  onRetry?: (attempt: number, delay: number, error: any) => void;  // Retry callback
  onFailure?: (error: any) => void;  // Failure callback
}
```

### 后置配置

```typescript
interface BackoffConfig {
  type: 'exponential' | 'linear' | 'constant';  // Backoff strategy
  baseDelay: number;           // Base delay in milliseconds
  maxDelay: number;            // Maximum delay in milliseconds
  factor?: number;             // Backoff factor for exponential
  jitter?: JitterConfig;       // Jitter configuration
}
```

### 鼠标连接

```typescript
interface JitterConfig {
  type: 'none' | 'full' | 'equal' | 'decorrelated';  // Jitter type
  factor?: number;             // Jitter factor (0-1)
}
```

## 默认值

```typescript
const DEFAULT_RETRY_OPTIONS = {
  maxRetries: 5,
  initialDelayMs: 1000,
  maxDelayMs: 30000,
  backoffFactor: 2,
  jitter: true,
  shouldRetry: () => true,
  onRetry: () => {},
  onFailure: () => {}
};

const DEFAULT_BACKOFF_CONFIG = {
  type: 'exponential',
  baseDelay: 1000,
  maxDelay: 30000,
  factor: 2,
  jitter: { type: 'full', factor: 0.1 }
};
```

## 一体化状况

### 锁定集成

**状态**: 不适用

**理由说明**: 这是一个纯公用软件包,没有运行时状态,副作用,或错误条件需要记录. RetryPolicy类是无国籍的和决定性的——它只是根据尝试数和出错类型来计算重试延迟和后退策略. 所有错误都作为调用代码可以处理的结构化结果返回,没有从结构化日志中受益的背景操作,网络调用,或状态变化.

**图案**: 纯功能用法 - 不需要日志集成. 伐木是通过使用此重试策略的消耗包处理的.

### NeverHub 整合

**状态**: 不适用

**理由说明**: 这是一个核心工具包,提供重试策略计算. 它不参与服务发现、事件出版或网络业务。 复试政策计算是不需要服务注册或发现的无国籍公用事业业务. 使用此工具的服务级软件包在需要时可以与NeverHub集成.

**图案**: 核心用途 - 不需要服务网格集成. 使用此重试策略的服务级软件包在需要时可以与NeverHub集成.

### Docs- 成套集成软件

**状态**: 准备

**格式**:类型Doc相容的JSDoc评论在整个源代码中都包含. 所有公开的API都有实例和类型信息的记载.

## 警卫

此软件包具有零运行时间的依赖性,只使用纯TypeScript函数. 安全考虑:

-   **无外部依赖**: 所有重试逻辑都内部执行,运行时没有外部软件包
-   **类型安全**: 严格类型Script打字,防止常见运行时间出错
-   **无网络呼叫**: 没有I/O操作的纯计算函数
-   **无秘密存储**: 不处理或储存任何敏感数据
-   **审计干净**数字 : `npm audit` 无脆弱性(零依赖性)

对于安全问题,请在存储器中打开一个问题.

## 测试

```bash
# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch
```

## 捐款

这个套装遵循了伯尼公司有限责任公司的发展标准:

-   **类型脚本严格模式** - 所有代码都必须通过严格的类型检查
-   **综合测试** - 需要95分测试覆盖率
-   **文档** - 所有公共API必须记录在案
-   **代码样式** - 遵循工程ESLint配置

## 许可证

ISC 许可证 - 详情见LICENSE文件.

## 相关软件包

-   `@bernierllc/retry-state` - 重新研究国家管理和持久性
-   `@bernierllc/retry-metrics` - 重新测试业绩衡量标准
-   `@bernierllc/retry-manager` - 高级重试管弦乐服务

## 常见问题

### @bernierllc/retry-policy 是什么？

原子复试政策公用设施,具有指数反弹和焦虑

### 如何安装 @bernierllc/retry-policy？

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

### @bernierllc/retry-policy 支持 TypeScript 吗？

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

### @bernierllc/retry-policy 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @bernierllc/retry-policy 可以商用吗？

@bernierllc/retry-policy 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @bernierllc/retry-policy 的下载量有多少？

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

### @bernierllc/retry-policy 还在维护吗？

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