Tescript 处理程序基础知识使用异步/等待使用回调将类型用于事件对象 Typescript Lambda 函数的代码最佳实践

定义采用 TypeScript 的 Lambda 函数处理程序

Lambda 函数处理程序是函数代码中处理事件的方法。当调用函数时，Lambda 运行处理程序方法。您的函数会一直运行，直到处理程序返回响应、退出或超时。

主题

Tescript 处理程序基础知识
使用异步/等待
使用回调
将类型用于事件对象
Typescript Lambda 函数的代码最佳实践

Tescript 处理程序基础知识

例 TypeScript 处理程序

此示例函数记录事件对象的内容并返回日志的位置。请注意以下几点：

在 Lambda 函数中使用此代码之前，必须添加 @types/aws-lambda 程序包作为开发依赖项。此程序包包含 Lambda 的类型定义。安装 @types/aws-lambda 时，import 语句 (import ... from 'aws-lambda') 会导入类型定义。它不导入 aws-lambda NPM 程序包，这是一个无关的第三方工具。有关更多信息，请参阅 DefinitelyTyped GitHub 存储库中的 aws-lambda。
本示例中的处理程序是 ES 模块，必须位于 package.json 文件中或使用 .mjs 文件扩展名进行指定。有关详细信息，请参阅将函数处理程序指定为 ES 模块。


import { Handler } from 'aws-lambda';

export const handler: Handler = async (event, context) => {
    console.log('EVENT: \n' + JSON.stringify(event, null, 2));
    return context.logStreamName;
};

运行时会将参数传递到处理程序方法。第一个参数是 event 对象，它包含来自调用方的信息。调用程序在调用 Invoke 时将该信息作为 JSON 格式字符串传递，运行时将它转换为对象。当 AWS 服务调用您的函数时，事件结构因服务而异。对于 TypeScript，建议对事件对象使用类型注释。有关更多信息，请参阅将类型用于事件对象。

第二个参数是 context 对象，它包含有关调用、函数和执行环境的信息。在前面的示例中，函数将从 context 对象获取日志流的名称，然后将其返回给调用方。

您也可以使用回调参数，这是一种可在非异步处理程序中进行调用以发送响应的函数。我们建议您使用 Async/await（异步/等待），而不使用 Callback（回调）。Async/await 具有更好的易读性、错误处理能力和效率。有关 Async/await 与 Callback 之间差异的更多信息，请参阅使用回调。

使用异步/等待

如果您的代码执行异步任务，则使用 Async/await 模式来确保处理程序会完成运行。Async/await 是一种简洁、易读的 Node.js 异步代码编写方式，无需嵌套回调或链式承诺。使用 Async/await 时，您编写的代码看起来与同步代码类似，同时仍然是异步和非阻止式的。

async 关键字会将函数标记为异步，await 关键字会暂停函数的执行，直到 Promise 完成解析为止。

例 TypeScript 函数 - 异步

此示例使用 fetch，它支持 nodejs18.x 运行时。请注意以下几点：

在 Lambda 函数中使用此代码之前，必须添加 @types/aws-lambda 程序包作为开发依赖项。此程序包包含 Lambda 的类型定义。安装 @types/aws-lambda 时，import 语句 (import ... from 'aws-lambda') 会导入类型定义。它不导入 aws-lambda NPM 程序包，这是一个无关的第三方工具。有关更多信息，请参阅 DefinitelyTyped GitHub 存储库中的 aws-lambda。
本示例中的处理程序是 ES 模块，必须位于 package.json 文件中或使用 .mjs 文件扩展名进行指定。有关详细信息，请参阅将函数处理程序指定为 ES 模块。


import { APIGatewayProxyEvent, APIGatewayProxyResult } from 'aws-lambda';
const url = 'https://aws.amazon.com/';
export const lambdaHandler = async (event: APIGatewayProxyEvent): Promise<APIGatewayProxyResult> => {
    try {
        // fetch is available with Node.js 18
        const res = await fetch(url);
        return {
            statusCode: res.status,
            body: JSON.stringify({
                message: await res.text(),
            }),
        };
    } catch (err) {
        console.log(err);
        return {
            statusCode: 500,
            body: JSON.stringify({
                message: 'some error happened',
            }),
        };
    }
};

使用回调

我们建议您使用 Async/await 来声明函数处理程序，而不是使用回调。Async/await 是更好的选择，原因有以下几点：

易读性：Async/await 代码比回调代码更易阅读和理解，回调代码很快就会变得难以理解，从而导致回调失败。
调试和错误处理：基于回调的代码可能非常难以调试。调用堆栈可能变得难以理解，并且很容易出现错误。使用 Async/await 时，您可以使用 try/catch 块来处理错误。
效率：回调通常需要在代码的不同部分之间切换。Async/await 可以减少上下文切换的数量，从而提高代码效率。

当您在处理程序中使用回调时，函数会一直执行，直到事件循环为空或函数超时为止。在完成所有事件循环任务之前，不会将响应发送给调用方。如果函数超时，则会返回 error。可以通过将 context.callbackWaitsForEmptyEventLoop 设置为 false，从而将运行时配置为立即发送响应。

callback 函数有两个参数：一个是 Error，一个是响应。响应对象必须与 JSON.stringify 兼容。

例包含回调的 TypeScript 函数

此示例函数接收来自 Amazon API Gateway 的事件、记录事件和上下文对象，然后向 API Gateway 返回响应。请注意以下几点：

在 Lambda 函数中使用此代码之前，必须添加 @types/aws-lambda 程序包作为开发依赖项。此程序包包含 Lambda 的类型定义。安装 @types/aws-lambda 时，import 语句 (import ... from 'aws-lambda') 会导入类型定义。它不导入 aws-lambda NPM 程序包，这是一个无关的第三方工具。有关更多信息，请参阅 DefinitelyTyped GitHub 存储库中的 aws-lambda。
本示例中的处理程序是 ES 模块，必须位于 package.json 文件中或使用 .mjs 文件扩展名进行指定。有关详细信息，请参阅将函数处理程序指定为 ES 模块。


import { Context, APIGatewayProxyCallback, APIGatewayEvent } from 'aws-lambda';

export const lambdaHandler = (event: APIGatewayEvent, context: Context, callback: APIGatewayProxyCallback): void => {
    console.log(`Event: ${JSON.stringify(event, null, 2)}`);
    console.log(`Context: ${JSON.stringify(context, null, 2)}`);
    callback(null, {
        statusCode: 200,
        body: JSON.stringify({
            message: 'hello world',
        }),
    });
};

将类型用于事件对象

我们建议您不要将任何类型用于处理程序参数和返回类型，因为您将失去检查类型的能力。相反，请使用 sam local generate-event AWS Serverless Application Model CLI 命令或者使用来自 @types/aws-lambda 软件包的开源定义生成事件。

使用 sam local generate-event 命令生成事件

生成 Amazon Simple Storage Service (Amazon S3) 代理事件。
```
sam local generate-event s3 put >> S3PutEvent.json
```
使用 quicktype 实用工具从 S3PutEvent.json 文件生成类型定义。
```
npm install -g quicktype
quicktype S3PutEvent.json -o S3PutEvent.ts
```

在您的代码中使用生成的类型。


import { S3PutEvent } from './S3PutEvent';

export const lambdaHandler = async (event: S3PutEvent): Promise<void> => {
  event.Records.map((record) => console.log(record.s3.object.key));
};

使用来自 @types/aws-lambda 软件包的开源定义生成事件

添加 @types/aws-lambda 软件包作为开发依赖项。
```
npm install -D @types/aws-lambda
```

在您的代码中使用这些类型。


import { S3Event } from "aws-lambda";

export const lambdaHandler = async (event: S3Event): Promise<void> => {
  event.Records.map((record) => console.log(record.s3.object.key));
};

Typescript Lambda 函数的代码最佳实践

在构建 Lambda 函数时，请遵循以下列表中的指南，采用最佳编码实践：

从核心逻辑中分离 Lambda 处理程序。这样您可以创建更容易进行单元测试的函数。在 Node.js 中可能如下所示：


exports.myHandler = function(event, context, callback) {
	var foo = event.foo;
	var bar = event.bar;
	var result = MyLambdaFunction (foo, bar);

	callback(null, result);
}

function MyLambdaFunction (foo, bar) {
	// MyLambdaFunction logic here
}

控制函数部署程序包中的依赖关系。AWS Lambda 执行环境包含许多库。对于 Node.js 和 Python 运行时，其中包括 AWS SDK。Lambda 会定期更新这些库，以支持最新的功能组合和安全更新。这些更新可能会使 Lambda 函数的行为发生细微变化。要完全控制您的函数所用的依赖项，请使用部署程序包来打包所有依赖项。
将依赖关系的复杂性降至最低。首选在执行环境启动时可以快速加载的更简单的框架。
将部署程序包大小精简为只包含运行时必要的部分。这样会减少调用前下载和解压缩部署程序包所需的时间。

利用执行环境重用来提高函数性能。连接软件开发工具包 (SDK) 客户端和函数处理程序之外的数据库，并在 /tmp 目录中本地缓存静态资产。由函数的同一实例处理的后续调用可重用这些资源。这样就可以通过缩短函数运行时间来节省成本。

为了避免调用之间潜在的数据泄露，请不要使用执行环境来存储用户数据、事件或其他具有安全影响的信息。如果您的函数依赖于无法存储在处理程序的内存中的可变状态，请考虑为每个用户创建单独的函数或单独的函数版本。
使用 keep-alive 指令来维护持久连接。Lambda 会随着时间的推移清除空闲连接。在调用函数时尝试重用空闲连接会导致连接错误。要维护您的持久连接，请使用与运行时关联的 keep-alive 指令。有关示例，请参阅在 Node.js 中通过 Keep-Alive 重用连接。
使用环境变量将操作参数传递给函数。例如，您在写入 Amazon S3 存储桶时，不应对要写入的存储桶名称进行硬编码，而应将存储桶名称配置为环境变量。
避免在 Lambda 函数中使用递归代码，因为如果使用递归代码，函数便会自动调用自身，直到满足某些任意条件为止。这可能会导致意想不到的函数调用量和升级成本。如果您不慎执行此操作，请立即将函数保留并发设置为 0 来限制对函数的所有调用，同时更新代码。
Lambda 函数代码中不要使用非正式的非公有 API。对于 AWS Lambda 托管式运行时，Lambda 会定期为 Lambda 的内部 API 应用安全性和功能更新。这些内部 API 更新可能不能向后兼容，会导致意外后果，例如，假设您的函数依赖于这些非公有 API，则调用会失败。请参阅 API 参考以查看公开发布的 API 列表。
编写幂等代码。为您的函数编写幂等代码可确保以相同的方式处理重复事件。您的代码应该正确验证事件并优雅地处理重复事件。有关更多信息，请参阅如何使我的 Lambda 函数具有幂等性？。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

使用 TypeScript 构建

部署 .zip 文件归档