如何在单个SAM模板中定义多路由？及相关疑问解答

问题背景 #

在使用AWS SAM的AWS::Serverless::Function定义API Gateway多路由时，部署CloudFormation模板时报错：

Resource handler returned message: 'The REST API doesn't contain any methods (Service: ApiGateway, Status Code: 400, Request ID: dfe9e452-9312-4c67-ba59-0ea7jq72cce5)'

使用的CFN模板如下：

MyLambdaFunction:
  Type: AWS::Serverless::Function
  Properties:
    Description: >
      Currently does not support S3 upload event.
    Handler: index.handler
    Runtime: nodejs20.x
    FunctionName:
      !Sub
        - "${TheEnv}-${TheAppNameForResources}-get-v1"
        - TheEnv: !Ref Environment
          TheAppNameForResources: !Ref AppNameForResources
    CodeUri: .
    MemorySize: 10240
    Role: !GetAtt MyLambdaExecutionRole.Arn
    Events:
      MyDemoAPI:
        Type: Api
        Properties:
          # RestApiId:
          # Ref: MyApiGateway
          Path: /batch
          Method: GET
      MyTestAPI:
        Type: Api
        Properties:
        # RestApiId:
          # Ref: MyApiGateway
          Path: /qa
          Method: GET
    Tracing: Active
    Tags:
      AppName: !Ref AppNameForTags
      Cost: !Ref CostTagValue

MyApiGateway:
  Type: AWS::Serverless::Api
  Properties:
    Name:
      !Sub
      - '${TheEnv}-${TheAppNameForResources}-api'
      - TheEnv: !Ref Environment
        TheAppNameForResources: !Ref AppNameForResources
        TheBucketRegion: !Ref AWS::Region
    StageName: test
    TracingEnabled: true
    OpenApiVersion: 3.0.2
    Cors:
      AllowHeaders: "'Content-Type,X-Amz-Date,Authorization,X-Api-Key,X-Amz-Security-Token'"
      AllowMethods: "'*'"
      AllowOrigin: "'*'"

注释掉RestApiId后仍报错，提出以下三个疑问：

• 是否必须定义AWS::Serverless::Api块？
• 能否在单个AWS::Serverless::Function块中定义多个路由？
• 若通过AWS::Serverless::Function可实现，何时需使用AWS::Serverless::Api块？

解答 #

1. 是否必须定义AWS::Serverless::Api块？ #

不是必须的。当你在AWS::Serverless::Function的Events字段中定义Api类型事件时，SAM会自动创建一个默认的API Gateway实例（称为"隐式API"），无需手动声明AWS::Serverless::Api资源。

你的报错原因是：模板中手动声明了MyApiGateway，但这个API实例没有关联任何方法——因为你注释掉了函数事件里的RestApiId，导致函数的路由关联到了SAM自动创建的隐式API，而手动创建的MyApiGateway是空的，没有绑定任何方法，因此CloudFormation抛出错误。

2. 能否在单个AWS::Serverless::Function块中定义多个路由？ #

完全可以。只需要在Events字段下添加多个Api类型的事件条目，每个条目对应独立的Path和Method即可，你模板里的写法本身是正确的，但需要注意API实例的关联逻辑：

• 若使用SAM自动创建的隐式API：无需指定RestApiId，所有函数的Api事件都会关联到这个默认API。
• 若使用手动声明的AWS::Serverless::Api：必须在每个Api事件中添加RestApiId: !Ref MyApiGateway，确保所有路由都绑定到同一个手动创建的API实例，避免出现空API引发的报错。

3. 何时需使用AWS::Serverless::Api块？ #

当你需要对API Gateway进行高级自定义配置时，就需要手动声明AWS::Serverless::Api资源，典型场景包括：

• 自定义API名称、阶段名称（如模板中的StageName: test）
• 配置精细化的CORS规则、API密钥、使用计划
• 启用X-Ray追踪、配置访问日志
• 导入现有OpenAPI规范来定义API结构
• 让多个Lambda函数共享同一个API Gateway实例，统一管理路由
• 配置自定义域名、API缓存、限流等高级功能

如果只是简单的路由与Lambda绑定需求，使用SAM自动创建的隐式API即可满足，无需手动声明AWS::Serverless::Api。

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