【免费下载链接】aws-cdk-examplesExample projects using the AWS CDK项目地址https://gitcode.com/gh_mirrors/aw/aws-cdk-examples点击查看免费下载本文以 aws-cdk-examples 仓库的贡献者指南 CONTRIBUTING.md 为核心系统讲解向该官方 CDK 示例仓库贡献代码的完整流程如何规范地报告 Bug 与功能需求、新增一个示例项目所需的目录结构、README.md稳定性横幅Stability Banner的标准写法、各语言的风格约束以及贡献在 scripts/synth.sh、GitHub Actions 工作流.github/workflows/build-pull-request.yml等自动化设施下的实际验证方式。读完本文你将能够独立提交一个符合该仓库审查标准、可被 CI 顺利构建通过的 Pull Request。一、仓库定位与贡献入口README.md 说明aws-cdk-examples 是 AWS 官方的 CDK 示例代码集合按语言分区组织typescript/、python/、csharp/、java/、go/目标是实现语言间示例的完整对等language parity。每个示例演示一种常见的服务实现或基础设施模式。README 中明确欢迎两类贡献修复现有示例与新增示例并指向 CONTRIBUTING.md 作为详细指南。需要说明的是该仓库定位为中级学习资源通常应在阅读过 CDK Developer Guide 或 CDK Workshop 之后再参考。CONTRIBUTING 文档的章节结构为报告 Bug/功能需求、通过 Pull Request 贡献、链接外部示例、风格与格式、寻找可贡献的任务、添加学习资源、行为准则、安全漏洞上报、许可协议。下面逐节展开并结合仓库中的实际配置与脚本给出佐证。二、报告 Bug 与功能需求贡献指南要求在使用 issue tracker 报告 Bug 或建议功能前先检查已有的 open issues 与最近关闭的 issues避免重复上报提交时应尽量包含以下信息可复现的测试用例或步骤序列a reproducible test case or series of steps正在使用的代码版本the version of our code being used与 Bug 相关的任何本地修改any modifications youve made relevant to the bug环境或部署中任何不寻常之处anything unusual about your environment or deployment。仓库通过.github/ISSUE_TEMPLATE/下的表单把上述要求落地为强制字段bug-report.ymlBug 报告表单必填字段包括 Bug 描述、期望行为、当前行为要求附完整错误、未捕获异常、堆栈与日志、复现步骤要求提供可复制粘贴、可直接运行的最小自包含样本即 SSCCE 原则、CDK CLI 版本cdk version输出、Node.js 版本、操作系统以及语言下拉框Typescript / Python / .NET / Java / Go。feature-request.yml功能需求表单必填功能描述与使用场景Use Case可选提交拟议方案并同样要求选择涉及的 CDK 语言。config.yml禁用了空白 issueblank_issues_enabled: false把普通问答类问题引导到 Discussions 的 QA 板块。这些表单与 CONTRIBUTING 中包含尽可能多信息的要求一一对应贡献者无需记忆细节填写表单即可满足信息完整性的预期。三、通过 Pull Request 贡献CONTRIBUTING 给出了发送 PR 前的两项前提与六步流程前提基于master分支的最新源码工作检查已存在与已合并的 PR确认问题未被他人解决。流程Fork 仓库修改源码聚焦于你要贡献的具体变更——如果同时重排全部代码格式维护者将难以聚焦审查你的改动确保你的示例能通过cdk synth或在 PR 中说明为何不能通过确保本地测试通过自动测试检查 scripts 目录使用清晰的提交信息提交到你的 fork发送 PR 并回答 PR 界面中的默认问题关注 PR 中报告的自动 CI 失败并持续参与后续讨论。仓库配套了两个直接可用的模板与约束文件PULL_REQUEST_TEMPLATE.md要求填写变更内容与原因并声明贡献以 Apache 2.0 许可证提交模板注释中直接内嵌了对 CONTRIBUTING.md 的引用。semantic.yml配置titleOnly: true即启用语义化 Pull RequestPR 标题必须符合约定式提交Conventional Commits格式。这意味着 PR 标题的写法会直接影响发布日志的分类提交前需要检查标题格式。另外.github/workflows/下还有close-stale-issues.yml、closed-issue-message.yml、handle-stale-discussions.yml等工作流用于治理陈旧 issue 与讨论长期无人跟进的 PR/issue 可能被自动处理因此贡献指南强调stay involved in the conversation并非空话。CI 如何验证你的 PRBuild Pull Request 工作流PR 提交后build-pull-request.yml 会在pull_request事件上运行其机制与确保cdk synth通过的要求直接对应采用矩阵策略覆盖五种语言csharp、go、python、java、typescript通过tj-actions/changed-files动作获取变更文件忽略 Markdown 与删除文件对每个包含cdk.json的受影响项目目录执行../scripts/build-language.sh构建脚本构建成功的项目会立即清理node_modules与cdk.out产物构建失败则在工作流末尾汇总为 FAILED BUILDS 并以非零码结束整个任务。各语言的工具链版本由.github/actions/setup-language/action.yml这个 composite action 统一固定Go 1.23、Node.js 20、Java 17Corretto 发行版、Python 3.12、.NET 8。从该文件可以推断示例的依赖版本应与此类运行时环境兼容本地使用差异过大的运行时可能出现 CI 与本地行为不一致的情况。本地如何模拟 CIcdk synth与 context 文件仓库根目录的 scripts/synth.sh 揭示了自动合成检查的细节#!/bin/bash set -euxo pipefail scriptdir$(cd $(dirname $0) pwd) export AWS_DEFAULT_REGIONus-east-1 # if cdk.context.json is not provided, copy a fake one fake_contextfalse [ ! -f cdk.context.json ] fake_contexttrue 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就临时拷贝一个占位文件 fake.context.json其内容仅一行x: y以绕开部分需要上下文查询的场景合成结束后再清理。这说明示例必须能通过cdk synth是可在无 AWS 账号、无上下文查询的环境下确定性执行的硬性要求。scripts/README.md 同时提醒这些是维护者支持脚本普通 CDK 用户无需使用。测试快照测试与资产哈希归一化确保本地测试通过自动测试一项在带测试的 TypeScript 示例中有具体落法。以 typescript/lambda-cron 为例其 package.json 定义npm run build执行tsc、npm test执行jest --configjest.config.js而 lambda-cron.test.ts 使用aws-cdk-lib/assertions的Template.fromStack断言资源数量1 个AWS::Lambda::Function、1 个AWS::Events::Rule、函数属性Handler: index.main、Runtime: python3.12、Timeout: 300、IAM 角色与事件规则表达式cron(0 18 ? * MON-FRI *)。对于快照snapshot类测试SNAPSHOT_TESTING.md 指出资产哈希在不同环境间会变化导致快照失败的问题并提供了归一化工具 typescript/test-utils/normalize-template.ts在快照比较前调用normalizeTemplate(template.toJSON())该工具会把S3Key中 64 位十六进制哈希替换为NORMALIZED_ASSET_HASH、把sha256:开头的ImageDigest替换为NORMALIZED_IMAGE_DIGEST对应源码中/^[a-f0-9]{64}\.zip$/等正则判断。贡献带快照测试的示例时应按该文档在比较前归一化模板并只在预期变更时使用npm test -- -u更新快照。新增示例的Added Value标准作为官方学习资源CONTRIBUTING 明确要求新示例不能与已有示例重复且必须满足以下三类价值之一合并时会按这些标准与后续各节的评审标准共同评估记录一种常见基础设施模式如静态网站、定时触发的 Lambda演示某个 L2 构造construct的用法覆盖一个或多个构造不太直观的实现方式如跨 Stack 资源共享、escape hatches、合成期使用 SSM 值等。四、新增示例的必备组件ComponentsCONTRIBUTING 规定新增示例的大部分组件可由cdk init生成必备组件如下。1. 通用目录结构在示例名的空目录中运行npx cdk init app --language [LANGUAGE]生成语言相关组件并保留 init 建议的结构TypeScript 应用的入口在./bin/example-name.ts、Stack 放在./lib/example-name-stack.ts。提交 PR 时目录必须包含所有相关的包管理器与配置文件使他人只需要运行构建命令和cdk deploy即可运行示例。仓库内现成示例印证了这一结构。例如 typescript/lambda-cron 目录包含 index.ts、cdk.json、package.json、tsconfig.json、jest.config.js 与测试文件。其 cdk.json 的app: npx tsc npx tsx index.ts指定了合成入口context段固化了一组 feature flag——这正是cdk init生成、CI 构建时依赖的完整配置文件要求的实例。2. README.md 与稳定性横幅每个示例必须在目录根部有一份完整的README.md必含四部分Stability Banner稳定性横幅、Overview概览、Structure结构、Build/Deploy构建/部署。横幅用于标明示例所依赖构造库的生命周期状态Stable / Dev-Preview / Cfn-Only规则是就低不就高若所有模块都稳定但仅有一个是 dev-preview整个示例必须标记为 dev-preview。CONTRIBUTING 给出了两段可直接复制的横幅代码。Stable 横幅!--BEGIN STABILITY BANNER-- ---  **This is a stable example. It should successfully build out of the box** This example is built on Construct Libraries marked Stable and does not have any infrastructure prerequisites to build. --- !--END STABILITY BANNER--Developer Preview 横幅!--BEGIN STABILITY BANNER-- ---  **This is an experimental example. It may not build out of the box** This example is built on Construct Libraries marked Developer Preview and may not be updated for latest breaking changes. It may additionally requires infrastructure prerequisites that must be created before successful build. If build is unsuccessful, please create an issue so that we may debug the problem --- !--END STABILITY BANNER--仓库中的 typescript/lambda-cron/README.md 是符合规范的范例横幅完整随后给出 Overview创建一个每天 UTC 18:00 按 cron 调度执行的 Lambda、Buildnpm install -g aws-cdk、npm install、npm run build、Testnpm test、Deploycdk deploy与cdk synth查看模板的输出说明。其余三部分的官方要求为Overview 应描述示例创建的资源、使用的标准/常见模式及整体功能Structure 在示例超过单 Stack 或资源较多时必须说明部署结构可以是资源列表也可以是完整架构图Build/Deploy 必须包含该语言下示例的基本构建/部署说明。3. 依赖版本的对齐工具仓库还维护了一个专门的维护工具 scripts/update-cdk-dependencies其 README.md 说明它会把各语言应用的 CDK 依赖更新到已发布cdk init模板推荐的版本Python 更新requirements.txt中的aws-cdk-lib与constructs有pyproject.toml时同步其依赖字符串Java 更新 POM 中software.amazon.awscdk:aws-cdk-lib与software.constructs:constructs的版本文本Go 执行等价于go get github.com/aws/aws-cdk-go/awscdk/v2target加go mod tidy的操作C# 更新Amazon.CDK.Lib与Constructs的 PackageReference。该 CLI 默认 dry-run支持--language、--write、--check、--json参数。虽然这是维护者工具但它从侧面定义了示例依赖版本应当与cdk init推荐策略一致的仓库标准贡献新示例时沿用cdk init生成的依赖版本即天然满足该标准。五、链接外部示例Linking External Examples如果你的示例项目因范围或体量超出本仓库标准而无法直接并入但仍是 CDK 用户有价值的学习资源CONTRIBUTING 允许以外部链接形式贡献向本仓库 README.md 的 Additional Examples 部分发起 PR 添加你的仓库链接该 PR 可用于和 CDK 团队讨论链接仓库的功能与内容。若你的仓库不是学习资源而是基于 CDK 或供 CDK 使用的工具/库则指南建议将其提交到 Awesome CDK 社区清单不在此仓库维护。README 的 Additional Examples 表格目前收录了由 AWS 维护的aws-cdk-changelogs-demo一个用 CDK 部署的完整无服务器 Node.js 应用栈作为该机制的实际条目。六、风格与格式Style and Formatting仓库追求跨语言示例风格一致同时要求代码尽量符合各语言习惯idiomatic。CONTRIBUTING 目前已定义的规则TypeScript可使用 ESLint 的标准配置检查代码语法与风格。Java尽可能使用 builder——部分类因 JSII 限制无法生成 builder但能生成时优先使用 builder 而非手工构造使用 google-java-format 格式化代码VS Code 用户可按 redhat-developer/vscode-java 仓库 issue #419 中的说明配置格式化任务。其余语言的规范将在制定后陆续补充即新增示例应参考对应语言目录下既有示例的风格基线。CI 工作流在构建前会yarn global add eslintlatest说明 ESLint 检查是自动化流程的一部分。七、寻找可贡献的任务与添加学习资源寻找任务浏览现有 issue 是找到可贡献工作的最佳方式。项目使用 GitHub 默认 issue 标签enhancement/bug/duplicate/help wanted/invalid/question/wontfix其中带help wanted标签的 issue 是最合适的起点。添加学习资源主 README 的 Learning Resources 部分维护了一份 CDK 相关学习资源短列表其中 Officially Supported 区段由 CDK 维护者维护如果你有资源workshop、示例集等希望加入列表应创建 PR在描述中说明添加理由维护者会在 PR 评审中与你讨论。指南要求添加资源时做出与新增示例相同的价值评估。README 现有的学习资源包括官方 Developer Guide、API Reference、CDK 主仓库、Construct Hub、CDK Workshop 以及社区维护的 AwesomeCDK 清单。八、行为准则、安全上报与许可行为准则本项目采用 Amazon Open Source Code of Conduct仓库内另有 CODE_OF_CONDUCT.md 提供 FAQ 入口与联系方式。安全漏洞上报发现潜在安全问题时指南明确要求通过 AWS/Amazon 官方的漏洞报告页通知安全团队且不要创建公开的 GitHub issue。许可项目采用 Apache 2.0 许可见 LICENSE 与 NOTICE贡献时会要求你确认贡献的许可较大的变更可能会被要求签署 Contributor License AgreementCLA。这与 PULL_REQUEST_TEMPLATE.md 中我的贡献以 Apache 2.0 许可证提交的确认声明相互呼应。九、贡献自检清单综合 CONTRIBUTING 文档与仓库自动化设施提交 PR 前可按以下清单自检基于master最新源码且已排查重复 issue/PRPR 标题符合语义化 PR 约定参见 semantic.yml 的titleOnly: true配置新示例满足 Added Value 三类标准之一无重复示例目录由npx cdk init app --language [LANGUAGE]起步并保留建议结构包含全部构建所需配置文件本地cdk synth通过可参考 scripts/synth.sh 的固定 region 占位 context 行为做本地验证示例README.md含 Stability Banner按最低模块状态标记、Overview、Structure、Build/Deploy 四要素语言风格符合 TypeScriptESLint 标准配置或 Javabuilder google-java-format约定带测试的示例通过npm test快照测试先经normalizeTemplate归一化再比较本地运行时尽量贴近 CI 固定版本Go 1.23 / Node.js 20 / Java 17 / Python 3.12 / .NET 8见.github/actions/setup-language/action.yml关注 CI 反馈并持续跟进 PR 讨论。以上流程的共同目标是保证仓库作为官方学习资源的定位任何示例都开箱即构建、可被 CI 确定性验证并与其他语言下的对位示例保持风格一致。赞分享【免费下载链接】aws-cdk-examplesExample projects using the AWS CDK项目地址https://gitcode.com/gh_mirrors/aw/aws-cdk-examples点击查看免费下载相关推荐Apache DolphinScheduler E2E 测试贡献指南从 Issue 认领到用例编写与提交Apache DolphinScheduler E2E 测试贡献指南从 Issue 认领到用例编写与提交 Apache DolphinScheduler 社区任务调度大数据后端前端gevent 贡献指南从提交代码到通过 CI 全流程实践gevent 贡献指南从提交代码到通过 CI 全流程实践 gevent 是基于协程greenlet的 Python 并发库它的核心价值在于用同步的编程模后端Firejail 贡献指南从提交 Issue 到编写安全 Profile 的完整实践路径Firejail 贡献指南从提交 Issue 到编写安全 Profile 的完整实践路径 Firejail 是一个基于 Linux namespaces 与应用安全操作系统上一篇SkyPilot API Server 多云部署实战在 GKE 上以 Okta 认证统一管理 GCP 与 Nebius GPU 资源下一篇Terragrunt Strict Mode 严格模式实战指南将废弃功能警告升级为错误保障代码面向未来创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
