aws-cdk

AWS CDK TypeScript

概述

使用此技能，通过 TypeScript 和可复用构造、安全的默认设置及以验证为先的交付流程来构建 AWS 基础设施。

适用场景

在以下情况下使用此技能：

• 使用 TypeScript 创建或重构 CDK 应用、堆栈或可复用构造
• 在 L1、L2 和 L3 构造之间进行选择
• 构建无服务器、网络或侧重安全性的 AWS 基础设施
• 配置多堆栈应用和适配环境的部署
• 使用 cdk synth、测试、cdk diff 和 cdk deploy 验证基础设施变更

说明

1. 项目初始化

# Create a new CDK app
npx cdk init app --language typescript

# Project structure
my-cdk-app/
├── bin/
│   └── my-cdk-app.ts          # App entry point (instantiates stacks)
├── lib/
│   └── my-cdk-app-stack.ts    # Stack definition
├── test/
│   └── my-cdk-app.test.ts     # Tests
├── cdk.json                    # CDK configuration
├── tsconfig.json
└── package.json

2. 核心架构

import { App, Stack, StackProps, CfnOutput, RemovalPolicy } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as s3 from 'aws-cdk-lib/aws-s3';

// Define a reusable stack
class StorageStack extends Stack {
  public readonly bucketArn: string;

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

    const bucket = new s3.Bucket(this, 'DataBucket', {
      versioned: true,
      encryption: s3.BucketEncryption.S3_MANAGED,
      removalPolicy: RemovalPolicy.RETAIN,
      blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
    });

    this.bucketArn = bucket.bucketArn;
    new CfnOutput(this, 'BucketName', { value: bucket.bucketName });
  }
}

// App entry point
const app = new App();

new StorageStack(app, 'DevStorage', {
  env: { account: process.env.CDK_DEFAULT_ACCOUNT, region: 'us-east-1' },
  tags: { Environment: 'dev' },
});

new StorageStack(app, 'ProdStorage', {
  env: { account: '123456789012', region: 'eu-west-1' },
  tags: { Environment: 'prod' },
  terminationProtection: true,
});

app.synth();

3. 构造级别

级别	描述	适用场景
L1 (Cfn*)	直接映射 CloudFormation，提供完全控制	需要 L2 未公开的属性
L2	精心设计，提供合理的默认设置和辅助方法	标准资源配置（推荐）
L3（模式）	多资源架构	LambdaRestApi 等常见模式

// L1 — Raw CloudFormation
new s3.CfnBucket(this, 'L1Bucket', { bucketName: 'my-l1-bucket' });

// L2 — Sensible defaults + grant helpers
const bucket = new s3.Bucket(this, 'L2Bucket', { versioned: true });
bucket.grantRead(myLambda);

// L3 — Multi-resource pattern
new apigateway.LambdaRestApi(this, 'Api', { handler: myLambda });

4. CDK 生命周期命令

cdk synth          # Synthesize CloudFormation template
cdk diff           # Compare deployed vs local changes
cdk deploy         # Deploy stack(s) to AWS
cdk deploy --all   # Deploy all stacks
cdk destroy        # Tear down stack(s)
cdk ls             # List all stacks in the app
cdk doctor         # Check environment setup

5. 推荐的交付流程

1. 设计堆栈

   • 从 L2 构造开始，并将重复逻辑提取到自定义构造中。

2. 运行 cdk synth

   • 检查点：合成成功，且没有缺失的导入、无效属性、缺失的上下文或未解析的引用。
   • 如果失败：修复构造配置或上下文值，然后重新运行 cdk synth。

3. 运行基础设施测试

   • 检查点：断言涵盖 IAM 权限范围、有状态资源和关键输出。
   • 如果测试失败：更新堆栈或测试预期，然后重新运行测试套件。

4. 运行 cdk diff

   • 检查点：检查 IAM 权限范围扩大、资源替换、导出变更以及有状态资源删除。
   • 如果差异存在风险：调整名称、依赖项或 RemovalPolicy，然后重新运行 cdk diff。

5. 运行 cdk deploy

   • 检查点：堆栈达到 CREATE_COMPLETE 或 UPDATE_COMPLETE 状态。
   • 如果部署失败：检查 CloudFormation 事件，修复配额、权限、导出冲突或引导问题，然后重试 cdk deploy。

6. 验证运行时结果

   • 在继续之前，确认堆栈输出、端点、警报和集成均按预期运行。

6. 跨堆栈引用

// Stack A exports a value
class NetworkStack extends Stack {
  public readonly vpc: ec2.Vpc;
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    this.vpc = new ec2.Vpc(this, 'Vpc', { maxAzs: 2 });
  }
}

// Stack B imports it via props
interface AppStackProps extends StackProps {
  vpc: ec2.Vpc;
}
class AppStack extends Stack {
  constructor(scope: Construct, id: string, props: AppStackProps) {
    super(scope, id, props);
    new lambda.Function(this, 'Fn', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      vpc: props.vpc,
    });
  }
}

// Wire them together
const network = new NetworkStack(app, 'Network');
new AppStack(app, 'App', { vpc: network.vpc });

示例

示例 1：无服务器 API

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as apigateway from 'aws-cdk-lib/aws-apigateway';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';

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

    const table = new dynamodb.Table(this, 'Items', {
      partitionKey: { name: 'id', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PAY_PER_REQUEST,
      removalPolicy: cdk.RemovalPolicy.DESTROY,
    });

    const fn = new lambda.Function(this, 'Handler', {
      runtime: lambda.Runtime.NODEJS_20_X,
      handler: 'index.handler',
      code: lambda.Code.fromAsset('lambda'),
      environment: { TABLE_NAME: table.tableName },
    });

    table.grantReadWriteData(fn);

    new apigateway.LambdaRestApi(this, 'Api', { handler: fn });
  }
}

示例 2：CDK 断言测试

import { Template } from 'aws-cdk-lib/assertions';
import { App } from 'aws-cdk-lib';
import { ServerlessApiStack } from '../lib/serverless-api-stack';

test('creates DynamoDB table with PAY_PER_REQUEST', () => {
  const app = new App();
  const stack = new ServerlessApiStack(app, 'TestStack');
  const template = Template.fromStack(stack);

  template.hasResourceProperties('AWS::DynamoDB::Table', {
    BillingMode: 'PAY_PER_REQUEST',
  });

  template.resourceCountIs('AWS::Lambda::Function', 1);
});

最佳实践

1. 每个堆栈只负责一项事务 — 将网络、计算、存储和监控分开。
2. 优先使用 L2 构造 — 仅在需要不受支持的属性时才使用 Cfn*。
3. 明确设置环境 — 传入包含账户和区域的 env；避免隐式指定生产目标。
4. 使用授权辅助方法 — 尽可能优先使用 .grant*()，而不是手写 IAM 配置。
5. 部署前检查差异 — 必须检查 IAM 权限扩展、资源替换和删除。
6. 测试基础设施 — 使用细粒度断言覆盖关键资源。
7. 避免硬编码值 — 使用上下文、参数或环境变量。
8. 使用合适的 RemovalPolicy — 生产数据使用 RETAIN，仅在可丢弃的环境中使用 DESTROY。

限制和警告

• CloudFormation 限制 — 每个堆栈最多 500 个资源；大型应用应拆分为多个堆栈
• 合成不等于部署 — cdk synth 只生成模板；cdk deploy 才会应用变更
• 跨堆栈引用会创建 CloudFormation 导出；移除这些引用需要谨慎安排顺序
• 有状态资源（RDS、DynamoDB、含数据的 S3）— 生产环境中始终设置 removalPolicy: RETAIN
• 需要引导 — 首次部署前，每个账户/区域都要运行一次 cdk bootstrap
• 资源打包 — Lambda 代码和 Docker 镜像会上传到 CDK 引导存储桶

参考资料

详细的实现指南位于 references/ 目录中：

• 核心概念 — 应用生命周期、堆栈、构造、环境、资产
• 无服务器模式 — Lambda、API Gateway、DynamoDB、S3 事件、Step Functions
• 网络与 VPC — VPC 设计、子网、NAT、安全组、VPC 端点
• 安全强化 — IAM、KMS、Secrets Manager、WAF、合规性
• 测试策略 — 断言、快照、集成测试、CDK Nag