🚀 使用 AWS CDK 和 LocalStack 创建完整的 API REST：从零到本地生产

Source: Dev.to

📋 介绍

在本完整教程中，我将向你展示如何使用 AWS CDK、TypeScript 和 LocalStack 创建一个用于管理采购订单的强大 REST API。你将学习如何配置一个本地开发环境，完美模拟 AWS，部署完整的 CRUD，并进行彻底的测试。

🎯 我们要构建什么？

• 完整的 REST API，包含 5 个 CRUD 端点
• TypeScript 编写的 Lambda 函数，对应每个操作
• DynamoDB 数据库 用于持久化
• API Gateway 作为入口点
• LocalStack 用于本地开发，无需 AWS 成本
• 自动化和手动测试

🛠️ 技术栈

• AWS CDK v2.170.0 – 基础设施即代码
• TypeScript 5.x – 主语言
• Node.js 20+ – 运行时
• LocalStack – 本地 AWS 模拟
• DynamoDB – NoSQL 数据库
• API Gateway – API 管理
• Lambda – 无服务器函数

🔧 初始配置

1. 在 VS Code 中安装 LocalStack

📦 安装 LocalStack 扩展

方法 1：通过 VS Code Marketplace

1. 打开 VS Code。
2. 前往扩展选项卡（Ctrl+Shift+X 或 Cmd+Shift+X）。
3. 搜索 “LocalStack”。
4. 安装官方 LocalStack 扩展（由 LocalStack 提供）。
5. 重启 VS Code。

方法 2：通过命令行

code --install-extension localstack.localstack

方法 3：手动安装
访问 VS Code Marketplace - LocalStack 并点击 “Install”。

⚙️ 扩展配置

打开设置（Windows 使用 Ctrl+,，Mac 使用 Cmd+,），搜索 “LocalStack”，并添加以下选项：

{
  "localstack.endpoint": "http://localhost:4566",
  "localstack.profile": "default",
  "localstack.region": "us-east-1",
  "localstack.autoStart": true,
  "localstack.dockerFlags": "-d"
}

🎯 扩展功能

• LocalStack 面板：服务状态、实时日志、服务管理、资源浏览器。
• 可用命令（在命令面板 Ctrl+Shift+P 中）：
  • LocalStack: Start – 启动 LocalStack
  • LocalStack: Stop – 停止 LocalStack
  • LocalStack: Restart – 重启 LocalStack
  • LocalStack: Show Logs – 查看日志
  • LocalStack: Open Web UI – 打开 Web UI
• 与 AWS CLI 集成：自动配置端点、本地配置文件，将 AWS 命令重定向到 LocalStack。

🔍 验证扩展是否安装成功

• 侧边栏：侧栏中出现 LocalStack 图标。
• 命令面板：Ctrl+Shift+P → 搜索 “LocalStack”。
• 状态栏：底部显示状态指示器。

🚀 第一次使用

1. 打开 LocalStack 面板（点击图标）。
2. 点击 Start LocalStack 按钮或使用命令启动 LocalStack。
3. 确认面板显示 Running。
4. 在 Logs 选项卡中查看日志。

2. 从零创建 CDK 项目

📋 前置条件

确保已安装以下工具：

# Node.js（20+ 版）
node --version

# npm
npm --version

# AWS CDK CLI（全局）
npm install -g aws-cdk

# 验证 CDK 安装
cdk --version

🏗️ 初始化 CDK 项目

# 创建项目目录
mkdir cdk-api-localstask
cd cdk-api-localstask

# 用 TypeScript 初始化 CDK 项目
cdk init app --language typescript

检查初始结构

ls -la
# 你应该看到：
# bin/           # 应用入口
# lib/           # Stack 定义
# test/          # 单元测试
# package.json   # 项目依赖
# tsconfig.json  # TypeScript 配置
# cdk.json       # CDK 配置

安装额外依赖

# LocalStack 相关依赖
npm install aws-cdk-local

# Lambda 与 DynamoDB 依赖
npm install @aws-sdk/client-dynamodb @aws-sdk/lib-dynamodb

# TypeScript 依赖
npm install @types/aws-lambda @types/uuid uuid

# 开发依赖
npm install --save-dev @types/node typescript

⚙️ 为 LocalStack 配置脚本

编辑 package.json，添加以下脚本：

{
  "scripts": {
    "build": "tsc",
    "watch": "tsc -w",
    "test": "jest",
    "synth": "cdk synth",
    "deploy": "cdk deploy",
    "local:synth": "npx cdklocal synth",
    "local:deploy": "npx cdklocal deploy",
    "local:destroy": "npx cdklocal destroy",
    "local:diff": "npx cdklocal diff",
    "local:bootstrap": "npx cdklocal bootstrap"
  }
}

🔧 配置 CDK 使用 LocalStack

cdk.json（CDK 配置）：

{
  "app": "npx ts-node --prefer-ts-exts bin/app.ts",
  "watch": {
    "include": ["**"],
    "exclude": [
      "README.md",
      "cdk*.json",
      "**/*.d.ts",
      "**/*.js",
      "tsconfig.json",
      "package*.json",
      "yarn.lock",
      "node_modules",
      "test"
    ]
  },
  "context": {
    "@aws-cdk/aws-lambda:recognizeLayerVersion": true,
    "@aws-cdk/core:checkSecretUsage": true,
    "@aws-cdk/core:target-partitions": ["aws", "aws-cn"],
    "@aws-cdk-containers/ecs-service-extensions:enableDefaultLogDriver": true,
    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true,
    "@aws-cdk/aws-ecs:arnFormatIncludesClusterName": true,
    "@aws-cdk/core:validateSnapshotRemovalPolicy": true,
    "@aws-cdk/aws-codepipeline:crossAccountKeyAliasStackSafeResourceName": true,
    "@aws-cdk/aws-s3:createDefaultLoggingPolicy": true,
    "@aws-cdk/aws-sns-subscriptions:restrictSqsDescryption": true,
    "@aws-cdk/aws-apigateway:disableCloudWatchRole": false,
    "@aws-cdk/core:enablePartitionLiterals": true,
    "@aws-cdk/aws-events:eventsTargetQueueSameAccount": true,
    "@aws-cdk/aws-iam:minimizePolicies": true,
    "@aws-cdk/core:disableStackTrace": false
  }
}

📁 创建目录结构

# 用于组织代码的目录
mkdir -p lib/lambdas
mkdir -p lib/types

# 基础文件
touch lib/types/order.ts
touch lib/lambdas/create-order.ts
touch lib/lambdas/get-order.ts
touch lib/lambdas/list-orders.ts
touch lib/lambdas/update-order.ts
touch lib/lambdas/delete-order.ts

🎯 配置主 Stack

bin/app.ts（入口文件）：

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from 'aws-cdk-lib';
import { CdkApiLocalstackStack } from '../lib/cdk-api-localstask-stack';

const app = new cdk.App();
new CdkApiLocalstackStack(app, 'CdkApiLocalstackStack', {
  env: {
    account: process.env.CDK_DEFAULT_ACCOUNT || '000000000000', // LocalStack 默认
    region: process.env.CDK_DEFAULT_REGION || 'us-east-1',
  },
});