aws-lambda-durable-functions

AWS Lambda durable functions

构建具备韧性的多步骤应用和 AI 工作流，这些应用和工作流最长可运行 1 年，即使遇到中断，也能可靠地持续推进。

入门

步骤 1：验证前提条件

使用 AWS Lambda durable functions 之前，请确认：

1. AWS CLI 已安装（2.33.22 或更高版本）并已配置：

   aws --version
   aws sts get-caller-identity
   

2. 运行时环境已就绪：

   • 对于 TypeScript/JavaScript：Node.js 22+（node --version）
   • 对于 Python：Python 3.11+（python --version。请注意，目前只有 Lambda 运行时环境 3.13+ 预装了 Durable Execution SDK。Durable SDK 本身支持的最低 Python 版本是 3.11，但你可以使用 OCI 搭载自己的容器映像，并在其中使用自己的 Python 运行时和 Durable SDK。）

3. 部署能力已具备（以下至少一项）：

   • AWS SAM CLI（sam --version）1.153.1 或更高版本
   • AWS CDK（cdk --version）v2.237.1 或更高版本
   • 直接部署到 Lambda 的权限

步骤 2：选择语言和 IaC 框架

语言选择

默认值：TypeScript

覆盖语法：

• “use Python” → 生成 Python 代码
• “use JavaScript” → 生成 JavaScript 代码

未指定时，始终使用 TypeScript

IaC 框架选择

默认值：CDK

覆盖语法：

• “use CloudFormation” → 生成 YAML 模板
• “use SAM” → 生成 YAML 模板

未指定时，始终使用 CDK

错误场景

不支持的语言

• 列出检测到的语言
• 声明：“Durable Execution SDK 尚不支持 [framework]”
• 建议使用受支持的语言作为替代方案

不支持的 IaC 框架

• 列出检测到的框架
• 声明：“[framework] 可能尚不支持 Lambda durable functions”
• 建议使用受支持的框架作为替代方案

Serverless MCP 服务不可用

• 告知用户：“AWS Serverless MCP 无响应”
• 询问：“是否在没有 MCP 支持的情况下继续？”
• 未经用户确认，不要继续

步骤 3：安装 SDK

对于 TypeScript/JavaScript：

npm install @aws/durable-execution-sdk-js
npm install --save-dev @aws/durable-execution-sdk-js-testing

对于 Python：

pip install aws-durable-execution-sdk-python
pip install aws-durable-execution-sdk-python-testing

何时加载参考文件

根据用户正在处理的内容加载相应的参考文件：

• 入门指南、基本设置、示例、ESLint 或 Jest 设置 -> 参见 getting-started.md
• 了解重放模型、确定性或非确定性错误 -> 参见 replay-model-rules.md
• 创建步骤、原子操作或重试逻辑 -> 参见 step-operations.md
• 等待、延迟、回调、外部系统或轮询 -> 参见 wait-operations.md
• 并行执行、映射操作、批处理或并发 -> 参见 concurrent-operations.md
• 错误处理、重试策略、saga 模式或补偿事务 -> 参见 error-handling.md
• 高级错误处理、超时处理、熔断器或条件重试 -> 参见 advanced-error-handling.md
• 测试、本地测试、云测试、测试运行器或不稳定测试 -> 参见 testing-patterns.md
• 部署、CloudFormation、CDK、SAM、日志组、部署或基础设施 -> 参见 deployment-iac.md
• 高级模式、GenAI Agent、完成策略、步骤语义或自定义序列化 -> 参见 advanced-patterns.md
• 故障排除、卡住的执行、失败的执行、调试执行 ID、执行历史记录、执行错误、我的执行为何失败、执行超时、未收到回调、诊断执行或执行根本原因 -> 参见 troubleshooting-executions.md

快速参考

基本处理程序模式

TypeScript：

import { withDurableExecution, DurableContext } from '@aws/durable-execution-sdk-js';

export const handler = withDurableExecution(async (event, context: DurableContext) => {
  const result = await context.step('process', async () => processData(event));
  return result;
});

Python：

from aws_durable_execution_sdk_python import durable_execution, DurableContext

@durable_execution
def handler(event: dict, context: DurableContext) -> dict:
    result = context.step(lambda _: process_data(event), name='process')
    return result

关键规则

1. 所有非确定性代码都必须放在步骤中（Date.now、Math.random、API 调用）
2. 不能嵌套持久化操作——使用 runInChildContext 对操作进行分组
3. 重放时闭包中的变更会丢失——从步骤返回值
4. 步骤之外的副作用会重复执行——使用 context.logger（可感知重放）

Python API 差异

Python SDK 在几个关键方面与 TypeScript 不同：

• 步骤：使用 @durable_step 装饰器 + context.step(my_step(args))，或内联使用 context.step(lambda _: ..., name='...')。建议使用装饰器自动命名步骤。
• 等待：context.wait(duration=Duration.from_seconds(n), name='...')
• 异常：ExecutionError（永久性）、InvocationError（瞬时）、CallbackError（回调失败）
• 测试：直接使用 DurableFunctionTestRunner 类——用处理程序实例化，使用上下文管理器，并调用 run(input=...)

调用要求

持久化函数必须使用限定 ARN（版本、别名或 $LATEST）：

# Valid
aws lambda invoke --function-name my-function:1 output.json
aws lambda invoke --function-name my-function:prod output.json

# Invalid - will fail
aws lambda invoke --function-name my-function output.json

IAM 权限

你的 Lambda 执行角色必须附加托管策略 AWSLambdaBasicDurableExecutionRolePolicy。该策略包含：

• lambda:CheckpointDurableExecution——持久化执行状态
• lambda:GetDurableExecutionState——检索执行状态
• CloudWatch Logs 权限

以下情况还需要其他权限：

• 持久化调用：目标函数 ARN 上的 lambda:InvokeFunction
• 外部回调：系统需要 lambda:SendDurableExecutionCallbackSuccess 和 lambda:SendDurableExecutionCallbackFailure

验证指南

编写或审查持久函数代码时，务必检查是否存在以下重放模型违规：

1. 步骤外的非确定性代码：Date.now()、Math.random()、UUID 生成、API 调用和数据库查询都必须放在步骤中
2. 步骤函数中的嵌套持久操作：不能在步骤函数中调用 context.step()、context.wait() 或 context.invoke()——请改用 context.runInChildContext()
3. 不会持久化的闭包变量修改：重放期间，步骤中修改的变量不会保留——请改为返回步骤的结果
4. 步骤外重放时会重复执行的副作用：使用 context.logger 记录日志（它能够感知重放，并自动去重）

实现或修改持久函数测试时，务必验证以下内容：

1. 所有操作都有描述性名称
2. 测试按名称获取操作，绝不按索引获取
3. 使用多次调用测试重放行为
4. 使用 LocalDurableTestRunner 进行本地测试

MCP 服务配置

默认启用写入权限。 插件在 .mcp.json 中默认包含 --allow-write，因此 MCP 服务可以代表用户创建项目、生成 IaC 并进行部署。

默认不允许访问敏感数据（如 Lambda 和 API Gateway 日志）。如需授予此权限，请在 .mcp.json 中添加 --allow-sensitive-data-access。

资源

• AWS Lambda 持久函数文档
• JavaScript SDK 仓库
• Python SDK 仓库
• IAM 策略参考