Claude Code × AWS API Gateway 完整指南 | REST API 设计到部署自动化

API Gateway 设计工时降至三分之一的经历

我是 Masa，运营着 claudecode-lab.com。当我还是后端开发自由职业者的时候，AWS API Gateway 的设计与实现总是”费时费力的工作”中的头号任务。写端点规格文档、翻译成 CloudFormation、手动配置 Lambda 集成、设置 CORS——每次都会犯同样的错误。

转折点发生在大约六个月前，我让 Claude Code “根据这个用例设计 REST API 并用 CDK 实现”。结果出乎意料地可以直接用于生产，此后 API Gateway 相关的实现工时降至了三分之一。

CORS 漏配、Lambda 权限错误、29 秒超时陷阱——自从 Claude Code 开始提前捕获这些问题，代码审查中被指出的问题也大幅减少了。

---

第一步：将 REST API 端点设计委托给 Claude Code

提示词示例

根据以下用例创建 REST API 端点规格说明。

用例：
- 任务管理应用（用户管理项目和任务）
- 需要用户认证（Cognito）
- 项目可以添加成员
- 任务支持评论和文件附件

输出格式：
- 端点列表（方法、路径、说明）
- 请求/响应 JSON Schema
- 标注需要认证的端点
- 指出违反 REST 原则的地方

---

第二步：自动生成 Lambda 集成配置

生成的 CDK Stack（摘录）

import * as cdk from "aws-cdk-lib";
import * as apigateway from "aws-cdk-lib/aws-apigateway";
import * as nodejs from "aws-cdk-lib/aws-lambda-nodejs";
import * as lambda from "aws-cdk-lib/aws-lambda";
import { Construct } from "constructs";

export class TaskApiStack extends cdk.Stack {
  public readonly api: apigateway.RestApi;

  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ===== Lambda 函数工厂 =====
    const createLambda = (name: string, handler: string) =>
      new nodejs.NodejsFunction(this, name, {
        entry: `src/handlers/${handler}.ts`,
        handler: "handler",
        runtime: lambda.Runtime.NODEJS_20_X,
        timeout: cdk.Duration.seconds(29), // API Gateway 最大超时时间
        memorySize: 256,
        bundling: {
          minify: true,
          sourceMap: true,
          externalModules: ["@aws-sdk/*"],
        },
      });

    const listProjectsFn = createLambda("ListProjects", "projects/list");
    const createProjectFn = createLambda("CreateProject", "projects/create");
    const getProjectFn = createLambda("GetProject", "projects/get");
    const updateProjectFn = createLambda("UpdateProject", "projects/update");
    const deleteProjectFn = createLambda("DeleteProject", "projects/delete");

    // ===== REST API 定义 =====
    this.api = new apigateway.RestApi(this, "TaskApi", {
      restApiName: "task-management-api",
      defaultCorsPreflightOptions: {
        allowOrigins: apigateway.Cors.ALL_ORIGINS, // 生产环境需限制
        allowMethods: apigateway.Cors.ALL_METHODS,
        allowHeaders: ["Content-Type", "Authorization", "X-Api-Key"],
      },
      deployOptions: {
        stageName: "v1",
        loggingLevel: apigateway.MethodLoggingLevel.INFO,
        dataTraceEnabled: false,
      },
    });

    // ===== 资源和方法定义 =====
    const projects = this.api.root.addResource("projects");
    projects.addMethod("GET", new apigateway.LambdaIntegration(listProjectsFn));
    projects.addMethod("POST", new apigateway.LambdaIntegration(createProjectFn));

    const project = projects.addResource("{id}");
    project.addMethod("GET", new apigateway.LambdaIntegration(getProjectFn));
    project.addMethod("PUT", new apigateway.LambdaIntegration(updateProjectFn));
    project.addMethod("DELETE", new apigateway.LambdaIntegration(deleteProjectFn));

    new cdk.CfnOutput(this, "ApiUrl", {
      value: this.api.url,
      description: "API Gateway URL",
    });
  }
}

---

第三步：认证配置（Cognito / Lambda Authorizer / API Key）

模式一：Cognito User Pool Authorizer

const cognitoAuthorizer = new apigateway.CognitoUserPoolsAuthorizer(
  this,
  "CognitoAuthorizer",
  {
    cognitoUserPools: [userPool],
    identitySource: "method.request.header.Authorization",
    resultsCacheTtl: cdk.Duration.minutes(5), // 缓存降低成本
  }
);

projects.addMethod("GET", new apigateway.LambdaIntegration(listProjectsFn), {
  authorizer: cognitoAuthorizer,
  authorizationType: apigateway.AuthorizationType.COGNITO,
});

模式二：Lambda Authorizer

// src/handlers/auth/authorizer.ts
import * as jwt from "jsonwebtoken";

export const handler: APIGatewayTokenAuthorizerHandler = async (event) => {
  const token = event.authorizationToken.replace("Bearer ", "");
  try {
    const decoded = jwt.verify(token, process.env.JWT_SECRET!) as {
      sub: string; email: string; role: string;
    };
    return generatePolicy(decoded.sub, "Allow", event.methodArn, {
      userId: decoded.sub, email: decoded.email, role: decoded.role,
    });
  } catch {
    throw new Error("Unauthorized"); // 返回 401
  }
};

---

第四步：Stage 管理（dev/staging/prod）

// lib/config.ts
export const stageConfig = {
  dev: {
    throttleRateLimit: 10,
    corsOrigins: ["http://localhost:3000"],
    enableDataTrace: true,
  },
  staging: {
    throttleRateLimit: 50,
    corsOrigins: ["https://staging.example.com"],
    enableDataTrace: false,
  },
  prod: {
    throttleRateLimit: 1000,
    corsOrigins: ["https://example.com"],
    enableDataTrace: false,
  },
};

# 部署到开发环境
CDK_ENV=dev npx cdk deploy Api-dev --require-approval never

# 部署到 staging
CDK_ENV=staging npx cdk deploy Api-staging

# 部署到生产（需确认）
CDK_ENV=prod npx cdk deploy Api-prod

---

4 个常见陷阱

陷阱一：CORS 配置缺失（最常见）

// ❌ 不够用
defaultCorsPreflightOptions: { allowOrigins: apigateway.Cors.ALL_ORIGINS }

// ✅ 必须在 Lambda 响应中也加上 CORS 头
return {
  statusCode: 200,
  headers: {
    "Content-Type": "application/json",
    "Access-Control-Allow-Origin": "https://example.com",
    "Access-Control-Allow-Credentials": "true",
  },
  body: JSON.stringify(data),
};

陷阱二：Lambda 调用权限缺失

listProjectsFn.addPermission("ApiGatewayInvoke", {
  principal: new iam.ServicePrincipal("apigateway.amazonaws.com"),
  sourceArn: this.api.arnForExecuteApi("GET", "/projects", "v1"),
});

陷阱三：29 秒超时限制

// ✅ 异步模式：立即返回 job ID，然后轮询状态
export const startExport: APIGatewayProxyHandler = async (event) => {
  const jobId = crypto.randomUUID();
  await sqsClient.send(new SendMessageCommand({
    QueueUrl: process.env.JOB_QUEUE_URL!,
    MessageBody: JSON.stringify({ jobId, params: JSON.parse(event.body!) }),
  }));
  return {
    statusCode: 202,
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ jobId, status: "processing" }),
  };
};

陷阱四：Lambda 中请求体缺失

// ✅ 始终明确设置 proxy: true
project.addMethod("POST", new apigateway.LambdaIntegration(createProjectFn, { proxy: true }));

---

总结表格

任务	Claude Code 的价值	难度
REST API 设计	从用例自动生成规格，检查 REST 原则	低
Lambda Integration CDK	批量生成代理集成 + 资源定义	低
Cognito 认证	生成 User Pool、Authorizer、客户端配置	中
Lambda Authorizer	实现 JWT 验证 + Policy 生成	中
Stage 管理	分离环境配置，生成部署命令	中
异步处理	设计 SQS 集成 + 轮询模式	高

---

实际效果：API Gateway 设计到 CDK 部署的时间从 3 天缩短至 1 天。Cognito Authorizer 配置过去需要超过一个小时阅读 AWS 文档，现在用一个 Claude Code 提示词就能解决。

---

相关文章

• Claude Code × AWS Lambda 完整指南
• Claude Code × REST API 设计实践
• Claude Code × AWS IAM 权限设计指南

参考资料

• AWS API Gateway 官方文档
• AWS CDK API Reference - APIGateway