AWS CDK Examples 官方示例仓库指南：五种语言示例的组织方式、运行方法与贡献规范

本文基于 aws-cdk-examples 仓库的根目录 README 展开，系统讲解这个 AWS CDK 官方示例集的定位、五大语言示例目录的组织与稳定性分级、各类语言示例的运行步骤，以及如何借助仓库自带的scripts工具链与快照测试机制来验证示例。读完本文后，你可以快速定位到适合自己语言的 CDK 示例、正确执行cdk synth/cdk deploy，并理解仓库保证示例质量的工程化手段。

一、仓库定位：中间级的官方 CDK 示例集

该仓库是 AWS 官方的 CDK 示例代码集合，用于演示各类常见的 AWS 服务实现与基础设施模式。README 中对其定位有两条关键说明：

1. 语言平行（language parity）目标：仓库按语言划分为若干区块，每种语言下有各自独立的示例子目录，长期目标是让各语言之间保持“示例等价”——即同一个示例能在各语言中同时存在。
2. 中间级学习资源：README 明确指出，本仓库属于“intermediate learning resource”，建议在阅读过 AWS CDK 的 Developer Guide 或 CDK Workshop 之后再参考本仓库的示例。

README 给出的语言支持状态表如下（五种语言在当前仓库中均为 JSII Stable）：

从当前仓库的实际目录统计看，各语言区块收录的示例规模并不完全对等（这正体现了 README 所说的“向完全语言平行演进”的过程）：typescript/下有 79 个示例目录，python/下 64 个，java/下 22 个，go/下 20 个，csharp/下 17 个。TypeScript 区块覆盖面最广，例如包含 appsync-graphql-dynamodb、stepfunctions-job-poller、cloudfront-functions、secrets-manager-rotation 等较复杂的场景；而 lambda-cron 这类基础示例则横跨五个语言目录同时存在，可以直接对比同一模式在不同语言中的写法。

二、仓库顶层结构与配套文件

仓库根目录除五个语言目录外，还包含以下与“示例质量保障”直接相关的文件：

README 的目录还列出了两个索引章节：

• Learning Resources（学习资源）：README 维护了一份学习资源清单，官方资源包括 AWS CDK Developer Guide、API Reference、aws-cdk 主仓库、Construct Hub 与 CDK Workshop；社区资源则收录了 AwesomeCDK 等。如果你自己创建了 CDK 学习资源并希望被收录，需按 CONTRIBUTING.md 中 “Adding Learning Resources” 一节的要求提交 PR。
• Additional Examples（大型示例外链）：README 中维护了一个独立仓库的复杂示例索引表，用于收录“规模超出本仓库范围、但具有完整应用价值”的 CDK 项目，例如 README 中列出的aws-cdk-changelogs-demo——一个用 CDK 部署的完整无服务器 Node.js 应用栈（含 AWS Lambda、Fargate、DynamoDB、ElastiCache、S3 与 CloudFront）。想让自己的仓库进入该表，同样需要通过 PR 并在 CONTRIBUTING.md 的 “Linking External Examples” 一节指引下讨论。

三、按语言运行示例：命令与前提

每个语言目录都有自己的 README，说明该语言的运行前提和步骤。以下按 README 中各语言区块的说明整理。

3.1 TypeScript 示例（typescript/README.md）

$ npm install -g aws-cdk $ cd typescript/EXAMPLE_DIRECTORY $ npm install $ cdk deploy

部署完成后销毁栈：

$ cdk destroy

typescript/README.md 还额外说明了该目录下的.gitignore/.npmignore是各示例项目的参考配置模板：前者排除编译产物、node_modules、CDK staging 与输出目录；后者排除 TypeScript 源文件与测试文件。各具体示例可能在此基础上有自己的定制配置。

3.2 Python 示例（python/README.md）

Python 区块多了一步虚拟环境管理：

# 1. 安装 CDK CLI $ npm install -g aws-cdk # 2. 创建虚拟环境 $ python3 -m venv .venv # 3. 激活虚拟环境（macOS/Linux） $ source .venv/bin/activate # （Windows 则为 .venv\Scripts\activate.bat） # 4. 安装依赖 $ pip install -r requirements.txt # 5. 合成或部署 $ cdk deploy

结束后用cdk destroy销毁栈。Python 区块涵盖面很广，python/README.md 的索引表列出了api-cors-lambda、application-load-balancer、custom-resource、rds、url-shortener、vpc-ec2-local-zones等示例及各自的一句话说明，可作为选型入口。

3.3 .NET 示例（csharp/README.md）

$ npm install -g aws-cdk $ cd csharp/EXAMPLE_DIRECTORY $ cdk deploy # 部署后销毁 $ cdk destroy

该 README 同时指出：CDK 目前只支持 .NET Core 项目。注意各示例目录自带cdk.json与.sln/.csproj，例如 csharp/lambda-cron/cdk.json，无需额外初始化。

3.4 示例目录的内部约定

无论哪种语言，一个可运行的示例通常遵循统一骨架。以 typescript/lambda-cron 为例，目录内包含：

typescript/lambda-cron/ ├── README.md # 稳定性横幅 + 构建/测试/部署说明 ├── cdk.json # CDK CLI 配置（app 入口 + 上下文开关） ├── index.ts # 应用入口（App + Stack） ├── lambda-handler.py # Lambda 内联代码 ├── lambda-cron.test.ts # 基于 aws-cdk-lib/assertions 的测试 ├── jest.config.js ├── package.json └── tsconfig.json

其中 cdk.json 的"app"字段为npx tsc && npx tsx index.ts，并附带一大段context特性开关（如@aws-cdk/aws-lambda:useCdkManagedLogGroup、@aws-cdk/aws-s3:publicAccessBlockedByDefault等），用于锁定示例在特定 CDK 版本下的合成行为。

入口代码 index.ts 则展示了该示例的核心模式：一个 Python 运行时（lambda.Runtime.PYTHON_3_12）的 Lambda 函数通过events.Rule挂接 cron 计划cron(0 18 ? * MON-FRI *)（工作日 18:00 UTC），再由rule.addTarget(new targets.LambdaFunction(lambdaFn))完成触发绑定——这正是 README “示例展示常见服务模式”定位的最小化体现。

四、示例的稳定性分级与质量准入

CONTRIBUTING.md 规定每个新示例必须携带一个Stability Banner，用徽章标明其稳定性级别（取示例所依赖模块中的最低等级）：

• Stable：“应开箱即可构建”，所依赖的 Construct Library 均为 Stable 且无基础设施前置条件；
• Developer Preview：“可能无法开箱构建”，依赖的模块可能随破坏性变更未同步更新，或需要先创建基础设施前置资源；
• Cfn-Only：依赖尚处于 CFN-only 状态的模块。

你可以在 typescript/lambda-cron/README.md 看到 Stable 横幅的完整写法；go/lambda-cron/README.md 则展示了早期 Developer Preview 时期 Go 区块的横幅写法（“Go support is still in Developer Preview”）。

新示例的准入标准（CONTRIBUTING.md “Added Value” 一节）要求示例不得与现有示例重复，并至少满足其一：

1. 记录一种常见基础设施模式（如静态网站、定时触发的 Lambda）；
2. 演示某个 L2 构造的使用方式；
3. 覆盖一个不太显眼的实现（如跨栈资源共享、escape hatch、合成期使用 SSM 值）。

新示例还须满足：用npx cdk init app --language [LANGUAGE]生成标准结构（如 TypeScript 应用入口位于./bin/example-name.ts，栈位于./lib/example-name-stack.ts）、通过cdk synth、通过仓库 scripts 目录下的自动化测试，并按语言风格约定（如 Java 尽量使用 builder、配合 google-java-format）格式化代码。

五、仓库的工程化支撑：synth 脚本与快照测试

5.1scripts/synth.sh：CI 中的统一合成验证

scripts/synth.sh 是维护者在 CI 中批量验证示例可合成性的核心脚本，逻辑简洁：

#!/bin/bash set -euxo pipefail scriptdir=$(cd $(dirname $0) && pwd) export AWS_DEFAULT_REGION="us-east-1" # if cdk.context.json is not provided, copy a fake one fake_context=false [ ! -f cdk.context.json ] && fake_context=true if $fake_context; then cp $scriptdir/fake.context.json cdk.context.json fi cdk synth if $fake_context; then rm -f cdk.context.json fi

要点有三：固定AWS_DEFAULT_REGION=us-east-1保证区域一致；若示例目录缺少cdk.context.json，则临时复制 scripts/fake.context.json（内容仅为{"x": "y"}的占位文件）以避免 CLI 上下文提示干扰合成；验证完成后清理该临时文件。这正是 CONTRIBUTING.md 中“确保示例通过cdk synth与本地自动化测试”要求的落地手段。

同目录下的 update-cdk-packages.ts 则负责把各示例中的aws-cdk依赖版本跟随 CLI 模板统一升级，保证仓库示例与最新 CDK 版本同步——这也是各语言package.json（如 csharp/package.json 中锁定aws-cdk: 2.1133.0）能长期可构建的原因。

5.2 快照测试与 asset hash 归一化（SNAPSHOT_TESTING.md）

对于带 Jest 快照测试的 TypeScript 示例，仓库提供了共享工具 typescript/test-utils/normalize-template.ts 来解决“同一基础设施在不同环境下资产哈希不同，导致快照误报”的问题。该工具递归遍历模板，对两类环境相关值做替换（见 normalize-template.ts）：

• S3 资产 Key：S3Key中形如 64 位十六进制串的资产哈希替换为NORMALIZED_ASSET_HASH（带/不带.zip后缀两种模式）；
• Docker 镜像摘要：以sha256:开头的ImageDigest替换为NORMALIZED_IMAGE_DIGEST。

典型用法（摘自 SNAPSHOT_TESTING.md）：

import { App } from 'aws-cdk-lib'; import { Template } from 'aws-cdk-lib/assertions'; import { YourStack } from '../lib/your-stack'; import { normalizeTemplate } from '../../test-utils/normalize-template'; test('YourStack creates the expected resources', () => { const app = new App(); const stack = new YourStack(app, 'TestStack'); const template = Template.fromStack(stack); const normalizedTemplate = normalizeTemplate(template.toJSON()); expect(normalizedTemplate).toMatchSnapshot(); });

若工具文件位于项目目录之外，还需按 SNAPSHOT_TESTING.md 的说明调整tsconfig.json（将rootDir指向../..、通过paths映射../../test-utils/*并在include中加入外部工具文件）。该工具目前已被ec2-instance、inspector2、api-gateway-lambda-token-authorizer、aws-transfer-sftp-server等多个示例的测试引用。指南同时给出最佳实践：始终在快照比较前先归一化、仅在预期变更时才用npm test -- -u更新快照并人工复核 diff。

六、如何向仓库贡献

README 欢迎两类贡献：修复现有示例，或新增示例。完整流程见 CONTRIBUTING.md，关键步骤包括：

1. 基于master最新代码开发，先检索 issue / PR 避免重复；
2. Fork 仓库后聚焦单一改动提交，不要顺带全量重排格式；
3. 确保示例通过cdk synth（如无法通过需在 PR 中说明）并通过 scripts 中的自动化测试；
4. 提交 PR 后关注 CI 结果并跟进评审。

此外仓库通过 semantic.yml 启用了 Semantic Pull Requests（titleOnly: true），PR 标题需符合约定式提交格式；安全类问题则不通过公开 issue 上报。所有示例代码以 Apache 2.0 许可（见 LICENSE）发布，可自由用于学习与二次开发。

七、延伸阅读

• 各语言示例总表：typescript/README.md、python/README.md、csharp/README.md（java、go 区块的索引直接查看各自目录）；
• 贡献与样式规范：CONTRIBUTING.md；
• 快照测试机制：SNAPSHOT_TESTING.md 与 typescript/test-utils/normalize-template.ts；
• CI 合成验证脚本：scripts/synth.sh、scripts/update-cdk-packages.ts。