aws-cdk-examples 实战:用 Python CDK 构建 Step Functions 作业轮询状态机

原创2026-10-14 18:13:071,618 阅读

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 一脉相承,完整任务序列为:

  1. Submit Job:调用 submitLambda,返回状态;
  2. Wait 30 Seconds:等待 30 秒后进入下一节点;
  3. Get Status:调用 statusLambda 查询作业状态;
  4. Job Complete?:Choice 状态读取负载中的 status 字段进行分支——
    • 等于 FAILED → 进入 Fail 节点,以失败终止;
    • 等于 SUCCEEDED → 进入 Succeed 节点,成功终止;
    • 其他情况 → 回到 Wait 30 Seconds 继续轮询。

下图即运行本示例后,由 CDK 在 AWS 控制台生成的状态机图形:

Python CDK 创建的 Step Functions 状态机图形

从源码结构看,整个状态机的构建由两段代码协作完成: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 作业)来构建生产级轮询流水线。

登录后查看全文
aws-cdk-examples