aws-lambda-durable-functions

AWS Lambda 持久函数

构建具有韧性的多步骤应用和 AI 工作流，最长可运行 1 年，并在中断后仍能可靠地继续执行。

最适合搭配 AWS MCP server 使用，但并非必需。此技能中的所有 AWS 交互都使用标准 AWS CLI 命令，因此在已配置 AWS 凭证的任何环境中均可使用。

关键规则

编写代码前请先阅读以下内容。每条规则都是一项约束，违反后会导致函数在不报错的情况下失效。

1. 必须在创建函数时启用持久执行，之后无法补加。 创建新的 Lambda 函数时必须启用持久执行。请将逻辑迁移到新函数中；不要尝试为现有函数安装 SDK 并包装其处理程序，以为这样就能正常工作。
2. 调用持久函数时必须使用限定 ARN——指定版本、别名或字面后缀 $LATEST。使用未限定的函数名称会导致失败。示例请参阅下文的 调用要求 部分。
3. 持久操作不能嵌套。 不可在另一个步骤的回调中调用 context.step()、context.wait() 或 context.invoke()。请改用 context.runInChildContext() 对操作进行分组。
4. 所有非确定性代码都必须在步骤内运行。 在步骤之外调用 Date.now()、Math.random()、生成 UUID、调用 API 和查询数据库，重放时会产生不同的值并破坏执行状态。
5. 重放时闭包中的变更会丢失——请使用步骤的返回值。
6. 步骤外的副作用会重复发生——请使用 context.logger（可感知重放）。

何时加载参考文件

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

• 入门、基本设置、示例、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

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:live 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 进行本地测试

安全注意事项

• 检查点数据加密：执行状态会自动持久化。请对关联的 CloudWatch Log Groups 启用 KMS 加密，以保护静态存储的检查点数据。
• 步骤结果中的敏感数据：步骤返回值会被检查点记录并持久化。不要从步骤返回机密、原始凭证或 PII——请将敏感数据存储在 Secrets Manager 或 SSM Parameter Store 中，并改为返回引用。
• 输入验证：在将事件负载传递给步骤之前，请在处理程序入口点验证并清理数据。
• 凭证管理：请在步骤内从 AWS Secrets Manager 或 SSM Parameter Store 获取机密。
• 回调负载验证：通过 waitForCallback 接收的数据来自外部系统——请在处理前进行验证和清理。
• 日志记录：在非开发环境中避免使用 DEBUG 日志级别，因为它可能会暴露步骤结果和执行状态。请使用 KMS 启用 CloudWatch Logs 加密。

资源

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