AWS API Gateway 深度实战：REST/HTTP/WebSocket API 选型与生产部署完整教程（2026最新版）

Meta Description: AWS API Gateway 深度实战教程：REST API vs HTTP API vs WebSocket API 选型对比、Lambda 集成、自定义域名HTTPS、限流防刷、Caching、Usage Plan、监控告警全链路实操，附2026最新价格对比表与常见问题FAQ。

关键词：AWS API Gateway、REST API、HTTP API、WebSocket API、Lambda 集成、API 限流、API 缓存、API Gateway 定价

一、前言：为什么 API Gateway 是云架构的必修课

在实际的云架构设计中，API Gateway 不仅仅是一个简单的请求转发器，它是整个微服务架构的流量入口和安全屏障。当你有多个后端服务（数据库、缓存、消息队列、第三方接口）需要对外暴露时，API Gateway 提供了统一的接入层，避免了客户端直接与每个后端服务耦合。同时，它天然支持 HTTPS 加密传输、请求速率限制、访问日志记录等能力，让你无需在每个微服务中重复实现这些横切功能。

决策口诀：内部轻量选 HTTP，公开生产选 REST，实时双向选 WebSocket。

在云原生架构中，API Gateway 扮演着"门卫"的角色——所有客户端请求都必须先经过它，才能到达后端的 Lambda 函数、微服务或数据库。它负责认证鉴权、流量控制、请求转换、缓存加速、日志监控等一系列横切关注点，让你的后端服务专注于业务逻辑。

AWS 提供了三种 API Gateway 形态：REST API、HTTP API 和 WebSocket API。很多开发者只知道"用 API Gateway 调 Lambda"，却不清楚三种 API 的架构差异、定价逻辑和生产最佳实践。本文从选型到部署，手把手带你把 API Gateway 用到极致。

二、三种 API 类型全景对比

选型结论：对外公开 API（需要缓存、Usage Plan、API Key）选 REST API；内部微服务调用或简单 Lambda 代理选 HTTP API（省钱约 70%）；实时聊天、游戏同步、协作编辑选 WebSocket API。

三、实战一：HTTP API + Lambda 快速搭建

本节演示如何用 HTTP API + Lambda 搭建一个用户信息查询接口，整个过程不超过 10 分钟。

3.1 创建 Lambda 函数

在 AWS Lambda 控制台创建函数，运行时选择 Python 3.12，代码如下：

import json

def lambda_handler(event, context):
    // 从查询参数中获取用户ID
    user_id = event.get('queryStringParameters', {}).get('id', '1')
    // 模拟数据库查询
    users = {
        '1': {'name': '张三', 'email': '[email protected]'},
        '2': {'name': '李四', 'email': '[email protected]'}
    }
    user = users.get(user_id, {'error': '用户不存在'})
    return {
        'statusCode': 200,
        'headers': {'Content-Type': 'application/json'},
        'body': json.dumps(user, ensure_ascii=False)
    }

3.2 使用 CLI 创建 HTTP API 并关联 Lambda

// 创建 HTTP API
API_ID=$(aws apigatewayv2 create-api \
  --name "user-query-http-api" \
  --protocol-type HTTP \
  --query 'ApiId' --output text)

// 创建 Lambda 集成
INTEGRATION_ID=$(aws apigatewayv2 create-integration \
  --api-id $API_ID \
  --integration-type AWS_PROXY \
  --integration-uri arn:aws:lambda:REGION:ACCOUNT:function:user-query-api \
  --payload-format-version 2.0 \
  --query 'IntegrationId' --output text)

// 创建路由 GET /user
aws apigatewayv2 create-route \
  --api-id $API_ID \
  --route-key "GET /user" \
  --target "integrations/$INTEGRATION_ID"

// 部署到默认阶段
aws apigatewayv2 create-stage \
  --api-id $API_ID \
  --stage-name '$default' \
  --auto-deploy

3.3 验证接口可用性

// 获取 API 调用 URL
API_URL=$(aws apigatewayv2 get-api --api-id $API_ID --query 'ApiEndpoint' --output text)

// 测试请求
curl -s "$API_URL/user?id=1" | python3 -m json.tool
// 预期输出：{"name": "张三", "email": "[email protected]"}

HTTP API 的优势在于零配置即可部署，无需手动创建 Stage，系统自动创建 $default 阶段并启用自动部署。对于内部工具、快速原型验证等场景，HTTP API 是最佳选择。

四、实战二：REST API 高级特性（缓存 + 限流 + API Key）

当你的 API 面向外部开发者或需要按调用次数计费时，REST API 的高级特性就派上了用场。

4.1 创建 REST API 并启用缓存

// 创建 REST API
API_ID=$(aws apigateway create-rest-api \
  --name "paid-data-api" \
  --description "付费数据查询接口" \
  --query 'id' --output text)

// 获取根资源 ID
RES_ID=$(aws apigateway get-resources --rest-api-id $API_ID --query 'items[0].id' --output text)

// 创建 GET 方法，使用 API Key 认证
aws apigateway put-method \
  --rest-api-id $API_ID --resource-id $RES_ID \
  --http-method GET --authorization-type API_KEY

// 创建部署和 prod 阶段
aws apigateway create-deployment --rest-api-id $API_ID --stage-name prod

// 启用 0.5GB 缓存
aws apigateway update-stage \
  --rest-api-id $API_ID --stage-name prod \
  --patch-operations \
    op=replace,path=/cacheClusterEnabled,value=true \
    op=replace,path=/cacheClusterSize,value=0.5

启用缓存后，对相同请求参数的重复调用将直接返回缓存结果，大幅降低 Lambda 调用次数和响应延迟。缓存 TTL 默认为 300 秒，可通过 Stage 设置自定义。

4.2 创建 Usage Plan 控制调用配额

Usage Plan 是对外收费 API 的核心机制，它定义了每个 API Key 的限流速率和月度配额。

// 创建 Basic 计划：每秒 50 次请求，每月 10000 次配额
PLAN_ID=$(aws apigateway create-usage-plan \
  --name "basic-plan" \
  --throttle burstLimit=100,rateLimit=50 \
  --quota limit=10000,period=MONTH \
  --query 'id' --output text)

// 创建 API Key 并关联到 Usage Plan
KEY_ID=$(aws apigateway create-api-key \
  --name "user-key-001" --enabled \
  --query 'id' --output text)
aws apigateway create-usage-plan-key \
  --usage-plan-id $PLAN_ID --key-id $KEY_ID --key-type API_KEY

// 将 Usage Plan 关联到 prod 阶段
aws apigateway update-usage-plan \
  --usage-plan-id $PLAN_ID \
  --patch-operations op=add,path=/stages,name=prod

4.3 测试 API Key 认证

// 无 Key 访问 → 403 Forbidden
curl -s "https://$API_ID.execute-api.REGION.amazonaws.com/prod/data"
// 返回：{"message": "Forbidden"}

// 携带 Key 访问 → 200 OK
API_KEY=$(aws apigateway get-api-key --api-key $KEY_ID --query 'value' --output text)
curl -s -H "x-api-key: $API_KEY" "https://$API_ID.execute-api.REGION.amazonaws.com/prod/data"

五、实战三：WebSocket API 实时通信

WebSocket API 适用于需要双向实时通信的场景，如在线聊天室、多人游戏状态同步、实时数据推送等。

5.1 创建 WebSocket API 架构

// 创建 WebSocket API，路由选择表达式根据消息体中的 action 字段分发
WS_API_ID=$(aws apigatewayv2 create-api \
  --name "chat-websocket-api" \
  --protocol-type WEBSOCKET \
  --route-selection-expression '$request.body.action' \
  --query 'ApiId' --output text)

// 创建 Lambda 集成（处理连接、断开、消息发送）
INTEGRATION_ID=$(aws apigatewayv2 create-integration \
  --api-id $WS_API_ID --integration-type AWS_PROXY \
  --integration-uri arn:aws:lambda:REGION:ACCOUNT:function:ws-handler \
  --query 'IntegrationId' --output text)

// 创建 $connect 路由（客户端连接时触发）
aws apigatewayv2 create-route \
  --api-id $WS_API_ID --route-key '$connect' \
  --target "integrations/$INTEGRATION_ID"

// 创建 $disconnect 路由（客户端断开时触发）
aws apigatewayv2 create-route \
  --api-id $WS_API_ID --route-key '$disconnect' \
  --target "integrations/$INTEGRATION_ID"

// 创建 sendmessage 路由（接收消息并广播）
aws apigatewayv2 create-route \
  --api-id $WS_API_ID --route-key 'sendmessage' \
  --target "integrations/$INTEGRATION_ID"

5.2 连接测试

WebSocket 连接建立后，客户端和服务端之间保持着一条持久化的全双工通道。与传统的 HTTP 请求-响应模式不同，WebSocket 允许服务端主动向客户端推送数据，这在实时场景下大幅降低了延迟和带宽消耗。AWS API Gateway 的 WebSocket API 会在连接建立和断开时分别触发 Lambda 函数，你需要在这些回调中管理连接状态的生命周期。

// 安装 WebSocket 客户端
npm install -g wscat

// 连接到 WebSocket API
wscat -c "wss://$WS_API_ID.execute-api.REGION.amazonaws.com/production"
// 发送消息
> {"action":"sendmessage","message":"Hello World"}

WebSocket API 的 Lambda 函数需要维护连接状态，推荐使用 DynamoDB 存储连接 ID，在 $connect 时写入、$disconnect 时删除，sendmessage 时遍历所有活跃连接并逐一推送。

六、生产部署最佳实践

6.1 自定义域名与 HTTPS 证书

// 在 us-east-1 区域申请 ACM 证书（API Gateway 要求）
aws acm request-certificate \
  --domain-name api.example.com \
  --validation-method DNS

// 创建自定义域名
aws apigatewayv2 create-domain-name \
  --domain-name api.example.com \
  --domain-name-configurations \
    CertificateArn=arn:aws:acm:us-east-1:ACCOUNT:certificate/CERT_ID,EndpointType=REGIONAL

// 创建 API 映射
aws apigatewayv2 create-api-mapping \
  --domain-name api.example.com \
  --api-id $API_ID \
  --stage prod

6.2 请求与响应转换

REST API 支持 Velocity 模板语言（VTL）进行请求和响应的转换。例如，将外部请求的查询参数转换为内部微服务所需的格式：

// 请求转换模板：提取并重命名查询参数
#set($inputRoot = $input.path('$'))
{
  "userId": "$input.params('id')",
  "action": "$input.params('action')",
  "timestamp": "$context.requestTime"
}

6.3 统一错误响应格式

所有 API 应返回标准化的错误格式，便于前端统一处理：

{
  "statusCode": 400,
  "headers": {"Content-Type": "application/json"},
  "body": {
    "error": {
      "code": "INVALID_PARAMETER",
      "message": "参数 id 不能为空",
      "requestId": "$context.requestId"
    }
  }
}

6.4 X-Ray 分布式追踪

启用 X-Ray 可以追踪请求从 API Gateway 到 Lambda 到数据库的完整调用链路，快速定位性能瓶颈：

// 为 REST API Stage 启用 X-Ray
aws apigateway update-stage \
  --rest-api-id $API_ID --stage-name prod \
  --patch-operations op=replace,path=/tracingEnabled,value=true

七、费用对比与省钱策略

省钱核心策略：内部服务调用务必使用 HTTP API 而非 REST API，仅此一项可节省约 70% 的请求费用。对于外部 API，合理利用缓存减少后端调用次数，设置 Usage Plan 防止恶意刷量。

八、监控与告警配置

// 创建 4xx 错误率告警（每5分钟检查一次，连续2次超标则报警）
aws cloudwatch put-metric-alarm \
  --alarm-name "api-gateway-4xx-high" \
  --metric-name 4XXError \
  --namespace AWS/ApiGateway \
  --statistic Sum \
  --period 300 \
  --evaluation-periods 2 \
  --threshold 50 \
  --comparison-operator GreaterThanThreshold \
  --dimensions Name=ApiName,Value=paid-data-api \
  --alarm-actions arn:aws:sns:REGION:ACCOUNT:alerts

// 创建延迟告警（P99 延迟超过 3 秒）
aws cloudwatch put-metric-alarm \
  --alarm-name "api-gateway-latency-high" \
  --metric-name Latency \
  --namespace AWS/ApiGateway \
  --statistic p99 \
  --period 300 \
  --evaluation-periods 3 \
  --threshold 3000 \
  --comparison-operator GreaterThanThreshold \
  --dimensions Name=ApiName,Value=paid-data-api \
  --alarm-actions arn:aws:sns:REGION:ACCOUNT:alerts

九、生产环境常见陷阱

很多团队在将 API Gateway 投入生产环境后才发现一些隐性问题。首先，Lambda 集成的冷启动延迟是 REST API 的常见痛点，解决方案包括使用 Provisioned Concurrency 预热函数、选择更小的部署包体积、以及使用 Graviton2（ARM）架构降低启动时间。其次，跨域资源共享（CORS）配置经常被遗漏，导致浏览器端调用失败——在 HTTP API 中需要在集成响应中正确设置 Access-Control-Allow-Origin 等头信息。最后，日志配置至关重要：默认情况下 API Gateway 不会记录完整的请求和响应体，你需要在 Stage 设置中开启全量日志并将日志组投递到 CloudWatch，以便在出现异常时进行排查。

十、常见问题 FAQ

Q: API Gateway 最大请求体大小是多少？ A: REST API 和 HTTP API 均支持最大 10MB 的请求体，WebSocket API 最大 128KB。对于超大文件上传场景，推荐使用 S3 预签名 URL 让客户端直接上传到 S3，避免经过 API Gateway。

Q: API Gateway 支持 gRPC 吗？ A: 自 2025 年起，REST API 支持 gRPC 后端集成，但客户端仍通过 HTTP/1.1 或 HTTP/2 协议访问。如果需要端到端 gRPC 通信，建议考虑 Application Load Balancer 或 AWS App Mesh。

Q: 如何实现 API 版本管理？ A: 推荐使用路径版本管理方式（如 /v1/users、/v2/users），REST API 原生支持在同一 API 下创建多个资源路径。也可以使用请求头版本控制（X-Api-Version: 2），但需要额外的 VTL 模板处理。

Q: API Gateway 能否直接连接 RDS 数据库？ A: 技术上可以通过 VPC 链接（VPC Link）连接 NLB，NLB 再转发到 RDS，但多了一层网络跳转且增加了延迟和复杂度。最佳实践是使用 Lambda 作为中间层，Lambda 通过 VPC 访问 RDS。

Q: WebSocket 断线重连怎么实现？ A: 客户端监听 onclose 事件后采用指数退避策略重连（1秒、2秒、4秒、8秒……）。服务端在 $connect 阶段将连接 ID 写入 DynamoDB，在 $disconnect 阶段清理，sendmessage 遍历所有活跃连接推送消息。

Q: 如何防止 API 被恶意刷量？ A: 启用 Usage Plan 设置速率限制和配额；使用 WAF 防护 SQL 注入和 XSS 攻击；配置 Usage Plan 的 burst limit 和 rate limit；对敏感接口启用 API Key + IAM 双重认证。

⚠️ 文中价格为 2026 年参考价，实际费用随区域和官方调价变动，请以 AWS 官网为准。

🚀 需要 AWS 国际版账号？通过 3.chengzicloud.cloud 获取最新注册教程与专属优惠，助你轻松上云。

本文由 3.chengzicloud.cloud 提供，点击访问首页了解更多