aws-cdk-examples 实战:API Gateway 集成并行 Step Functions,聚合两个 Lambda 结果并同步返回

原创2026-10-14 18:27:501,327 阅读

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-parallel-step-functions 架构设计图

从图中可以看出,客户端请求经过 API Gateway(StepFunctionsRestApi)触发 Express 状态机,状态机内部并行调度两个 Lambda(分别位于不同的私有隔离子网内),随后执行结果被聚合回 API Gateway 输出。

状态机设计:两个并行分支 + 一次结果合并

并行状态机结构图

状态机由三个核心部分组成:

  1. 并行执行区(Parallel):名称为 two-jobs,包含两个分支 quick-job 与 slow-job,各自通过 LambdaInvoke 任务调用一个 Lambda;
  2. 合并区(Pass):名为 merge-outcomes,从并行输出中按数组下标提取两个分支的结果;
  3. 执行完整体:整条链路被封装进 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 返回

结合上面的源码,一次完整调用的数据流如下:

  1. 客户端发起请求,API Gateway 同步启动 Express 状态机;
  2. Parallel(two-jobs)并发运行 quick-job 与 slow-job 两个分支;
  3. quick-job 的 LambdaInvoke 调用快 Lambda,得到 {"message":"Hello World!"};slow-job 的 LambdaInvoke 调用慢 Lambda(等待 5 秒后)得到 {"message":"Hello World zzZ! (Sleepy)"};
  4. 两个分支的输出以数组形式写入 $.CombinedOutput;
  5. merge-outcomes 用 JSONPath 取出 CombinedOutput[0].Payload.body 与 CombinedOutput[1].Payload.body,合并为一个响应对象;
  6. 状态机执行结束,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-lib 2.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 中给出可复用的参照。

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