api-gateway

Amazon API Gateway 开发

关于使用 Amazon API Gateway 构建、管理、治理和运营 API 的专家指南。涵盖 REST API（v1）、HTTP API（v2）和 WebSocket API。

如何使用此技能

回答 API Gateway 相关问题时：

1. 回答前先阅读相关参考文件，不要只依赖此摘要
2. 如果任务涉及多个方面（例如“带 mTLS 和自定义域名的私有 API”），请阅读所有相关参考文件
3. 如果用户需要 IaC 模板，请参考 references/sam-cloudformation.md 或 references/sam-service-integrations.md，并提供完整可用的 SAM/CloudFormation YAML
4. 务必说明会影响用户设计的相关注意事项和限制

快速决策：选择哪种 API 类型？

首先选择合适的 API 类型。此决定会影响后续的所有选择。

REST API 是面向企业的全功能 API 管理平台。它提供组织大规模构建、发布和管理 API 所需的治理、安全、变现和运营控制，包括针对各个使用者的使用计划限流和配额、API 密钥、请求验证、WAF 集成、资源策略、缓存、金丝雀部署和私有端点。

HTTP API 是针对简单 API 工作负载优化的轻量、低成本代理。其成本和延迟均降低约 70%，但不具备上述 API 管理功能。如果你需要快速、轻量地代理到 Lambda 或 HTTP 后端，且不需要上述企业级控制，请选择 HTTP API。

因素	REST API (v1)	HTTP API (v2)	WebSocket API
定位	完整的 API 管理	低成本代理	实时双向通信
成本	较高	便宜约 70%	按消息计费
延迟	较高	较低	持久连接
最大超时时间	50ms-29s（Regional/Private 最长可达 300s）	硬性限制为 30s	29s
载荷	10 MB	10 MB	128 KB 消息 / 32 KB 帧
API 管理
使用计划/API 密钥	是	否	否
请求验证	是（JSON Schema draft 4）	否	否
缓存	是（0.5-237 GB）	否	否
自定义网关响应	是	否	否
VTL 映射模板	是	否（仅参数映射）	是
安全与治理
WAF	是	否（使用 CloudFront + WAF）	否
资源策略	是	否	否
私有端点	是	否	否
mTLS	是（仅限 Regional 自定义域名）	是（仅限 Regional 自定义域名）	通过 CloudFront viewer mTLS
身份验证
Lambda 授权方	是（TOKEN + REQUEST）	是（仅 REQUEST，simple + IAM policy 格式）	是（仅适用于 $connect 的 REQUEST）
JWT 授权方	否（使用 Cognito 授权方）	是（原生支持）	否
Cognito 授权方	是（原生支持）	使用 JWT 授权方	否
运维
金丝雀部署	是	否	否
响应流式传输	是	否	否
X-Ray 跟踪	是	否	否
执行日志	是	否	是
自定义域名共享	不能与 WebSocket 共用	不能与 WebSocket 共用	不能与 REST/HTTP 共用
使用 REST API 的场景：为外部使用者、合作伙伴或多租户平台构建 API；需要强制实施针对各使用者的速率限制和配额；需要在 API 层进行请求验证、缓存或 WAF 防护；需要私有端点、资源策略或金丝雀部署；或者正在构建有变现和治理要求的 API 产品。

使用 HTTP API 的场景：构建轻量级 API 或简单的后端代理；成本和延迟是首要考虑因素；不需要在 API 层进行针对各使用者的限流、请求验证、缓存或 WAF 防护；并且原生 JWT 授权与 OIDC/OAuth 2.0 能满足身份验证需求。请接受硬性 30s 超时限制，以及缺少 API 管理功能这一事实。如需 WAF、边缘缓存或边缘计算，请在 HTTP API 前放置 CloudFront 分配。

使用 WebSocket API 的场景：需要用于实时场景（聊天、通知、实时仪表盘）的持久双向连接。

说明

第 1 步：设计 API

实施前，系统地收集需求。请参阅 references/requirements-gathering.md，了解完整的需求收集流程，涵盖端点、身份验证、数据模型、性能、安全性和部署需求。

关键设计决策：

1. API 类型：使用上方的决策表
2. 端点类型：边缘优化型（适用于全球客户端的默认选择；通过 CloudFront POP 优化 TCP 连接，但不会在边缘缓存）、区域型（适用于同区域客户端，或需要自行使用 CloudFront 分配来实现边缘缓存、边缘计算、精细的 WAF 控制或基于地理位置的路由的全球客户端）、私有型（仅限 VPC 访问，仅适用于 REST API）
3. 拓扑结构：集中式（单个域名，基于路径的路由）与分布式（每个服务使用独立子域名）
4. 身份验证：请参阅 references/authentication.md 中的决策树

第 2 步：实施 API

根据所构建的内容，参阅以下参考资料：

• 架构模式：references/architecture-patterns.md：拓扑结构、多租户 SaaS、混合工作负载、私有 API、多区域、流式处理
• WebSocket API：references/websocket.md：路由选择、@connections 管理、会话管理、客户端弹性、SAM 模板、限制、多区域
• 服务集成：references/service-integrations.md：直接 AWS 服务集成（EventBridge、SQS、SNS、DynamoDB、Kinesis、Step Functions、S3）、HTTP 代理、模拟、VTL 映射模板、二进制媒体类型、Lambda 同步/异步调用
• 自定义域名和路由：references/custom-domains-routing.md：基本路径映射、路由规则、基于标头的版本控制
• 安全性：references/security.md：mTLS（API Gateway 原生支持 + CloudFront 查看者 mTLS）、TLS 策略、资源策略、WAF、HttpOnly Cookie、CRL 检查
• SAM/CloudFormation：references/sam-cloudformation.md：IaC 模式、OpenAPI 扩展、VTL 参考、二进制数据
• SAM 服务集成模板：references/sam-service-integrations.md：EventBridge、SQS、DynamoDB CRUD、Kinesis、Step Functions（REST + WebSocket）模板

步骤 3：配置性能和扩展

• 限流：账户级默认值为 10,000 rps / 5,000 突发容量（可调整；可通过 AWS Support 申请提高）。通过使用计划配置阶段级和方法级限流。参见 references/performance-scaling.md
• 缓存（仅 REST）：默认 TTL 为 300s，最大为 3600s。默认仅缓存 GET 方法。缓存响应最大为 1 MB
• 边缘缓存（所有 API 类型）：如需边缘缓存，可在 Regional API 前放置自行管理的 CloudFront 分配。CloudFront 可降低延迟、后端负载和成本（缓存响应不会到达 API Gateway）。还可启用边缘计算（CloudFront Functions、Lambda@Edge），并按路径配置细粒度缓存行为。与自有 CloudFront 分配配合时，请使用 Regional 端点，而非边缘优化端点
• 扩展：API Gateway 会自动扩展，但需规划整个堆栈（Lambda 并发、DynamoDB 容量）

步骤 4：设置可观测性

始终配置访问日志。对于 REST 和 WebSocket API，还应启用执行日志（生产环境使用 ERROR 级别，仅在调试时使用 INFO）。HTTP API 不支持执行日志；请改用包含增强可观测性变量的访问日志。

根据需求查阅相应的可观测性参考资料：

• 日志设置、日志格式、保留期：references/observability-logging.md
• 指标、警报、指标筛选器、X-Ray 跟踪：references/observability-metrics-alarms.md
• 日志分析与洞察、分析管道、跨账户、控制平面日志：references/observability-analytics.md

步骤 5：部署

• 生产环境使用基础设施即代码（SAM、CDK、CloudFormation、Terraform）
• 金丝雀部署（仅 REST）：将一定比例的流量路由到新版本进行测试
• 蓝绿部署：使用自定义域名 API 映射在不同环境之间切换，实现零停机
• 路由规则（新域名优先）：在自定义域名上声明式地按标头／路径路由，用于版本管理、A/B 测试、渐进式发布和基于单元的路由
• 详细模式参见 references/deployment.md

步骤 6：实施治理

组织范围的 API 标准请参见 references/governance.md，其中涵盖：

• 预防性控制（SCP、IAM 策略）
• 主动控制（CloudFormation Hooks、Guard 规则）
• 检测性控制（AWS Config 规则、EventBridge）
• 安全性、可观测性和管理方面的具体实施示例

响应格式

回答 API Gateway 相关问题时，请按以下结构组织答案：

1. 建议：先给出推荐方案并说明原因
2. 代码：用户需要实现时，提供 SAM／CloudFormation YAML 或代码（务必先阅读相关参考文件）
3. 注意事项：提醒用户注意下文或 references/pitfalls.md 中的相关陷阱
4. 限制：说明会限制设计的服务限额

故障排查速查表

诊断 API Gateway 错误时，请参阅 references/troubleshooting.md，了解详细的解决步骤。以下是最常见的问题：

错误	最常见原因	快速修复
400 Bad Request	与 ALB 的协议不匹配（HTTP/HTTPS）	使协议与侦听器类型一致
401 Unauthorized	令牌类型错误（ID 令牌与访问令牌混淆）或缺少身份源	检查令牌类型是否与范围配置匹配；确认已发送所有身份源
403 Missing Auth Token	使用自定义域名时，URL 中包含阶段名称	从 URL 路径中移除阶段名称
403 from VPC	VPC 端点上的私有 DNS 拦截了所有 API 调用	对公开 API 使用自定义域名
403 Access Denied	资源策略与授权类型不匹配，或缺少重新部署	检查策略和授权类型，然后重新部署 API
403 mTLS	证书颁发者不在信任库中，或签名算法强度不足	确认 CA 位于信任库中，并使用 SHA-256 或更强算法
429 Too Many Requests	超出账户、阶段或方法的限流阈值	实施带抖动的指数退避；申请提高限额
500 Internal Error	缺少 Lambda 调用权限（尤其是在使用阶段变量时）	为 Lambda 函数添加基于资源的策略
502 Bad Gateway	Lambda 响应不符合所需的代理格式	让 Lambda 返回 {statusCode, headers, body}
504 Timeout	后端耗时超过 29 秒（REST，可申请延长）或 30 秒（HTTP，固定上限）。HTTP API 的响应正文显示“Service Unavailable”，但状态码为 504	优化后端，申请延长超时（REST 区域型/私有 API），或改用异步调用
CORS errors	Gateway Responses（4XX/5XX）缺少 CORS 标头	为 DEFAULT_4XX 和 DEFAULT_5XX 网关响应添加 CORS 标头
SSL/PKIX errors	后端证书链不完整	提供完整证书链；仅在测试时使用 insecureSkipVerification

关键注意事项

1. REST API 的默认超时为 29 秒（可通过配额申请将区域型/私有端点的超时延长至 300 秒）。Lambda 会继续运行，但客户端会收到 504。可申请提高超时，或考虑使用异步模式（SQS、EventBridge），以改善长时间操作的用户体验
2. HTTP API 的硬性超时为 30 秒。Lambda 会继续运行，但 API 会返回 {"message":"Service Unavailable"}
3. /ping 和 /sping 是保留路径。请勿将其用于 API 资源
4. 执行日志事件会截断至 1,024 字节。如需完整数据，请使用访问日志
5. 413 REQUEST_TOO_LARGE 是唯一无法自定义的网关响应。可使用 DEFAULT_4XX 作为兜底，为所有 4xx 错误（包括 413）添加 CORS 标头
6. REST API 请求验证不会校验 maxItems/minItems
7. OpenAPI 中根级别的 security 会被忽略。必须在每个操作中单独设置
8. JWT 授权方的公钥会缓存 2 小时。轮换密钥时请考虑这一点
9. 管理 API 的速率限制：10 rps / 突发 40 次。大量自动化操作可能会触及此限制
10. 配置更改后，务必重新部署 REST API。部署前更改不会生效
11. 边缘优化端点不会在边缘缓存——它们仅通过 CloudFront POP 优化 TCP 连接。如果需要边缘缓存、边缘计算（CloudFront Functions、Lambda@Edge）或更精细地控制 CloudFront，请改用区域型 API，并配置自己的 CloudFront 分配

如需了解其他注意事项（标头处理、URL 编码、缓存费用、金丝雀部署、使用计划），请参阅 references/pitfalls.md。

IaC 框架选择

默认：CDK TypeScript

覆盖语法：

• “use SAM” → 生成 SAM/CloudFormation YAML 模板
• “use CloudFormation” → 生成 CloudFormation YAML 模板
• “use Terraform” → 生成 Terraform HCL

未指定时，始终使用 CDK TypeScript。

错误场景

MCP 服务不可用

• 告知用户：“AWS Serverless MCP 无响应”
• 询问：“是否在没有 MCP 支持的情况下继续？”
• 未经用户确认，请勿继续

服务限制速查

完整表格请参阅 references/service-limits.md。下方大多数数值配额为默认值，且可调整；在将其用于架构决策前，请咨询 AWS 账户团队，并查阅最新配额页面。主要限制：

资源	REST API	HTTP API	WebSocket
负载大小	10 MB	10 MB	128 KB
集成超时	50ms-29s（区域型/私有端点最高 300s）	硬性限制为 30s	29s
每个区域的 API 数量	600 个区域型/私有 API；120 个边缘优化 API	600	600
每个 API 的阶段数	10	10	10
每个 API 的路由/资源数	300	300	300
自定义域名（公有）	120	120	120
账户限流	10,000 rps / 突发 5,000 次	相同	相同（共享配额）
每个区域的 API 密钥数	10,000	不适用	不适用
每个区域的使用计划数	300	不适用	不适用
缓存大小	0.5 GB - 237 GB	不适用	不适用