CloudFormation部署WebSocket API报"Invalid method response 200"，手动部署正常？

问题描述 #

部署简单WebSocket Mock路由时触发以下错误：

Execution failed due to configuration error: Output mapping refers to an invalid method response: 200

现有资源包括：

• Websocket API
• Stage
• Deployment
• $connect路由
• 关联Mock的$connect集成（默认映射为{"statusCode": 200}）
• $connect集成响应（直接传递集成结果）
• $connect路由响应

奇怪的是，在AWS控制台点击deploy API就能解决问题，无需修改任何配置，但该操作无法集成到CI/CD流水线中。推测问题出在Route Response上，因为控制台部署时后台执行了CloudFormation部署中缺失的操作。

附cdk synth生成的CloudFormation模板：

Resources:
  testWsApiBackendWsApi40DF2EE8:
    Type: AWS::ApiGatewayV2::Api
    Properties:
      Name: testWsApi
      ProtocolType: WEBSOCKET
      RouteSelectionExpression: $request.body.action

  testWsApiApiDeployment423ACBB9:
    Type: AWS::ApiGatewayV2::Deployment
    Properties:
      ApiId:
        Fn::GetAtt:
          - testWsApiBackendWsApi40DF2EE8
          - ApiId
    DependsOn:
      - MockWithAuthAwsStackwsMockRoute04DB7577
  testWsApiApiStageF40CAAE0:
    Type: AWS::ApiGatewayV2::Stage
    Properties:
      ApiId:
        Fn::GetAtt:
          - testWsApiBackendWsApi40DF2EE8
          - ApiId
      StageName: production
      DeploymentId:
        Fn::GetAtt:
          - testWsApiApiDeployment423ACBB9
          - DeploymentId

  MockWithAuthAwsStackwsMockRoute04DB7577:
    Type: AWS::ApiGatewayV2::Route
    Properties:
      ApiId:
        Fn::GetAtt:
          - testWsApiBackendWsApi40DF2EE8
          - ApiId
      RouteKey: $connect
      Target:
        Fn::Join:
          - ""
          - - integrations/
            - Ref: MockWithAuthAwsStackwsMockIntegration36E7A460

  MockWithAuthAwsStackwsMockIntegration36E7A460:
    Type: AWS::ApiGatewayV2::Integration
    Properties:
      ApiId:
        Fn::GetAtt:
          - testWsApiBackendWsApi40DF2EE8
          - ApiId
      IntegrationType: MOCK
      PassthroughBehavior: WHEN_NO_TEMPLATES
      RequestTemplates:
        $default: '{"statusCode":200}'
      TemplateSelectionExpression: \$default

  MockWithAuthAwsStackwsMockRouteResponseAEE0B8ED:
    Type: AWS::ApiGatewayV2::RouteResponse
    Properties:
      ApiId:
        Fn::GetAtt:
          - testWsApiBackendWsApi40DF2EE8
          - ApiId
      RouteId:
        Ref: MockWithAuthAwsStackwsMockRoute04DB7577
      RouteResponseKey: $default

  MockWithAuthAwsStackwsMockIntegrationResponse85928773:
    Type: AWS::ApiGatewayV2::IntegrationResponse
    Properties:
      ApiId:
        Fn::GetAtt:
          - testWsApiBackendWsApi40DF2EE8
          - ApiId
      IntegrationId:
        Ref: MockWithAuthAwsStackwsMockIntegration36E7A460
      IntegrationResponseKey: $default
      TemplateSelectionExpression: \$default

解决方案 #

1. 修正Deployment的依赖关系 #

错误的核心原因是Deployment资源在Route Response和Integration Response未完全创建时就执行了部署。AWS控制台部署会自动等待所有关联资源就绪，但CloudFormation只会遵循显式声明的DependsOn规则。

修改Deployment资源，添加对Route Response和Integration Response的依赖：

testWsApiApiDeployment423ACBB9:
  Type: AWS::ApiGatewayV2::Deployment
  Properties:
    ApiId:
      Fn::GetAtt:
        - testWsApiBackendWsApi40DF2EE8
        - ApiId
  DependsOn:
    - MockWithAuthAwsStackwsMockRoute04DB7577
    - MockWithAuthAwsStackwsMockRouteResponseAEE0B8ED
    - MockWithAuthAwsStackwsMockIntegrationResponse85928773

2. （可选）简化Mock集成配置 #

对于$connect的Mock集成，无需单独配置Integration Response——Mock集成默认会返回200状态码，且直接传递请求模板的结果。如果没有自定义响应模板的需求，可以直接移除MockWithAuthAwsStackwsMockIntegrationResponse85928773资源，减少冗余配置。

3. CDK代码层面的调整（若使用CDK） #

在CDK中，需要为Deployment节点添加对RouteResponse和IntegrationResponse的依赖，确保资源创建顺序正确：

import * as apigatewayv2 from 'aws-cdk-lib/aws-apigatewayv2';

// 假设已创建wsApi、connectRoute、connectRouteResponse、connectIntegrationResponse

const deployment = new apigatewayv2.CfnDeployment(this, 'Deployment', {
  apiId: wsApi.ref,
});

// 添加依赖，确保所有关联资源就绪后再部署
deployment.addDependsOn(connectRoute);
deployment.addDependsOn(connectRouteResponse);
deployment.addDependsOn(connectIntegrationResponse);

内容的提问来源于stack exchange，提问作者sayandcode