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

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

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

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

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

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

- 包体积（解压后）：83.8 kB，40 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：3 个
- 首次发布：2025-03-13T08:16:08.236Z
- 最新版本发布：2026-10-06T14:30:08.471Z
- 近 30 天下载量：14700（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 11 个）

## 中文简介

使用 JSON Schemas 验证事件和响应的工具

## 安装

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

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

## README

# AWS Lambda (TypeScript) - 验证工具

这个工具为事件和响应提供了JSON Schema验证,包括JMESPath在验证前对已解围事件的支持.

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

要启动, 请通过运行安装软件包 :

```sh
npm i @aws-lambda-powertools/validation
```

## 特征

您可以使用下列设备验证出入境有效载荷: `@validator` 类方法装饰器或 `validator` Middy.j的中间软件.

也可以单独使用 `validate` 函数,如果您想要对验证过程进行更多的控制,例如处理验证错误.

### 校验器装饰器

这个 `@validator` 装饰器是TypeScript类方法的装饰器,可以用来验证来袭事件和应答有效载荷.

如果验证失败,我们会扔一个 `SchemaValidationError`。 。 。 .

```typescript
import { validator } from '@aws-lambda-powertools/validation/decorator';
import type { Context } from 'aws-lambda';

const inboundSchema = {
  type: 'object',
  properties: {
    value: { type: 'number' },
  },
  required: ['value'],
  additionalProperties: false,
};

const outboundSchema = {
  type: 'object',
  properties: {
    result: { type: 'number' },
  },
  required: ['result'],
  additionalProperties: false,
};

class Lambda {
  @validator({
    inboundSchema,
    outboundSchema,
  })
  async handler(event: { value: number }, _context: Context) {
    // Your handler logic here
    return { result: event.value * 2 };
  }
}

const lambda = new Lambda();
export const handler = lambda.handler.bind(lambda);
```

进出有效载荷的验证并非强制性的. 你可以使用一个,另一个,或者两者兼有.

### 验证器中间软件

如果你在使用Middy.js, 你可以改用 `validator` 用于验证即将到来的事件和反应有效载荷的中间软件.

```typescript
import { validator } from '@aws-lambda-powertools/validation/middleware';
import middy from '@middy/core';

const inboundSchema = {
  type: 'object',
  properties: {
    foo: { type: 'string' },
  },
  required: ['foo'],
  additionalProperties: false,
};

const outboundSchema = {
  type: 'object',
  properties: {
    bar: { type: 'number' },
  },
  required: ['bar'],
  additionalProperties: false,
};

export const handler = middy()
  .use(validation({ inboundSchema, outboundSchema }))
  .handler(async (event) => {
    // Your handler logic here
    return { bar: 42 };
  });
```

喜欢 `@validator` 装饰者,可以选择只验证出入境有效载荷.

### 独立验证函数

这个 `validate` 函数赋予您对验证过程的更多控制,通常在 Lambda 处理器内部使用,或者其他需要验证数据的函数.

在使用独立函数时, 您可以通过抓取来优雅地处理计划验证错误 `SchemaValidationError` 错误.

```typescript
import { validate } from '@aws-lambda-powertools/validation';
import { SchemaValidationError } from '@aws-lambda-powertools/validation/errors';

const schema = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    age: { type: 'number' },
  },
  required: ['name', 'age'],
  additionalProperties: false,
} as const;

const payload = { name: 'John', age: 30 };

export const handler = async (event: unknown) => {
  try {
    const validatedData = validate({
      payload,
      schema,
    });

    // Your handler logic here
  } catch (error) {
    if (error instanceof SchemaValidationError) {
      // Handle the validation error
      return {
        statusCode: 400,
        body: JSON.stringify({ message: error.message }),
      };
    }
    // Handle other errors
    throw error;
  }
}
```

### JMESPath 支持

在某些情况下,你可能只想要验证事件有效载荷的一部分——这就是: `envelope` 选项.

您可以使用 JMESPath 表达式指定要验证的属性的路径 。 校验器将在校验前解开此事件 .

```typescript
import { validate } from '@aws-lambda-powertools/validation';

const schema = {
  type: 'object',
  properties: {
    user: { type: 'string' },
  },
  required: ['user'],
  additionalProperties: false,
} as const;

const payload = {
  data: {
    user: 'Alice',
  },
};

const validatedData = validate({
  payload,
  schema,
  envelope: 'data',
});
```

### 扩展验证符

由于验证器是建立在 [亚日弗](https://ajv.js.org/),您可以用自定义格式和外部计划来扩展它,并带回自己的 `ajv` 举个例子.

下面的例子说明如何将额外选项传递到 `validate` 函数,但您也可以将其传递给 `@validator` 装饰和 `validator` 中间软件.

```typescript
import { validate } from '@aws-lambda-powertools/validation';

const formats = {
  ageRange: (value: number) => return value >= 0 && value <= 120,
};

const definitionSchema = {
  $id: 'https://example.com/schemas/definitions.json',
  definitions: {
    user: {
      type: 'object',
      properties: {
        name: { type: 'string' },
        age: { type: 'number', format: 'ageRange' },
      },
      required: ['name', 'age'],
      additionalProperties: false,
    }
  }
} as const;

const schema = {
  $id: 'https://example.com/schemas/user.json',
  type: 'object',
  properties: {
    user: { $ref: 'definitions.json#/definitions/user' },
  },
  required: ['user'],
  additionalProperties: false,
} as const;

const payload = {
  user: {
    name: 'Alice',
    age: 25,
  },
};

const validatedData = validate({
  payload,
  schema,
  externalRefs: [definitionSchema],
  formats,
});
```

欲了解如何使用 `validate` 函数,请参见 [文档](https://docs.aws.amazon.com/powertools/typescript/latest/features/validation)。 。 。 .

## 贡献

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

使用 JSON Schemas 验证事件和响应的工具

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

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

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

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

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

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

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

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

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

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

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

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