aws-cdk-examples 实战:在 AWS CDK 中直接引用外部 ASL 文件定义 Step Functions 状态机

原创2026-10-14 20:15:512,328 阅读

aws-cdk-examples 实战:在 AWS CDK 中直接引用外部 ASL 文件定义 Step Functions 状态机

导读

本文基于 aws-cdk-examples 仓库中的 stepfunction-external-definition 示例,讲解如何在 TypeScript CDK 项目中通过 DefinitionBody.fromString 直接加载外部的 Amazon States Language(ASL)文件来定义 Step Functions 状态机,从而复用本地开发工具(如 AWS Toolkit for VS Code)的编写与调试流程,避免在 CDK 代码中重复实现状态机逻辑。读完本文,你将掌握外部 ASL 文件与 CDK 状态机、CloudWatch 日志、API Gateway 触发器的完整集成方案,以及该示例状态机的每个状态语义。

项目背景:为什么要把 ASL 文件放到 CDK 之外

在 AWS CDK 中,Step Functions 状态机的定义方式主要有两类:一类是使用 aws-cdk-lib/aws-stepfunctions 提供的 StateMachine 链式 API(如 Pass、Choice、Wait、Parallel 等类)在代码中逐节点构建;另一类就是本示例采用的方式——直接引用一个现成的、符合 Amazon States Language 规范的 JSON 文件。

原 README.md 明确指出这种做法的核心价值:

在希望利用 Step Functions 状态机本地开发流程(例如 AWS Toolkit for VS Code)的场景下,可以直接把 ASL 文件导入项目,而无需在 CDK 中重写它。

也就是说,当你已经习惯在 IDE 中通过本地 ASL 文件编写、校验、预览状态机时,CDK 侧只需负责"读取文件 + 注册为状态机 + 绑定触发与权限",即可让同一个 ASL 文件同时服务于本地开发与云端部署,保持单一事实来源(Single Source of Truth)。

工程目录结构

该示例的完整目录结构如下:

typescript/stepfunction-external-definition/
├── bin/
│   └── stepfunction-external-definition.ts   # CDK App 入口
├── lib/
│   └── stepfunction-external-definition-stack.ts  # 核心 Stack:状态机 + API Gateway
├── workflow/
│   └── stepfunction.json.asl                 # 外部 ASL 状态机定义文件
├── cdk.json                                  # CDK Toolkit 执行配置
├── package.json                              # 依赖与脚本
└── tsconfig.json                             # TypeScript 编译配置

其中 workflow/stepfunction.json.asl 就是被"外部化"的状态机定义,lib 下的 Stack 通过 Node.js 的文件系统 API 将其读入并注册为 AWS Step Functions 状态机。

核心实现解析:读取外部 ASL 并注册状态机

Stack 的全部逻辑集中在 lib/stepfunction-external-definition-stack.ts,可以拆解为四个步骤。

1. 创建 CloudWatch 日志组

const logGroup = new logs.LogGroup(this, 'MyStateMachineLogGroup', {
  logGroupName: '/aws/vendedlogs/states/MyStateMachine',
  retention: logs.RetentionDays.ONE_WEEK,
});

这里为状态机的执行日志预先创建了一个日志组,名称遵循 Step Functions 推荐的 /aws/vendedlogs/states/ 前缀规范,保留期设置为一周(ONE_WEEK)。相比让 CDK 自动创建日志组,显式声明的好处是你可以直接控制保留期、命名等细节,并能在后续通过 logGroup.grantWrite(stateMachine.role) 明确授予写入权限。

2. 读取外部 ASL 文件

const workflow = fs.readFileSync('./workflow/stepfunction.json.asl', 'utf8');

这是整个示例的关键一行:使用 Node.js 内置的 fs 模块,以 UTF-8 编码同步读取 ./workflow/stepfunction.json.asl。注意该路径是相对于 CDK 命令执行目录(项目根目录)解析的,因此无论 ASL 文件放在 workflow/ 还是其他目录,只要保持相对路径一致即可。

3. 通过 DefinitionBody 注册状态机

const stateMachine = new stepfunctions.StateMachine(this, 'MyStateMachine', {
  stateMachineType: stepfunctions.StateMachineType.EXPRESS,
  definitionBody: stepfunctions.DefinitionBody.fromString(workflow.toString()),
  logs: {
    destination: logGroup,
    level: stepfunctions.LogLevel.ALL,
    includeExecutionData: true,
  },
});

这段代码体现了本示例区别于"链式 API 构建"方式的核心 API:

  • definitionBody: stepfunctions.DefinitionBody.fromString(...):DefinitionBody 是 CDK 中表示状态机定义体的抽象,fromString 工厂方法直接接受一个完整的 ASL JSON 字符串。这正是外部 ASL 文件与 CDK 之间的"桥梁"——你从本地文件读到的内容原样传给状态机,不需要逐节点翻译成 Pass/Choice 等类。
  • stateMachineType: EXPRESS:该状态机类型为 Express Workflows,适合高频、短时执行的场景(如 API 请求级的编排)。Express 类型不会持久化每一步的执行历史,而是依赖 CloudWatch Logs 记录执行数据,因此这里显式配置了 logs。
  • logs 配置:执行日志写入上面创建的日志组,级别为 LogLevel.ALL(记录所有执行事件),并开启 includeExecutionData: true,让日志中包含每个步骤的输入输出数据,便于排障。

最后一行 logGroup.grantWrite(stateMachine.role) 为状态机的执行角色授予向该日志组写入的 IAM 权限,确保 Express 状态机能把执行记录投递到 CloudWatch。

4. 用 API Gateway 暴露触发入口

const api = new apigateway.RestApi(this, "StepFuncApi", {
  restApiName: "StepFuncApi",
  description: "StepFuncApi",
  endpointTypes: [apigateway.EndpointType.REGIONAL]
});
const resource = api.root.addResource("orders");
resource.addMethod("GET", apigateway.StepFunctionsIntegration.startExecution(stateMachine));

示例还演示了如何让外部状态机"跑起来":创建一个区域级(REGIONAL)的 REST API,在 /orders 资源上挂载 GET 方法,并使用 apigateway.StepFunctionsIntegration.startExecution(stateMachine) 将 API 请求直接转换为对状态机的执行启动调用。也就是说,客户端访问 GET /orders 即可触发整个 ASL 工作流,CDK 会自动生成 API Gateway 调用 Step Functions 所需的 IAM 角色与权限。

外部 ASL 工作流逐状态解析

被外部化的状态机定义位于 workflow/stepfunction.json.asl,注释中称其为"供汽车公司使用的简单工作流"(smiple workflow for the car company)。它演示了 ASL 的多种状态类型,适合作为学习外部定义格式的样例。

整体流程为:Order Received → RiskyCustomer(分支)→ 取车/拒绝 → 取车 → 等待 → 归还预约 → 并行处理 → 结束。

状态 类型 作用
Order Received Pass 起始状态,透传输入,进入 RiskyCustomer
RiskyCustomer Choice 依据 $.risk 布尔值分流:true 走 Yes,false 走 No,默认 Yes
Yes Pass 高风险客户仍继续流程,进入 organize pickup
No Fail 低风险客户反而被拒绝(Cause: "Not Hello World")
organize pickup Wait 等待 3 秒模拟安排取车
wait for 6 months Wait 再次等待 3 秒(示例中为简化演示)
organize return Wait 等待 3 秒模拟安排归还
Parallel State Parallel 并行执行两个分支:book(预约)与 calculate damage(计算损坏),互不阻塞
return Pass 汇合后作为终止状态,End: true

其中 Choice 状态的完整写法值得留意,它是 ASL 分支逻辑的标准表达:

"RiskyCustomer": {
  "Type": "Choice",
  "Choices": [
    { "Variable": "$.risk", "BooleanEquals": true,  "Next": "Yes" },
    { "Variable": "$.risk", "BooleanEquals": false, "Next": "No" }
  ],
  "Default": "Yes"
}

Parallel 状态则展示了如何把一个任务拆成多个并行分支:

"Parallel State": {
  "Type": "Parallel",
  "Next": "return",
  "Branches": [
    { "StartAt": "book",           "States": { "book":           { "Type": "Pass", "End": true } } },
    { "StartAt": "calculate damage", "States": { "calculate damage": { "Type": "Pass", "End": true } } }
  ]
}

这个 ASL 文件之所以可以直接被 CDK 消费,是因为 DefinitionBody.fromString 只要求传入合法的 Amazon States Language JSON——文件扩展名 asl 仅用于开发工具识别,不影响 CDK 读取。

入口文件与工程配置

App 入口

bin/stepfunction-external-definition.ts 是标准的 CDK 入口:创建 cdk.App,实例化 StepfunctionExternalDefinitionStack。默认情况下 Stack 不绑定具体账号/区域(environment-agnostic),注释中保留了两种常见用法:通过 CDK_DEFAULT_ACCOUNT/CDK_DEFAULT_REGION 跟随 CLI 当前配置,或直接硬编码 account/region。

cdk.json

cdk.json 中的 app 字段指定了应用的执行方式:

"app": "npx tsc && npx tsx bin/stepfunction-external-definition.ts"

即先由 tsc 编译 TypeScript,再由 tsx 直接运行入口文件。这也解释了为什么 fs.readFileSync('./workflow/stepfunction.json.asl') 中使用的 ./ 相对路径能正确解析:该命令在项目根目录下执行。

依赖版本

package.json 显示该示例基于 aws-cdk-lib 2.262.1 与 aws-cdk(CLI)2.1133.0,TypeScript 约 7.0.2,测试框架使用 jest + @swc/jest。若要在自己的项目中复现,请确认你的 CDK 版本支持 DefinitionBody API(CDK v2 早期版本即已引入)。

常用命令与部署流程

原 README 提供了完整的开发命令清单,在此结合工程配置逐条说明:

命令 作用
npm run build 执行 tsc,将 TypeScript 编译为 JavaScript
npm run watch 执行 tsc -w,监听文件变化并增量编译
npm run test 执行 jest 单元测试(本项目当前未附带测试用例文件,命令由 jest 配置支撑)
npx cdk deploy 将本 Stack 部署到你默认的 AWS 账号/区域
npx cdk diff 对比已部署 Stack 与当前代码的差异
npx cdk synth 生成并输出合成的 CloudFormation 模板

部署完成后,你可以通过 API Gateway 控制台找到 StepFuncApi 的 /orders 端点,向其发起 GET 请求即可触发状态机执行,随后在 CloudWatch Logs 的 /aws/vendedlogs/states/MyStateMachine 日志组中查看包含输入/输出数据的完整执行记录。

与链式 API 定义方式的对比

为了更直观地理解"外部 ASL 定义"的定位,可以对照仓库中另一个 Step Functions 示例 typescript/stepfunctions-job-poller/index.ts。后者使用:

const stateMachine = new sfn.StateMachine(this, 'CronStateMachine', {
  definitionBody: sfn.DefinitionBody.fromChainable(definition),
  ...
});

fromChainable 接收的是由 new sfn.Pass(...)、new sfn.Choice(...) 等类链式构建出的可执行对象;而本示例的 fromString 接收的是纯文本 ASL。两者最终产出的状态机定义一致,区别在于:

  • fromChainable:状态机逻辑完全在 TypeScript 代码中表达,享受 IDE 补全与编译期检查,但无法直接复用工具生成的 ASL 文件;
  • fromString(本示例):状态机逻辑保留在独立的 .asl 文件中,可在 VS Code + AWS Toolkit 中本地编辑、校验和可视化,CDK 仅负责"搬运与挂载",适合团队中由 ASL 文件主导状态机设计的协作方式。

小结

stepfunction-external-definition 示例完整展示了"外部 ASL 文件 + CDK"的集成范式:用 fs.readFileSync 读取 workflow/stepfunction.json.asl,通过 DefinitionBody.fromString 注册为 Express 状态机,配置 CloudWatch 日志组并授权写入,最后由 API Gateway 的 /orders 端点触发执行。这套方案让状态机定义可以在 CDK 代码之外独立演进,直接复用本地开发工具链,是 Step Functions 工程化中值得借鉴的模式。如需在业务中落地,只需替换 workflow/ 下的 ASL 文件内容,并保持 cdk.json 中 app 命令的执行目录一致即可。

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