# @aws-lambda-powertools/idempotency 中文文档

规范地址：https://npmcn.com/package/%40aws-lambda-powertools/idempotency/

版本：2\.36\.0
npm 元数据更新时间：2026-10-06T14:28:47.825Z
中文译文更新时间：2026-11-07T09:36:50.313Z
软件包许可：MIT-0

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

原始 npm 页面：https://www.npmjs.com/package/%40aws-lambda-powertools/idempotency
原文对照：https://npmcn.com/package/%40aws-lambda-powertools/idempotency/?lang=original
项目主页：https://github.com/aws-powertools/powertools-lambda-typescript/tree/main/packages/idempotency#readme
源码仓库：https://github.com/aws-powertools/powertools-lambda-typescript

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

- 包体积（解压后）：338 kB，124 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：2 个
- peer 依赖：@middy/core 4\.x \|\| 5\.x \|\| 6\.x \|\| 7\.x，@redis/client ^6\.3\.0，@valkey/valkey-glide ^2\.5\.3，@aws-sdk/lib-dynamodb \>=3\.x，@aws-sdk/client-dynamodb \>=3\.x
- 首次发布：2023-07-11T14:13:15.661Z
- 最新版本发布：2026-10-06T14:28:47.370Z
- 近 30 天下载量：483209（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：69（近 12 个月 11 个）

## 中文简介

AWS Lambda (TypeScript) 库的Powertools的同能软件包. 它提供选项 使您的 Lambda 函数具有像样的能力 并且安全地重试.

## 安装

```sh
npm install @aws-lambda-powertools/idempotency
```

也可以使用：`pnpm add @aws-lambda-powertools/idempotency`、`yarn add @aws-lambda-powertools/idempotency`、`bun add @aws-lambda-powertools/idempotency`

## README

# AWS Lambda (TypeScript) 的功用工具——同上, 效率

用于 AWS Lambda (TypeScript) 的 Powertool 是用于执行的开发者工具包 无服务器 [最佳做法和增加开发者的速度](https://docs.aws.amazon.com/powertools/typescript/latest/#features)。 。 。 .

您可以在 TypeScript 和 JavaScript 代码基础中使用软件包.

-   [介绍](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-intro)
-   [使用量](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-usage)
    -   [函数包](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-function-wrapper)
    -   [装饰](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-decorator)
    -   [中间软件](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-middy-middleware)
    -   [DynamoDB 持久性层](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-dynamodb-persistence-layer)
-   [贡献](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-contribute)
-   [路线图](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-roadmap)
-   [连接](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-connect)
-   [如何支持 AWS Lambda (TypeScript) 的 Powertools ?](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-how-to-support-powertools-for-aws-lambda-typescript)
    -   [成为参考客户](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-becoming-a-reference-customer)
    -   [分享你的工作](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-sharing-your-work)
    -   [使用 Lambda 层](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-using-lambda-layer)
-   [许可证](https://npmcn.com/package/%40aws-lambda-powertools/idempotency/#readme-license)

## 介绍

此套件为您 Lambda 函数中执行 idepotency 提供了一个工具 . 你可以用它来包裹一个函数, 装饰一个方法, 或者做为Middy 中间软件来制作您的 AWS Lambda 处理器 一相能发.

当前实施为亚马逊DynamoDB提供了一个持久层,提供各种配置 选项。 通过扩展 `BasePersistenceLayer` 课.

## 使用量

要启动, 请通过运行安装库 :

```sh
npm i @aws-lambda-powertools/idempotency @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb
```

接下来,检查您 AWS Lambda 函数的 IAM 权限,并确保您允许 页:1 [详细行动](https://docs.aws.amazon.com/powertools/typescript/latest/features/idempotency/#iam-permissions) 在工具文档中.

### 函数包

通过使用 `makeIdempotent` 高档 函数.

这个 `makeIdempotent` 函数将引用函数作为第一个参数,并引用对象 作为第二个参数的选项.

当您包装您的 Lambda 处理器函数时, 工具会使用其中的内容 `event` 处理 一能通论.

```ts
import {makeIdempotent} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';

``
const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const myHandler = async (
  event: APIGatewayProxyEvent,
  _context: Context
): Promise<void> => {
  // your code goes here here
};

export const handler = makeIdempotent(myHandler, {
  persistenceStore,
});  
```

你也可以使用这个 `makeIdempotent` 函数可以包入任何其他任意函数,而不仅仅是Lambda处理器.

```ts
import {makeIdempotent} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, SQSEvent, SQSRecord} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const processingFunction = async (payload: SQSRecord): Promise<void> => {
  // your code goes here here
};

const processIdempotently = makeIdempotent(processingFunction, {
  persistenceStore,
});

export const handler = async (
  event: SQSEvent,
  _context: Context
): Promise<void> => {
  for (const record of event.Records) {
    await processIdempotently(record);
  }
};
```

如果您函数有多个参数, 您可以使用 `dataIndexArgument` 选项以指定哪个参数 用作一能键.

```ts
import {makeIdempotent} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, SQSEvent, SQSRecord} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const processingFunction = async (payload: SQSRecord, customerId: string): Promise<void> => {
  // your code goes here here
};

const processIdempotently = makeIdempotent(processingFunction, {
  persistenceStore,
  // this tells the utility to use the second argument (`customerId`) as the idempotency key
  dataIndexArgument: 1,
});

export const handler = async (
  event: SQSEvent,
  _context: Context
): Promise<void> => {
  for (const record of event.Records) {
    await processIdempotently(record, 'customer-123');
  }
};
```

注意您还可以在 Idepotency 配置对象中指定 JMESPath 表达式来选择事件的子集 有效载荷作为一能键。 这在处理载有时间戳或请求识别码的有效载荷时是有用的.

```ts
import {makeIdempotent, IdempotencyConfig} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
    tableName: 'idempotencyTableName',
});

const myHandler = async (
  event: APIGatewayProxyEvent,
  _context: Context
): Promise<void> => {
  // your code goes here here
};

export const handler = makeIdempotent(myHandler, {
  persistenceStore,
  config: new IdempotencyConfig({
    eventKeyJmespath: 'requestContext.identity.user',
  }),
});
```

此外,您还可以使用其中的一种 页:1 [JMESPath 内置函数](https://docs.aws.amazon.com/powertools/typescript/latest/features/jmespath/#built-in-jmespath-functions) 喜欢 `powertools_json()` 以解码键并使用部分有效载荷作为一能键.

```ts
import {makeIdempotent, IdempotencyConfig} from '@aws-lambda-powertools/idempotency';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

const myHandler = async (
  event: APIGatewayProxyEvent,
  _context: Context
): Promise<void> => {
  // your code goes here here
};

export const handler = makeIdempotent(myHandler, {
  persistenceStore,
  config: new IdempotencyConfig({
    eventKeyJmespath: 'powertools_json(body).["user", "productId"]',
  }),
});
```

检查 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/idempotency/) 需要更多的实例.

### 装饰

你可以使任何功能具有二元性, 并且可以安全地重试, 通过装饰它使用 `@idempotent` 装饰师.

```ts
import {idempotent} from '@aws-lambda-powertools/idempotency';
import {LambdaInterface} from '@aws-lambda-powertools/commons';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

class MyHandler extends LambdaInterface {
  @idempotent({persistenceStore: dynamoDBPersistenceLayer})
  public async handler(
    event: APIGatewayProxyEvent,
    context: Context
  ): Promise<void> {
    // your code goes here here
  }
}

const handlerClass = new MyHandler();
export const handler = handlerClass.handler.bind(handlerClass);
```

使用同一种装饰器,也可以使任何其他任意方法的一能.

```ts
import {idempotent} from '@aws-lambda-powertools/idempotency';
import {LambdaInterface} from '@aws-lambda-powertools/commons';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import type {Context} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});

class MyHandler extends LambdaInterface {

  public async handler(
    event: unknown,
    context: Context
  ): Promise<void> {
    for (const record of event.Records) {
      await this.processIdempotently(record);
    }
  }

  @idempotent({persistenceStore: dynamoDBPersistenceLayer})
  private async process(record: unknown): Promise<void> {
    // process each code idempotently
  }
}

const handlerClass = new MyHandler();
export const handler = handlerClass.handler.bind(handlerClass);
```

装饰器配置选项与其中的选项相同 `makeIdempotent` 函数。 检查 页:1 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/idempotency/) 需要更多的实例.

### 中间软件

如果你用Middy,你可以用这个 `makeHandlerIdempotent` 中间软件。 当使用中间软件时,你的Lambda 处理者成为一能者.

默认情况下,《同上》的效用将使用全部事件有效载荷来创建散列并确定请求是否 一能相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相取相相相取相相相取相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相相. 当处理更复杂的有效载荷时,有效载荷的部件总是会改变,你应该使用 页:1 `IdempotencyConfig` 对象指示该工具只使用您的有效载荷的一部分。 当 处理载有时间戳或请求识别码的有效载荷.

```ts
import {IdempotencyConfig} from '@aws-lambda-powertools/idempotency';
import {makeHandlerIdempotent} from '@aws-lambda-powertools/idempotency/middleware';
import {DynamoDBPersistenceLayer} from '@aws-lambda-powertools/idempotency/dynamodb';
import middy from '@middy/core';
import type {Context, APIGatewayProxyEvent} from 'aws-lambda';

const persistenceStore = new DynamoDBPersistenceLayer({
  tableName: 'idempotencyTableName',
});
const config = new IdempotencyConfig({
  hashFunction: 'md5',
  useLocalCache: false,
  expiresAfterSeconds: 3600,
  throwOnNoIdempotencyKey: false,
  eventKeyJmesPath: 'headers.idempotency-key',
});

export const handler = middy(
  async (_event: APIGatewayProxyEvent, _context: Context): Promise<void> => {
    // your code goes here here
  }
).use(
  makeHandlerIdempotent({
    config,
    persistenceStore,
  })
);
```

检查 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/idempotency/) 需要更多的实例.

### DynamoDB 持久性层

您可以使用 DynamoDB 表来存储一能信息 。 这使得你能够追踪散列键, 有效载荷 进展状态 过期 以及更多.

您可以自定义表格的大部分配置选项,即属性的名称. 见 页:1 [API 文档](https://docs.aws.amazon.com/powertools/typescript/latest/api/types/_aws-lambda-powertools_idempotency.types.DynamoDBPersistenceOptions.html) 更多细节.

## 贡献

如果你有兴趣为这个项目捐款,请参见我们 [贡献准则](https://github.com/aws-powertools/powertools-lambda-typescript/blob/main/CONTRIBUTING.md)。 。 。 .

## 路线图

AWS Lambda(英语:TypeScript)的"Powertools"行进图受顾客需求所驱动.  
帮助我们确定未来功能或公用事业的优先次序 [更新现有 RFC 和功能请求](https://github.com/aws-powertools/powertools-lambda-typescript/issues),或 [创建新的](https://github.com/aws-powertools/powertools-lambda-typescript/issues/new/choose),在此 GitHub 仓库中.

## 连接

-   **关于 GitHub 讨论的 AWS Lambda 工具**数字 : [加入对话](https://github.com/aws-powertools/powertools-lambda-typescript/discussions)
-   **电子邮件**数字 : [aws-lambda-powertools- feedback@amazon.com 互联网档案馆的存檔,存档日期2014-12-21](mailto:aws-lambda-powertools-feedback@amazon.com)

## 如何支持 AWS Lambda (TypeScript) 的 Powertools ?

### 成为参考客户

了解哪些公司正在使用这个图书馆对于帮助在内部确定项目的优先次序很重要。 如果你的同伴们 正在对 AWS Lambda (TypeScript) 使用 Powertools , 您可以请求将您的姓名和标志添加到 README 文件 提高a [AWS Lambda( TypeScript) 的辅助电源工具(成为参考)](https://s12d.com/become-reference-pt-ts) 问题.

除其他外,下列公司使用Powertools:

-   [Alma 媒体](https://www.almamedia.fi/)
-   [应用自己](https://appyourself.net/)
-   [贝利·纳尔逊](https://www.baileynelson.com.au/)
-   [Banx 软件](https://www.banxware.com/)
-   [凯伦特](https://caylent.com/)
-   [可认证](https://www.certible.com/)
-   [代码](https://www.codeac.io/)
-   [EF 教育第一](https://www.ef.com/)
-   [埃尔瓦](https://elva-group.com/)
-   [飞行重量](https://flyweight.io/)
-   [欺诈](https://fraudfalcon.app/)
-   [全球数据网](https://globaldatanet.com/)
-   [关节](https://guild.com/)
-   [半径](https://hashnode.com/)
-   [内向](https://instil.co/)
-   [本地软件包](https://localstack.cloud/)
-   [我们的隐私](https://oursprivacy.com/)
-   [完美邮递](https://www.perfectpost.fr/)
-   [传感器](https://sennder.com/)
-   [铁丝网股份有限公司](https://www.tecracer.com/)
-   [绊脚石10](https://www.trek10.com/)
-   [学校](https://www.weschool.com/)

### 分享你的工作

分享您为 AWS Lambda (TypeScript) 所做的 Powertools 。 看看社区有什么 [已经共享](https://docs.aws.amazon.com/powertools/typescript/latest/we_made_this) 关于AWS Lambda的Powertools (TypeScript).

### 使用 Lambda 层

这帮助我们了解谁用Powertools为AWS Lambda(英语:TypeScript (TypeScript))以非侵入性的方式使用Powertools,并帮助我们获得未来对其他AWS Lambda语言的Powertool的投资. 何时 [使用图层](https://docs.aws.amazon.com/powertools/typescript/latest/getting-started/lambda-layers/),您可以添加Powertools作为dev的依赖性,以不影响开发过程.

## 许可证

这个图书馆根据MIT-0许可证获得许可. 见LICENSE文件.

## 常见问题

### @aws-lambda-powertools/idempotency 是什么？

AWS Lambda \(TypeScript\) 库的Powertools的同能软件包\. 它提供选项 使您的 Lambda 函数具有像样的能力 并且安全地重试\.

### 如何安装 @aws-lambda-powertools/idempotency？

在项目目录运行 npm install @aws-lambda-powertools/idempotency，或使用 pnpm add / yarn add / bun add。

### @aws-lambda-powertools/idempotency 支持 TypeScript 吗？

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

### @aws-lambda-powertools/idempotency 支持 ESM 还是 CommonJS？

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

### @aws-lambda-powertools/idempotency 可以商用吗？

@aws-lambda-powertools/idempotency 使用 MIT-0 许可。声明的许可为 MIT-0，请阅读许可原文确认使用条件。以上为概括，不构成法律意见，请以许可原文为准。

### @aws-lambda-powertools/idempotency 的下载量有多少？

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

### @aws-lambda-powertools/idempotency 还在维护吗？

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