aws-cdk-examples 实战:用 Python CDK 构建 Step Functions 作业轮询状态机
aws-cdk-examples 实战:用 Python CDK 构建 Step Functions 作业轮询状态机
导读
本文围绕 aws-cdk-examples 仓库中的 python/stepfunctions 示例,完整讲解如何用 AWS CDK 的 Python 语言绑定(language bindings)创建一条 Step Functions 状态机。该示例实现了一个典型的"作业轮询(Job Poller)"工作流:提交作业 → 等待 → 查询状态 → 按结果分支 → 成功或失败。读完本文,你将掌握 Python CDK 项目的标准初始化流程(虚拟环境、依赖安装、模板合成),理解 aws_stepfunctions 与 aws_stepfunctions_tasks 两大模块的链式建模方法,并能在自己的账号中部署出同样的状态机。
项目概览:一条"提交—轮询—判定"的状态机
本示例的核心产物是一条由 CDK 合成的 AWS Step Functions 状态机,其逻辑与仓库中 TypeScript 版 stepfunctions-job-poller 一脉相承,完整任务序列为:
- Submit Job:调用
submitLambda,返回状态; - Wait 30 Seconds:等待 30 秒后进入下一节点;
- Get Status:调用
statusLambda查询作业状态; - Job Complete?:
Choice状态读取负载中的status字段进行分支——- 等于
FAILED→ 进入 Fail 节点,以失败终止; - 等于
SUCCEEDED→ 进入 Succeed 节点,成功终止; - 其他情况 → 回到 Wait 30 Seconds 继续轮询。
- 等于
下图即运行本示例后,由 CDK 在 AWS 控制台生成的状态机图形:
从源码结构看,整个状态机的构建由两段代码协作完成:stepfunctions_stack.py 负责定义 Lambda 与状态机,app.py 负责把 Stack 挂载到 CDK App 上。两者共同构成了"入口脚本 + 基础设施即代码"的标准组织方式。
环境准备:Python CDK 项目初始化
README 明确指出,本项目的初始化流程与标准 Python 项目一致,且依赖一个基于 python3 的虚拟环境(默认存放在项目内的 .env 目录)。开始前请确认两个前提:
- 机器上存在可用的
python3(Windows 上为python)可执行文件,且能访问 Python 标准库中的venv包; - 已安装 Node.js 10.13.0 或更高版本(这是 CDK 的官方前置要求,详见 CDK 官方入门文档的 Prerequisites 部分)。
创建虚拟环境
在 MacOS 和 Linux 下手动创建虚拟环境:
$ python3 -m venv .env
初始化完成后,激活虚拟环境:
$ source .env/bin/activate
如果是 Windows 平台,激活方式为:
% .env\Scripts\activate.bat
说明:如果首次自动创建虚拟环境失败,上述手动步骤就是官方推荐的兜底方案;激活后你的所有 Python 依赖都会被安装进该环境,与系统级环境隔离。
安装项目依赖
激活虚拟环境后,执行:
$ pip install -r requirements.txt
本仓库中该文件的内容如下(见 requirements.txt):
aws-cdk-lib>=2.262.0,<3.0.0
constructs>=10.5.0,<11.0.0
types-setuptools
可以看到当前示例基于 aws-cdk-lib 2.x 系列(最低 2.262.0),并通过 constructs 依赖提供构造对象的运行时支持;types-setuptools 用于为 setup.py 的 setuptools 提供类型标注。
若需要新增其他 CDK 库,README 给出的标准做法是:先把它加入 setup.py 的依赖声明中,再重新执行 pip install -r requirements.txt。
合成 CloudFormation 模板
依赖就绪后,即可合成(synthesize)本代码对应的 CloudFormation 模板:
$ cdk synth
该命令会读取 cdk.json 中声明的应用入口并执行它。本仓库的 cdk.json 内容极简:
{
"app": "python3 app.py"
}
也就是说,CDK Toolkit 通过 python3 app.py 来运行应用;而 app.py 只做了三件事——导入 App 与 JobPollerStack、实例化 Stack(id 为 aws-stepfunctions-integ)、调用 app.synth() 触发合成:
#!/usr/bin/env python3
from aws_cdk import App
from stepfunctions.stepfunctions_stack import JobPollerStack
app = App()
JobPollerStack(app, "aws-stepfunctions-integ")
app.synth()
合成完成后,CloudFormation 模板会输出到 cdk.out 目录,你可以在其中核查状态机的 JSON 定义(包括 IAM 角色、Lambda 函数资源与状态机资源)。
状态机核心实现:从构造对象到链式编排
本示例的技术核心全部集中在 stepfunctions_stack.py 中。下面按"资源定义 → 状态节点 → 链式编排 → 状态机"四步拆解。
第一步:定义 Lambda 处理器
submit_lambda = _lambda.Function(self, 'submitLambda',
handler='lambda_function.lambda_handler',
runtime=_lambda.Runtime.PYTHON_3_9,
code=_lambda.Code.from_asset('lambdas/submit'))
status_lambda = _lambda.Function(self, 'statusLambda',
handler='lambda_function.lambda_handler',
runtime=_lambda.Runtime.PYTHON_3_9,
code=_lambda.Code.from_asset('lambdas/status'))
两个函数均使用 Python 3.9 运行时,入口处理器为 lambda_function.lambda_handler,代码分别打包自 lambdas/submit 与 lambdas/status 两个本地目录。这里无需手工上传 zip——Code.from_asset 会在合成阶段自动把目录内容作为资产(asset)打包进 CloudFormation。
第二步:定义各状态节点
submit_job = _aws_stepfunctions_tasks.LambdaInvoke(
self, "Submit Job",
lambda_function=submit_lambda,
output_path="$.Payload",
)
wait_job = _aws_stepfunctions.Wait(
self, "Wait 30 Seconds",
time=_aws_stepfunctions.WaitTime.duration(
Duration.seconds(30))
)
status_job = _aws_stepfunctions_tasks.LambdaInvoke(
self, "Get Status",
lambda_function=status_lambda,
output_path="$.Payload",
)
fail_job = _aws_stepfunctions.Fail(
self, "Fail",
cause='AWS Batch Job Failed',
error='DescribeJob returned FAILED'
)
succeed_job = _aws_stepfunctions.Succeed(
self, "Succeeded",
comment='AWS Batch Job succeeded'
)
这里用到了 CDK 状态机建模的两大核心模块:
aws_stepfunctions:提供基础状态类型——Wait(等待)、Choice(条件分支)、Fail(失败终止)、Succeed(成功终止);aws_stepfunctions_tasks:提供可调用 AWS 服务的任务状态,本示例用的是LambdaInvoke(调用 Lambda 的任务)。
值得注意的细节是 output_path="$.Payload":Lambda 返回的完整对象被包装在 Payload 字段中,该配置把后续状态收到的输入直接裁剪为 Lambda 的返回体,从而让 Choice 状态能直接读取其中的 status 字段。
第三步:链式编排状态与条件分支
chain = submit_job.next(wait_job)\
.next(status_job)\
.next(_aws_stepfunctions.Choice(self, 'Job Complete?')
.when(_aws_stepfunctions.Condition.string_equals('$.status', 'FAILED'), fail_job)
.when(_aws_stepfunctions.Condition.string_equals('$.status', 'SUCCEEDED'), succeed_job)
.otherwise(wait_job))
这是整条状态机的"骨架":
- 通过
next()方法把LambdaInvoke、Wait、Choice等节点首尾相连,形成可读性极高的链式 API; Choice节点通过Condition.string_equals('$.status', 'FAILED')等条件,对输入 JSON 的$.status字段做字符串精确匹配;- 两个
when(...)分别把FAILED引向fail_job、把SUCCEEDED引向succeed_job; otherwise(wait_job)是关键的回环设计——只要状态既不是成功也不是失败,就回到等待节点再次轮询,从而构成"提交 → 轮询 → 再轮询"的循环,直到作业收敛为FAILED或SUCCEEDED。
第四步:创建状态机
sm = _aws_stepfunctions.StateMachine(
self, "StateMachine",
definition_body=_aws_stepfunctions.DefinitionBody.from_chainable(chain),
timeout=Duration.minutes(5),
)
状态机通过 DefinitionBody.from_chainable(chain) 直接接受上面构建的链式对象作为定义,并设置 5 分钟的整体超时。合成时,CDK 会为该状态机自动创建执行所需的 IAM 角色与最小权限策略,并将 Lambda 调用权限一并授予状态机。
Lambda 处理器:模拟"作业状态"
状态机的输入输出由两个极简的 Python Lambda 驱动(见 lambdas/submit/lambda_function.py 与 lambdas/status/lambda_function.py)。
submit 处理器直接返回成功状态:
def lambda_handler(event, context):
# Return the handling result
return {
"event": event,
"status": "SUCCEEDED",
}
status 处理器则对传入的 status 字段做透传判断——成功则继续返回 SUCCEEDED,否则返回 FAILED:
def lambda_handler(event, context):
if event["status"] == "SUCCEEDED":
return {"status": "SUCCEEDED", "event": event}
else:
return {"status": "FAILED", "event": event}
由于示例中的 submit 函数恒返回 SUCCEEDED,在默认行为下,状态机通常会走"提交 → 等待 → 查询 → 成功"这条最短路径;但只要你修改 Lambda 的返回值(例如模拟 FAILED 或中间状态),就能观察到 Choice 节点的失败分支与 otherwise 回环的真实行为——这也正是该示例适合用来学习分支与循环语义的原因。
常用 CDK 命令速查
README 末尾列出了本项目的五条高频命令,适用于所有 CDK Python 项目:
| 命令 | 作用 |
|---|---|
cdk ls |
列出 App 中所有的 Stack(此处应为 aws-stepfunctions-integ) |
cdk synth |
合成并输出 CloudFormation 模板(输出到 cdk.out) |
cdk deploy |
将 Stack 部署到默认 AWS 账号与区域 |
cdk diff |
对比已部署资源与当前代码状态的差异 |
cdk docs |
打开 CDK 官方文档 |
执行 cdk deploy 后,即可在 AWS 控制台的 Step Functions 页面看到上文图形中的状态机;点击"Start execution"可手动触发一次运行,并逐节点观察执行历史,验证 Submit Job → Wait 30 Seconds → Get Status → Job Complete? → Succeeded 的执行轨迹。
小结:本示例的实战价值
通过这个约百行的 Python CDK 示例,可以一次性掌握:
- 项目组织:
app.py(入口)+stack目录(基础设施定义)+lambdas目录(函数代码)+cdk.json(工具配置)+requirements.txt/setup.py(依赖管理)的完整 Python CDK 工程结构; - 状态机建模:
LambdaInvoke、Wait、Choice、Fail、Succeed五种状态对象,以及next()链式编排、Condition.string_equals条件判断、output_path数据裁剪、DefinitionBody.from_chainable状态机装配; - 部署闭环:从
python3 -m venv .env初始化、pip install -r requirements.txt装依赖,到cdk synth出模板、cdk deploy上云的完整流程。
在此基础上,你可以把 Choice 分支扩展为更多状态值、把 Wait 替换为等待外部信号(如 SQS 消息或事件),或接入真实的长时任务(如 AWS Batch、Glue 作业)来构建生产级轮询流水线。
