AWS SAM中API网关CORS配置的差异解析

在AWS Serverless Application Model（SAM）模板开发过程中，开发者可能会遇到一个微妙的配置差异问题：当在REST API和HTTP API之间切换时，CORS（跨域资源共享）配置中的允许来源（AllowOrigin）属性命名存在不一致性。

问题背景

在AWS SAM模板中定义API网关时，开发者可以选择两种类型的API：

1. 传统REST API（通过AWS::Serverless::Api资源类型）
2. 新一代HTTP API（通过AWS::Serverless::HttpApi资源类型）

这两种API类型虽然功能相似，但在CORS配置上存在语法差异，特别是对于允许跨域来源的配置项命名。

配置差异详解

REST API的CORS配置

在REST API中，CorsConfiguration使用以下属性：

• AllowHeaders：字符串类型，定义允许的HTTP头
• AllowMethods：字符串类型，定义允许的HTTP方法
• AllowOrigin：字符串类型（注意单数形式），定义允许的来源

示例配置：

Cors:
  AllowOrigin: "https://example.com"
  AllowMethods: "GET,POST"
  AllowHeaders: "Content-Type,X-Amz-Date"

HTTP API的CORS配置

而在HTTP API中，HttpApiCorsConfiguration使用：

• AllowHeaders：列表类型
• AllowMethods：列表类型
• AllowOrigins：列表类型（注意复数形式）

示例配置：

Cors:
  AllowOrigins:
    - "https://example.com"
  AllowMethods:
    - GET
    - POST
  AllowHeaders:
    - Content-Type
    - X-Amz-Date

迁移时的注意事项

当开发者从REST API迁移到HTTP API时，需要注意以下关键点：

1. 属性名变化：AllowOrigin → AllowOrigins（单数变复数）
2. 数据类型变化：字符串 → 列表
3. 值格式变化：逗号分隔的字符串 → YAML列表项

如果直接复制粘贴配置而不做相应修改，SAM转换器会抛出"Invalid value for 'Cors' property"错误，这个错误信息没有明确指出具体是哪个属性配置有问题，导致调试困难。

最佳实践建议

1. 在模板中明确注释API类型，避免混淆
2. 建立配置片段库，区分REST和HTTP API的配置
3. 在CI/CD流程中加入API类型检查
4. 考虑使用SAM策略检查工具验证配置

深入理解

这种差异源于AWS API网关不同版本的设计理念：

• REST API（v1）采用较早期的设计，配置偏向简单字符串
• HTTP API（v2）采用更现代的设计，支持更结构化的数据格式

虽然这种差异给迁移带来了一些挑战，但HTTP API的列表格式实际上提供了更清晰的语法和更好的可维护性，特别是当需要配置多个允许的来源、方法或头时。

总结

AWS SAM中两种API网关类型的CORS配置差异虽然细微，但在实际开发中可能造成困扰。理解这些差异并建立相应的配置规范，可以帮助开发者更高效地在不同API类型间迁移，避免配置错误导致的部署失败。随着HTTP API的普及，建议新项目优先考虑使用HTTP API及其更现代的配置语法。