aws-cdk-examples 实战:API Gateway 集成并行 Step Functions,聚合两个 Lambda 结果并同步返回
aws-cdk-examples 实战:API Gateway 集成并行 Step Functions,聚合两个 Lambda 结果并同步返回
导读
本文基于 aws-cdk-examples 仓库中的 api-gateway-parallel-step-functions 示例,讲解如何用 AWS CDK 搭建"API Gateway → Express 状态机 → 并行执行两个 Lambda → 聚合结果 → 同步返回给客户端"的完整链路。读完本文,你将掌握 StepFunctionsRestApi 与同步 Express 状态机集成的方法、Parallel 状态并行分支与 resultPath 的用法,以及用 Pass 状态做结果合并的 JSONPath 数据流技巧,并能直接复现示例的构建与部署。
架构总览:一条同步的 API 调用链
该示例的核心思路是:API Gateway 暴露一个 REST 端点,请求进来后同步启动一条 Express 状态机(Synchronous Express Workflow),状态机用 Parallel 状态同时执行两个独立的 Lambda 任务,两个任务的返回结果在 Pass 状态中被合并成一个 JSON 对象,最终通过 API Gateway 作为 HTTP 响应返回给调用方。
从图中可以看出,客户端请求经过 API Gateway(StepFunctionsRestApi)触发 Express 状态机,状态机内部并行调度两个 Lambda(分别位于不同的私有隔离子网内),随后执行结果被聚合回 API Gateway 输出。
状态机设计:两个并行分支 + 一次结果合并
状态机由三个核心部分组成:
- 并行执行区(Parallel):名称为
two-jobs,包含两个分支quick-job与slow-job,各自通过LambdaInvoke任务调用一个 Lambda; - 合并区(Pass):名为
merge-outcomes,从并行输出中按数组下标提取两个分支的结果; - 执行完整体:整条链路被封装进
EXPRESS类型的状态机,并由 API Gateway 同步驱动。
两个 Lambda:一个"快",一个"慢"
为了直观演示并行效果,示例准备了两个职责对称的 Lambda:
- my-lambda-1/index.js:立即返回
{"message":"Hello World!"}; - my-lambda-2/index.js:先
await一个 5000ms 的定时器(模拟耗时任务),再返回{"message":"Hello World zzZ! (Sleepy)"}。
两者结构一致:main 是异步函数,返回 { body, statusCode } 形式的对象,异常时返回 { body: JSON.stringify({ error }) }。注意 Lambda 返回的 body 是字符串化的 JSON,这直接决定了后续合并阶段使用的 JSONPath 取值方式。
源码级实现:CDK 堆栈逐段拆解
示例全部基础设施定义在 typescript/api-gateway-parallel-step-functions/index.ts 中,入口 Stack 名为 ApiGatewayParallelStepFunctionsStack(构造时传入的 stack id 为 apigateway-parallel-stepfunctions-stack-2)。
第一步:用 NestedStack 承载 VPC
示例并没有在主 Stack 里直接建 VPC,而是通过 cdk.NestedStack 子堆栈封装网络资源(index.ts):
class VpcNestedStack extends cdk.NestedStack {
public readonly vpc: ec2.Vpc;
constructor(scope: Construct, id: string, props?: cdk.NestedStackProps) {
super(scope, id, props);
this.vpc = new ec2.Vpc(this, 'nested-stack-vpc', {
ipAddresses: ec2.IpAddresses.cidr('10.0.0.0/16'),
natGateways: 0,
maxAzs: 3,
subnetConfiguration: [
{ name: 'public-subnet-1', subnetType: ec2.SubnetType.PUBLIC, cidrMask: 24 },
{ name: 'private-isolated-subnet-1', subnetType: ec2.SubnetType.PRIVATE_ISOLATED, cidrMask: 24 },
]
});
}
}
几个值得注意的配置点:
natGateways: 0:不创建 NAT 网关。对纯 Lambda 无外网需求、且只做内部并行计算的场景,这能显著降低成本;maxAzs: 3:VPC 跨最多 3 个可用区,为后续 Lambda 的PRIVATE_ISOLATED子网提供冗余;- 子网分两层:
PUBLIC(公网子网,供 NAT/负载等公共服务使用)与PRIVATE_ISOLATED(私有隔离子网,Lambda 将部署在此,无公网出口,符合最小权限网络模型)。
主 Stack 通过 const { vpc: vpcLambda } = new VpcNestedStack(this, 'nested-stack-lambda'); 取回 VPC 引用,供两个 Lambda 共享。
第二步:定义两个 Lambda 函数
两个 Lambda 的 CDK 配置几乎一致,仅在超时时间与环境上体现"快慢"差异(index.ts):
const lambdaFunction1 = new lambda.Function(this, 'lambda-function-1', {
runtime: lambda.Runtime.NODEJS_24_X,
vpc: vpcLambda,
vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_ISOLATED },
memorySize: 128,
timeout: cdk.Duration.seconds(5),
handler: 'index.main',
code: lambda.Code.fromAsset(path.join(__dirname, '/my-lambda-1')),
environment: {
VPC_CIDR: vpcLambda.vpcCidrBlock,
VPC_ID: vpcLambda.vpcId,
},
logRetention: logs.RetentionDays.ONE_DAY,
});
lambdaFunction1超时 5 秒,对应"快任务";lambdaFunction2超时 10 秒(index.ts),因为其 handler 内部有 5 秒的setTimeout模拟,必须留足余量,同时也能展示并行场景下慢任务不拖慢快任务;- 两个函数均被放置到
PRIVATE_ISOLATED子网,handler: 'index.main'对应 my-lambda-1/index.js 中module.exports = { main }的导出; logRetention: logs.RetentionDays.ONE_DAY将 CloudWatch 日志保留期设为 1 天,是控制日志成本的常见做法;memorySize: 128是最小内存档位,对该示例的轻量逻辑足够。
第三步:用 StateMachineFragment 封装可复用的任务片段
示例定义了一个 MyJob extends stepFunctions.StateMachineFragment 的片段类(index.ts),把"调用某个 Lambda"封装成一个可插入状态机的原子片段:
class MyJob extends stepFunctions.StateMachineFragment {
public readonly startState: stepFunctions.State;
public readonly endStates: stepFunctions.INextable[];
constructor(parent: Construct, id: string, props: any) {
super(parent, id);
this.startState = new tasks.LambdaInvoke(this, 'my-lambda-task', {
lambdaFunction: props.lambdaFunction
});
}
}
StateMachineFragment 是 CDK 中用于复用"状态子图"的机制:它暴露 startState(入口状态)和 endStates(末端状态数组),可被嵌入其他状态机的任意位置。这里每个 MyJob 内部就是一个 LambdaInvoke 任务,调用传入的 lambdaFunction。
第四步:Parallel 并行分支与结果落盘
核心的并行逻辑在 index.ts:
const parallel = new stepFunctions.Parallel(this, 'two-jobs', {
resultPath: '$.CombinedOutput'
})
.branch(new MyJob(this, 'quick-job', { lambdaFunction: lambdaFunction1 }).prefixStates())
.branch(new MyJob(this, 'slow-job', { lambdaFunction: lambdaFunction2 }).prefixStates());
要点解析:
Parallel状态会并发执行所有.branch()注册的分支,只有所有分支都成功完成,Parallel本身才算成功;resultPath: '$.CombinedOutput'把各分支的输出按数组形式写入状态输入中的$.CombinedOutput字段。数组下标 0 对应第一个.branch()(quick-job),下标 1 对应第二个(slow-job);.prefixStates()是StateMachineFragment提供的辅助方法,用片段 id(如quick-job、slow-job)为内部状态名加前缀,避免并行分支内部状态逻辑 ID 冲突;LambdaInvoke任务默认将 Lambda 的返回值写入$.Payload,因此每个分支在CombinedOutput数组里对应一个{ Payload: {...} }对象。
第五步:Pass 状态合并输出
合并动作由 merge-outcomes 这个 Pass 状态完成(index.ts):
const merge = new stepFunctions.Pass(this, 'merge-outcomes', {
parameters: {
'normal.$': '$.CombinedOutput[0].Payload.body',
'fast.$': '$.CombinedOutput[1].Payload.body',
},
});
parallel.next(merge);
Pass状态默认只透传数据不执行计算,这里通过parameters结合.$后缀的 JSONPath 表达式重组输出结构;'normal.$': '$.CombinedOutput[0].Payload.body'取出第一个分支(快任务)Lambda 返回的body字段(即{"message":"Hello World!"}的字符串形式);'fast.$': '$.CombinedOutput[1].Payload.body'取出第二个分支(慢任务)的body字段(即{"message":"Hello World zzZ! (Sleepy)"})。
parallel.next(merge) 把两个状态串成 Parallel → Pass 的链式结构。
第六步:EXPRESS 状态机与日志
状态机本体定义如下(index.ts):
const stfLogGroup = new logs.LogGroup(this, 'stepfunctions-loggroup');
const stateMachine = new stepFunctions.StateMachine(this, 'my-state-machine', {
definitionBody: stepFunctions.DefinitionBody.fromChainable(parallel),
stateMachineType: stepFunctions.StateMachineType.EXPRESS,
logs: {
destination: stfLogGroup,
level: stepFunctions.LogLevel.ALL,
},
});
两个关键点:
stateMachineType: EXPRESS:Express 工作流专为高频、短时、同步调用设计,执行时间上限为 5 分钟,且必须与 API Gateway、Lambda 等同步集成场景配合使用。这正是本示例能"同步返回"的前提——API Gateway 调用的是StartSyncExecution并等待执行结果;logs:将执行日志写入专属LogGroup,LogLevel.ALL记录全部日志级别,便于联调时排查 JSONPath 取值问题;definitionBody: stepFunctions.DefinitionBody.fromChainable(parallel)是 CDK v2 推荐的构造方式,直接把Parallel状态作为状态机的起始状态。
第七步:StepFunctionsRestApi 暴露 REST 端点
最后一步是把状态机挂到 API Gateway 上(index.ts):
const api = new apigateway.StepFunctionsRestApi(this, 'my-api', {
stateMachine,
description: 'example api gateway',
deployOptions: { stageName: 'dev' },
});
const items = api.root.addResource('messages');
items.addMethod('GET');
StepFunctionsRestApi是 CDK 提供的专用构造(L2 构造),它会自动完成:创建 REST API → 为状态机创建StartExecution/StartSyncExecution的执行权限 → 将 API 的POST /(根路径)映射为状态机执行入口;本示例对 Express 状态机走同步执行,API Gateway 会等待执行完成并直接透传执行结果;- 示例在根路径下追加了
messages资源并绑定GET方法。注意:StepFunctionsRestApi默认只在POST /上暴露执行入口,GET /messages这样的自定义资源与方法组合需要读者按需扩展集成逻辑(例如配合自定义映射模板),此处展示的是资源定义方式; deployOptions.stageName: 'dev'指定 API 部署阶段名为dev,部署完成后输出的 API URL 形如https://<api-id>.execute-api.<region>.amazonaws.com/dev/。
响应数据流:从两个 Lambda 到 API 返回
结合上面的源码,一次完整调用的数据流如下:
- 客户端发起请求,API Gateway 同步启动 Express 状态机;
Parallel(two-jobs)并发运行quick-job与slow-job两个分支;quick-job的LambdaInvoke调用快 Lambda,得到{"message":"Hello World!"};slow-job的LambdaInvoke调用慢 Lambda(等待 5 秒后)得到{"message":"Hello World zzZ! (Sleepy)"};- 两个分支的输出以数组形式写入
$.CombinedOutput; merge-outcomes用 JSONPath 取出CombinedOutput[0].Payload.body与CombinedOutput[1].Payload.body,合并为一个响应对象;- 状态机执行结束,API Gateway 将执行结果作为 HTTP 响应返回。
最终返回的样本响应(README 中给出的原样输出)为:
{
"normal":"{\"message\":\"Hello World!\"}",
"fast":"{\"message\":\"Hello World zzZ! (Sleepy)\"}"
}
其中 normal 是 Lambda-1(快任务)的输出,fast 是 Lambda-2(慢任务)的输出——注意两者都是字符串形式的 JSON,这与 Lambda 返回 body: JSON.stringify(...) 的实现一一对应。
构建与部署
按照 README 的操作步骤,在示例根目录(typescript/api-gateway-parallel-step-functions)执行:
npm install -g aws-cdk
npm install
- 第一条命令全局安装 AWS CDK Toolkit(cli);
- 第二条命令安装本示例的依赖(包括
aws-cdk-lib2.262.1 与constructs^10.0.0,以及 devDependencies 中的typescript、jest等,详见 package.json)。
随后执行部署:
cdk deploy
部署完成后,终端会输出 API 的 URL(即上述 dev 阶段的调用地址),可用 curl 或浏览器直接访问验证聚合结果。该命令支持重复执行,用于对已部署 Stack 的增量更新(redeploy)。
CDK Toolkit 与工程配置
本示例的 cdk.json 中 app 字段为:
"app": "npx tsc && npx tsx index.ts"
即 CDK 工具链先通过 TypeScript 编译器完成类型检查(tsc),再用 tsx 直接执行 index.ts 合成模板。context 字段中注入了大量 CDK 特性开关(如 @aws-cdk/aws-ec2:restrictDefaultSecurityGroup、@aws-cdk/aws-lambda:useCdkManagedLogGroup 等),它们是当前版本 CDK 的默认行为配置,一般无需改动。
构建完 TypeScript 代码后,可正常使用 CDK Toolkit 的常用命令(与 README 一致):
$ cdk ls
<list all stacks in this program>
$ cdk synth
<generates and outputs cloudformation template>
$ cdk deploy
<deploys stack to your account>
$ cdk diff
<shows diff against deployed stack>
此外,tsconfig.json 开启了 strict 严格模式,jest.config.js 配置了基于 @swc/jest 的测试环境(testMatch: ['**/*.test.ts']),为后续给 Stack 编写单元测试预留了脚手架。
小结与扩展方向
本示例用约 150 行 CDK 代码,完整演示了"同步 API + 并行任务编排 + 结果聚合"的典型模式,值得提炼的三点经验:
- 同步集成选型:API 场景需要"请求-响应"式结果时,优先选择
EXPRESS状态机 +StepFunctionsRestApi,利用StartSyncExecution实现同步返回,无需自建轮询机制; - 并行结果合并:
Parallel的resultPath把分支结果按序收集为数组,配合Pass的parameters+ JSONPath(CombinedOutput[i].Payload.body)即可无损重组响应结构,是状态机数据流中的高频技巧; - 网络与成本控制:Lambda 放入
PRIVATE_ISOLATED子网、natGateways: 0、日志保留 1 天,在保证功能的前提下体现了对安全与成本的双重考量。
如需扩展,可以在此基础上:将 MyJob 片段替换为更多类型的任务(如 ECS、Batch、SNS 通知);为 API 增加自定义请求/响应映射模板;或改用 Standard 状态机 + 异步模式来处理长耗时工作流——底层构造均已在该仓库的 index.ts 中给出可复用的参照。

