Claude Code 与 AWS API Gateway：用 SAM 构建 HTTP API、CORS、日志、认证和限流

API Gateway 是公开 API 的入口层

AWS API Gateway 可以理解为公开 API 的入口。它接收来自浏览器、移动端、合作伙伴系统或内部任务的请求，并在同一层处理认证、限流、日志和后端连接。请求进来以后，API Gateway 判断 route，决定是否放行，写入访问日志，然后把请求交给 Lambda、HTTP 后端或其他 AWS 服务。

这个定义对 Claude Code 很重要。如果只写「帮我做一个 API」，Claude Code 可能会生成能跑的 Lambda，却没有把 CORS、JWT 或 IAM 认证、Access Log、throttling、stage 命名，以及 HTTP API 与 REST API 的选择讲清楚。演示时一切正常，真正接到前端后才发现浏览器被 CORS 挡住，或者生产事故时找不到对应的 requestId。

本文以 AWS 官方文档为依据，用 AWS SAM 做一个可复制的 HTTP API 示例。重点不是堆配置，而是把 API Gateway 变成 Claude Code 可以审查的边界：入口是否公开、CORS 是否过宽、日志是否足够、限流是否保护后端。

先选择 REST API、HTTP API 或 WebSocket API

API Gateway 常见有三种形态：REST API、HTTP API 和 WebSocket API。AWS 官方说明中，API Gateway 用于创建、发布和管理 API，把客户端连接到 Lambda、HTTP endpoint 或 AWS 服务。

类型	适合场景	实务判断
HTTP API	SPA、移动端、Lambda JSON API	如果需要低成本、低延迟、JWT、CORS、日志和简单 route，通常先选它
REST API	更完整的 API 管理	如果需要 API key、usage plan、请求验证、WAF、private endpoint 或客户级限流，选择它
WebSocket API	双向通信	聊天、通知、实时进度、服务器主动推送时使用

AWS 的比较文档说明，REST API 功能更丰富，HTTP API 功能更精简、价格更低。也就是说，联系表单、预约、Webhook 或普通 Lambda API，HTTP API 往往已经足够。只有当业务要求 API key、客户套餐、WAF 或私有入口时，REST API 才是更合适的选项。

官方参考：

• Amazon API Gateway concepts
• Choose between REST APIs and HTTP APIs
• WebSocket APIs
• AWS SAM AWS::Serverless::HttpApi

写代码前先确认四个用例

第一个用例是 Lambda 集成。API Gateway 负责公开 URL 和路由，Lambda 负责业务逻辑。联系表单、预约表单、SaaS Webhook、小型后台 API 都适合这种分工。

第二个用例是 CORS。当前端在 https://example.com，API 在 execute-api 域名下时，浏览器会把它们视为不同 origin。AWS 文档说明，HTTP API 配置 CORS 后，API Gateway 可以响应 preflight OPTIONS 请求。文档也说明，如果 API 层已经配置 CORS，来自后端集成的 CORS header 可能会被忽略。因此不要只在 Lambda 里写 CORS；主要设计应放在 API Gateway。

第三个用例是认证。JWT authorizer 适合用户端 API，例如 Cognito 或 OIDC 提供商签发 token。IAM authorization 适合 AWS workload 之间调用，客户端需要 SigV4 签名并拥有 execute-api 权限。Lambda authorizer 则适合自定义规则，例如旧会员库、合作伙伴合同、IP 限制或复杂权限。

第四个用例是日志和限流。CloudWatch Access Log 应至少包含 requestId、routeKey、status、IP 和时间。Throttling 可以返回 429 Too Many Requests，但 AWS 将这些值描述为保护目标，而不是绝对不可突破的硬墙。后端还需要 Lambda 并发限制、数据库保护和客户端退避重试。

可复制的 AWS SAM 示例

创建 template.yaml。

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Claude Code Lab HTTP API sample with CORS, logs, throttling, and Lambda proxy

Parameters:
  StageName:
    Type: String
    Default: Prod
  AllowedOrigin:
    Type: String
    Default: https://example.com

Globals:
  Function:
    Runtime: nodejs20.x
    Architectures:
      - arm64
    Timeout: 10
    MemorySize: 256

Resources:
  ApiAccessLogs:
    Type: AWS::Logs::LogGroup
    Properties:
      RetentionInDays: 14

  PublicHttpApi:
    Type: AWS::Serverless::HttpApi
    Properties:
      StageName: !Ref StageName
      CorsConfiguration:
        AllowOrigins:
          - !Ref AllowedOrigin
        AllowHeaders:
          - authorization
          - content-type
          - x-request-id
        AllowMethods:
          - GET
          - POST
          - OPTIONS
        MaxAge: 300
      AccessLogSettings:
        DestinationArn: !GetAtt ApiAccessLogs.Arn
        Format: '{"requestId":"$context.requestId","routeKey":"$context.routeKey","status":"$context.status","ip":"$context.identity.sourceIp","requestTime":"$context.requestTime","responseLength":"$context.responseLength"}'
      DefaultRouteSettings:
        ThrottlingBurstLimit: 20
        ThrottlingRateLimit: 10
      RouteSettings:
        "POST /contacts":
          ThrottlingBurstLimit: 5
          ThrottlingRateLimit: 2
      FailOnWarnings: true

  HealthFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handler.health
      Events:
        Health:
          Type: HttpApi
          Properties:
            ApiId: !Ref PublicHttpApi
            Path: /health
            Method: GET
            PayloadFormatVersion: "2.0"

  ContactFunction:
    Type: AWS::Serverless::Function
    Properties:
      Handler: src/handler.contact
      Events:
        Contact:
          Type: HttpApi
          Properties:
            ApiId: !Ref PublicHttpApi
            Path: /contacts
            Method: POST
            PayloadFormatVersion: "2.0"
            TimeoutInMillis: 10000

Outputs:
  ApiUrl:
    Description: Invoke URL
    Value: !Sub "https://${PublicHttpApi}.execute-api.${AWS::Region}.${AWS::URLSuffix}/${StageName}/"

再创建 package.json 和 src/handler.js。

{
  "type": "module",
  "scripts": {
    "check": "node --check src/handler.js"
  }
}

const json = (statusCode, body) => ({
  statusCode,
  headers: { "content-type": "application/json" },
  body: JSON.stringify(body)
});

export const health = async () => json(200, {
  ok: true,
  service: "claude-code-api-gateway",
  checkedAt: new Date().toISOString()
});

export const contact = async (event) => {
  let payload;
  try {
    payload = JSON.parse(event.body ?? "{}");
  } catch {
    return json(400, { message: "Request body must be valid JSON." });
  }

  const name = String(payload.name ?? "").trim();
  const email = String(payload.email ?? "").trim();
  if (!name || !email.includes("@")) {
    return json(422, { message: "name and a valid email are required." });
  }

  return json(202, {
    message: "accepted",
    requestId: event.requestContext?.requestId,
    received: { name, email }
  });
};

执行：

npm run check
sam build
sam deploy --guided \
  --stack-name clc-api-gateway-sample \
  --parameter-overrides AllowedOrigin=https://example.com

让 Claude Code 做上线前审查

请在生产发布前审查这个 AWS SAM template。
检查是否存在公开 route、CORS 是否过宽、是否缺少 JWT/IAM/Lambda authorizer、
Access Log 是否缺少 requestId 或 routeKey、throttling 是否太弱、
Lambda 错误响应是否安全，以及是否有必须使用 REST API 而不是 HTTP API 的需求。
请给出具体 template 修改建议。

这个 prompt 的重点不是让 Claude Code 继续写更多代码，而是让它站在运维和安全角度找风险。API Gateway 是入口层，入口层最怕「能跑但没有边界」。

常见失败例

第一，只在 Lambda 返回 CORS header。HTTP API 配置 CORS 后，应以 API Gateway 层为准。

第二，晚一点再开 access log。很多 403、404、429 发生在 Lambda 之前，没有 access log 很难调查。

第三，把 throttling 当成绝对上限。还要结合 Lambda 并发、数据库限制、队列和客户端 backoff。

第四，凭习惯选择 API 类型。HTTP API 对很多简单 API 很好，但 API key、usage plan、WAF、private endpoint 仍然是 REST API 的强项。

相关内容可以继续读 Claude Code AWS Lambda、Claude Code AWS CloudWatch 和 Claude Code AWS IAM。团队训练材料整理在 training 页面。

Masa 手边试过的结果

Masa 按照「设计、template、Lambda、审查」四步测试了这个流程。最有价值的发现不是语法，而是 POST /contacts 应比 /health 有更严格限流，Access Log 必须包含 requestId 和 routeKey，公开 route 应被标记为临时状态。从 API Gateway 边界开始，后面的 Lambda 实现明显更安静、更容易审查。