# @aws-lambda-powertools/event-handler 中文文档

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

版本：2\.36\.0
npm 元数据更新时间：2026-10-06T14:31:34.829Z
中文译文更新时间：2026-11-07T11:33:33.253Z
软件包许可：MIT-0

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

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

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

- 包体积（解压后）：818 kB，256 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：@standard-schema/spec ^1\.0\.0，@aws-lambda-powertools/tracer \>=2\.36\.0，@aws-lambda-powertools/metrics \>=2\.36\.0
- 首次发布：2025-04-21T17:47:24.892Z
- 最新版本发布：2026-10-06T14:31:34.434Z
- 近 30 天下载量：132663（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：28（近 12 个月 11 个）

## 中文简介

为API Gateway REST/HTTP API,ALB,Lambda函数URL以及AppSync减少锅炉板的轻量级路由.

## 安装

```sh
npm install @aws-lambda-powertools/event-handler
```

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

## README

# AWS Lambda (TypeScript) - 事件处理工具

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

您可以在 TypeScript 和 JavaScript 代码库中使用库.

## 介绍

Amazon API Gateway REST和HTTP API的事件处理器,应用程序负载平衡器(ALB),Lambda函数URL,AWS AppSync GraphQL API,以及AWS AppSync Eventies API.

## 使用量

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

```sh
npm i @aws-lambda-powertools/event-handler
```

## HTTP 密码

Amazon API Gateway REST和HTTP API,应用程序负载平衡器(ALB)和Lambda函数URL的事件处理器.

-   为API Gateway REST/HTTP API、 ALB 和 Lambda 函数 URL 减少锅炉板的轻型路由
-   基于Web 标准 - 收到的事件自动转换为 [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) 对象,您可以返回 [`Response`](https://developer.mozilla.org/en-US/docs/Web/API/Response) 来自您的处理器的对象
-   自动事件类型检测和响应格式转换, 这样您就可以将集成( 例如从 ALB 到 API Gateway) 互换, 很少到没有代码更改
-   用于请求/响应转换和验证的内置中间软件引擎
-   具有微函数(一条或几条路线)和单一函数的工程

### 处理 HTTP 请求

您可以使用相应的方法为特定的 HTTP 方法和路径注册处理器 `get()` 或者说 `post()`。当请求符合方法和路径时,将调用处理器.

```typescript
import { Router } from '@aws-lambda-powertools/event-handler/http';
import type { Context } from 'aws-lambda';

const app = new Router();

app.get('/todos', async () => {
  // your logic here
  return [
    {
      id: 'todo-id',
      title: 'Todo Title',
      completed: false,
    },
  ];
});

app.post('/todos', async ({ req }) => {
  const body = await req.json();
  // your logic here
  return body;
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);
```

### 动态路线

您可以在路径中使用动态路径参数,这些参数会自动解析并传递给您的处理器.

```typescript
import { Router } from '@aws-lambda-powertools/event-handler/http';
import type { Context } from 'aws-lambda';

const app = new Router();

app.get('/todos/:todoId', async ({ params: { todoId } }) => {
  // your logic here
  return {
    id: todoId,
    title: 'Todo Title',
    completed: false,
  };
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);
```

HTTP事件处理器还有更多内容,包括:

-   使用 [标准Schema](https://standardschema.dev/) zod, Valibot, 和 ArkType 等兼容的库
-   处理内置和自定义错误处理器出错,并输入 HTTP 错误
-   CORS、压缩和通过内置中间软件跟踪 AWS X-Ray
-   分割路由器以组织跨越多个文件的路由
-   响应流和二进制响应

见 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/event-handler/http) 用于了解如何使用 HTTP 事件处理器的更多细节.

## App同步事件

AWS AppSync 实时事件事件处理器.

-   以专用处理方法轻松处理发布和订阅事件
-   基于命名空间和频道模式的自动路由
-   支持通配符模式创建覆盖全处理器
-   分批处理的平行冕仪汇总处理活动
-   单个事件的重大错误处理

### 处理发布事件

在使用发布事件处理器时,可以注册特定通道或通配符模式的处理器. 该频道收到的每封邮件,都会呼叫处理器一次.

```typescript
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/default/foo', async (payload) => {
  // your logic here
  return payload;
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```

在某些情况下,您可能想要同时处理所有消息,例如优化下游操作. 在这种情况下,你可以设置 `aggregate` 选项到 `true` 登记处理器时。 这将使处理器对该频道收到的所有消息一次性呼叫.

```typescript
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onPublish('/default/foo', async (payloads) => {
  const newMessages = [];
  for (const message of payloads) {
    // your logic here
  }

  return newMessages;
}, {
  aggregate: true
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```

### 处理订阅事件

您也可以注册订阅事件的处理器。 在指定频道收到的每个订阅请求都会调用此处理器一次 。 您可以使用此处理器来进行任何必要的设置或验证, 然后再允许订阅继续 .

```typescript
import { AppSyncEventsResolver } from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onSubscribe('/default/foo', async (event) => {
  // your logic here
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```

如果您想要拒绝订阅请求, 您可以丢入 `UnauthorizedException` 错误。 这将导致订阅被拒绝,客户端将收到错误消息.

```typescript
import {
  AppSyncEventsResolver,
  UnauthorizedException,
} from '@aws-lambda-powertools/event-handler/appsync-events';

const app = new AppSyncEventsResolver();

app.onSubscribe('/default/foo', async (event) => {
  // your logic here
  throw new UnauthorizedException('Unauthorized');
});

export const handler = async (event, context) =>
  app.resolve(event, context);
```

见 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/event-handler/appsync-events) 关于如何使用 AppSync 事件处理器的更多细节.

## AppSync 图QL

AWS AppSync GraphQL APIs 的事件处理器允许您在 Lambda 函数中轻松处理 GraphQL 请求 。 它使您能够定义 GraphQL 类型和字段的解析器,使得无需复杂的 VTL 或 JavaScript 模板即可更容易地处理 GraphQL 请求.

-   基于 GraphQL 类型和字段密钥的路由事件
-   自动分析 API 参数到函数参数
-   处理图表QL 回复和预期格式的错误

### 处理查询请求

为查询类型注册解析器时,可以使用 `onQuery()` 方法。 此方法允许您定义一个在进行 GraphQL 查询时将引用的函数 .

```typescript
import { Logger } from '@aws-lambda-powertools/logger';
import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
import type { Context } from 'aws-lambda';

const logger = new Logger({
  serviceName: 'TodoManager',
});
const app = new AppSyncGraphQLResolver({ logger });

app.onQuery<{ id: string }>('getTodo', async ({ id }) => {
  logger.debug('Resolving todo', { id });
  // Simulate fetching a todo from a database or external service
  return {
    id,
    title: 'Todo Title',
    completed: false,
  };
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);
```

### 处理突变请求

同样,您也可以使用 `onMutation()` 方法。 此方法允许您定义一个函数, 当图形 QL 突变时将引用该函数 .

```typescript
import { Logger } from '@aws-lambda-powertools/logger';
import {
  AppSyncGraphQLResolver,
  makeId,
} from '@aws-lambda-powertools/event-handler/appsync-graphql';
import type { Context } from 'aws-lambda';

const logger = new Logger({
  serviceName: 'TodoManager',
});
const app = new AppSyncGraphQLResolver({ logger });

app.onMutation<{ title: string }>('createTodo', async ({ title }) => {
  logger.debug('Creating todo', { title });
  const todoId = makeId();
  // Simulate creating a todo in a database or external service
  return {
    id: todoId,
    title,
    completed: false,
  };
});

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);
```

### 通用解析器

当您想要对类型和字段有更多的控制时,您可以使用 `resolver()` 方法。 这种方法允许您注册特定 GraphQL 类型和字段的函数,包括自定义类型.

```typescript
import { Logger } from '@aws-lambda-powertools/logger';
import { AppSyncGraphQLResolver } from '@aws-lambda-powertools/event-handler/appsync-graphql';
import type { Context } from 'aws-lambda';

const logger = new Logger({
  serviceName: 'TodoManager',
});
const app = new AppSyncGraphQLResolver({ logger });

app.resolver(
  async () => {
    logger.debug('Resolving todos');
    // Simulate fetching a todo from a database or external service
    return [
      {
        id: 'todo-id',
        title: 'Todo Title',
        completed: false,
      },
      {
        id: 'todo-id-2',
        title: 'Todo Title 2',
        completed: true,
      },
    ];
  },
  {
    fieldName: 'listTodos',
    typeName: 'Query',
  }
);

export const handler = async (event: unknown, context: Context) =>
  app.resolve(event, context);
```

见 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/event-handler/appsync-graphql) 关于如何使用 AppSync GraphQL 事件处理器的更详细信息.

## 贡献

如果你有兴趣为这个项目捐款,请参见我们 [贡献准则](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 ?

### 成为参考客户

了解哪些公司正在使用这个图书馆对于帮助在内部确定项目的优先次序很重要。 如果您的公司正在使用 Powertools 为 AWS Lambda (TypeScript) , 您可以要求您在 README 文件中添加您的姓名和标志 [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/event-handler 是什么？

为API Gateway REST/HTTP API,ALB,Lambda函数URL以及AppSync减少锅炉板的轻量级路由\.

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

在项目目录运行 npm install @aws-lambda-powertools/event-handler，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@standard-schema/spec（^1\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

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

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

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

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

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

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

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

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

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

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