aws-cdk-examples 实战:在 AWS CDK 中直接引用外部 ASL 文件定义 Step Functions 状态机
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 命令的执行目录一致即可。