aws-lambda-durable-functions

AWS Lambda durable functions

构建具备高韧性的多步骤应用与 AI 工作流，最长支持运行 1 年，并在发生中断时依然能可靠地保持执行进度。

推荐配合 AWS MCP 服务器 使用，但并非必需。本 Skill 中的所有 AWS 交互均使用标准的 AWS CLI 命令，可在任何配置了 AWS 凭证的环境中运行。

关键规则

编写代码前请务必阅读以下规则。违反其中任何一条都可能导致函数静默崩溃。

1. 必须在创建函数时启用持久化执行（Durable execution）——无法对现有函数追加配置。 新的 Lambda 函数必须在创建时就开启持久化执行。请将已有逻辑迁移到新函数中；不要尝试安装 SDK 并直接封装现有函数的 handler，这样是无法正常工作的。
2. Durable functions 必须使用限定 ARN（qualified ARN）进行调用 —— 即指定具体版本、别名，或者带有 $LATEST 后缀。使用未限定的函数名会导致调用失败。示例详见下方的 调用要求 章节。
3. 持久化操作不能嵌套。 你不能在某个 step 的回调函数内部调用 context.step()、context.wait() 或 context.invoke()。请改用 context.runInChildContext() 来对操作进行分组。
4. 所有非确定性代码都必须在 step 内部运行。 在 step 外部使用 Date.now()、Math.random()、生成 UUID、发起 API 调用或数据库查询，会在重放（replay）时产生不同的值，从而损坏执行状态。
5. 闭包修改在重放时会丢失 —— 请通过 step 返回值传递数据
6. step 外部的副作用会在重放时重复执行 —— 请使用 context.logger（具备重放感知能力）

何时读取参考文件

根据当前处理的任务，读取对应的参考文件：

• 入门快速上手、基础配置、示例、ESLint 或 Jest 配置 -> 参见 getting-started.md
• 理解重放模型（replay model）、确定性或非确定性错误 -> 参见 replay-model-rules.md
• 创建 step、原子操作或重试逻辑 -> 参见 step-operations.md
• 等待、延迟、回调、外部系统或轮询 -> 参见 wait-operations.md
• 并行执行、Map 操作、批量处理或并发控制 -> 参见 concurrent-operations.md
• 错误处理、重试策略、Saga 模式或补偿事务 -> 参见 error-handling.md
• 高级错误处理、超时处理、熔断器（circuit breakers）或条件重试 -> 参见 advanced-error-handling.md
• 测试、本地测试、云端测试、测试运行器或不稳定性测试（flaky tests） -> 参见 testing-patterns.md
• 部署、CloudFormation、CDK、SAM、日志组、发布部署或基础设施即代码（IaC） -> 参见 deployment-iac.md
• 高级模式、GenAI Agent、完成策略、step 语义或自定义序列化 -> 参见 advanced-patterns.md
• 故障排查、执行卡住、执行失败、调试执行 ID（execution ID）、执行历史记录、执行错误、“为什么我的执行失败了”、执行超时、未收到回调、执行诊断或排查根因 -> 参见 troubleshooting-executions.md

快速参考

基础 Handler 模式

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 SDK 有所不同：

• Steps（步骤）：使用 @durable_step 装饰器 + context.step(my_step(args))，或使用内联函数 context.step(lambda _: ..., name='...')。推荐优先使用装饰器以实现自动步骤命名。
• Wait（等待）：context.wait(duration=Duration.from_seconds(n), name='...')
• 异常类型：ExecutionError（永久性错误）、InvocationError（临时性错误）、CallbackError（回调失败）
• 测试：直接使用 DurableFunctionTestRunner 类 —— 传入 handler 进行实例化，使用上下文管理器并调用 run(input=...)

调用要求

Durable functions 要求必须使用限定 ARN（qualified ARN）（即包含版本号、别名或 $LATEST）：

# 正确示例
aws lambda invoke --function-name my-function:1 output.json
aws lambda invoke --function-name my-function:live output.json

# 错误示例 —— 会直接失败
aws lambda invoke --function-name my-function output.json

IAM 权限配置

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

• lambda:CheckpointDurableExecution - 持久化执行状态
• lambda:GetDurableExecutionState - 读取执行状态
• CloudWatch Logs 相关权限

以下场景需要额外追加权限：

• Durable 嵌套调用：在目标函数 ARN 上拥有 lambda:InvokeFunction 权限
• 外部回调：外部系统需要 lambda:SendDurableExecutionCallbackSuccess 和 lambda:SendDurableExecutionCallbackFailure 权限

校验规范

在编写或审查 durable function 代码时，请务必检查是否违反了重放模型规范：

1. step 外部存在非确定性代码：Date.now()、Math.random()、UUID 生成、API 调用、数据库查询都必须放在 step 内部
2. 在 step 函数内部嵌套了 durable 操作：不能在 step 函数内部直接调用 context.step()、context.wait() 或 context.invoke() —— 应改用 context.runInChildContext()
3. 闭包变量修改无法持久化：在 step 内部修改的变量在重放时不会保留 —— 请改为通过 step 的返回值传递
4. step 外部的副作用会在重放时重复触发：日志记录请使用 context.logger（它具有重放感知能力，能自动去重）

在实现或修改 durable function 的测试用例时，请务必确认：

1. 所有操作都拥有具名描述（descriptive names）
2. 测试代码通过**名称（NAME）**获取操作，绝不要通过索引获取
3. 已对多次调用的重放行为（replay behavior）进行了测试
4. 本地测试统一使用 LocalDurableTestRunner

安全注意事项

• 检查点数据加密：执行状态会自动持久化存储。建议在关联的 CloudWatch Log Groups 上启用 KMS 加密，保护落地的检查点数据安全。
• step 返回值中的敏感数据：step 的返回值会被保存为检查点并持久化。切勿在 step 中直接返回密钥、明文凭证或个人身份信息（PII）—— 应将敏感数据存入 Secrets Manager 或 SSM Parameter Store，仅返回引用标识。
• 输入校验：在 handler 入口处对 event 入参进行校验与清洗，然后再传递给具体的 step。
• 凭证管理：在 step 内部从 AWS Secrets Manager 或 SSM Parameter Store 获取密钥。
• 回调数据校验：通过 waitForCallback 接收的数据来源于外部系统 —— 在处理前必须进行校验和清洗。
• 日志级别：非开发环境中应避免使用 DEBUG 日志级别，以免泄露 step 返回值和执行状态。建议开启基于 KMS 的 CloudWatch Logs 加密。

相关资源

• AWS Lambda durable functions 官方文档
• JavaScript SDK 仓库
• Python SDK 仓库
• IAM 策略参考指南