aws-doc-sdk-examples 仓库完全指南：多语言 AWS SDK 示例的组织、运行与贡献-平芜编程栈

示例工程
教程
后端

【免费下载链接】aws-doc-sdk-examples

Welcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.

项目地址：https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples

点击查看免费下载

本篇指南围绕 AWS Code Examples Repository（仓库根目录 README.md）展开，系统讲解这个为 AWS 官方文档与各语言 SDK 开发者指南提供代码示例的开源仓库：从顶层目录结构与 SDK 版本对照，到示例代码的调用前提、运行方式、测试体系，再到贡献与示例请求的流程规范。读完本文，你将能够快速定位任意语言、任意 AWS 服务的示例代码，掌握在多语言目录中运行与测试示例的通用方法，并理解该仓库的质量保障机制与许可边界。

仓库定位：面向 AWS 文档与开发者的代码示例集

根目录 README.md 开宗明义地指出：这个仓库包含用于演示如何通过 AWS SDK 与 AWS 服务交互的代码示例，其中大量示例被直接注入到 AWS 官方文档中。这意味着仓库中的代码并非孤立的教学片段，而是 AWS Documentation、AWS SDK Developer Guides 等官方内容背后的"活素材"。

从实际仓库结构看，这一定位体现在两方面：

覆盖面广：从 C++ 到 Swift，从经典的 SDK v1 到 v3/v4，仓库覆盖了 .NET、C++、Go、Java、JavaScript、Kotlin、PHP、Python、Ruby、Rust、Swift 等多语言生态，还包含sap-abap/、aws-cli/、aws-cfn/等非传统 SDK 的示例。
与文档联动：多数示例遵循"单服务动作（action）— 单服务场景（scenario）— 跨服务示例（cross-service）"的层级组织，这种结构正是为了便于 AWS 文档按场景引用。

仓库组织结构：按语言 SDK 与版本分区

README 用一张清晰的对照表定义了各语言子目录与 SDK 版本的对应关系，这是导航整个仓库的第一把钥匙：

SDK	目录	SDK 版本
.NET	dotnetv3/	3.5+
.NET	.dotnet/	<3.5
C++	cpp/	1
Go	gov2/	2
Go	go/	1
Java	javav2/	2
Java	java/	1
JavaScript	javascriptv3/	3
JavaScript	javascript/	2
Kotlin	kotlin/	1
PHP	php/	3
Python	pythonv1/	1
Python	python/	3
Ruby	ruby/	3
Rust	rustv1/	1
Swift	swift/	preview

需要留意两个容易混淆的点：

同名语言、不同版本并存：例如 Go 同时存在 go/（v1 SDK）与 gov2/（v2 SDK）；Python 同时存在 pythonv1/（v1 SDK）与 python/（v3 SDK，即 Boto3）。选错目录会导致 API 调用方式与示例不匹配。
JavaScript 目录命名：README 表格中javascript/一栏的目录链接实际指向 javascriptv3/（v2 SDK 示例），而 v3 SDK 的示例在 javascriptv3/。选择前请先确认你使用的 SDK 大版本。

README 同时给出了一条重要的维护状态提示（NOTE）：按照 AWS 的 SDKs and Tools Maintenance Policy，AWS SDK for Java v1.x 已于 2024 年 7 月 31 日进入维护模式，并将在 2025 年 12 月 31 日停止支持。因此 java/ 目录下的 v1 示例更适合作为迁移参考，新项目应优先使用 javav2/。

每个语言目录内部都带有"SDK 专属的说明"，用于指导理解与调用对应示例。以 python/README.md 为典型代表，它进一步细化了示例的组织方式：

单服务动作（Single-service actions）：演示如何调用单个服务函数，按服务存放在 python/example_code 目录，每个服务子目录的 README 说明运行方式；
单服务场景（Single-service scenarios）：在同一服务内通过多次函数调用完成某个具体任务；
跨服务示例（Cross-service examples）：跨多个 AWS 服务协同工作的示例应用，集中在 python/cross_service 目录。

这种"动作 — 场景 — 跨服务"的三层分类，在多数语言目录（如 dotnetv3/、kotlin/、javascriptv3/）中都能看到对应的目录形态，是整个仓库共用的组织范式。

附加目录：生产级应用、共享资源与测试框架

除语言目录外，README 还说明了三个跨语言共享的附加目录：

目录	用途	使用方式
applications/	存放与语言无关的生产级示例应用组件，展示 SDK 在生产式应用中的用法	各应用的语言侧实现见对应语言子目录下的`cross-service`目录
.tools/（原 README 所述 test 目录）	支撑仓库例行测试的自定义测试自动化框架组件，以容器化的多语言集成测试方案部署到 AWS	目前仍在持续建设中
resources/	供仓库内大量示例共享的公共组件	以前端（resources/clients）或后端（resources/cdk、resources/cfn）组件形式部署

生产级应用示例（applications）

applications/README.md 给出了两个完整的、跨语言的"生产级"示例应用：

名称	路径	支持语言	重点服务
Photo Asset Manager	applications/photo-asset-manager	C++、.NET、Java、JavaScript、Rust	Amazon Rekognition、Amazon API Gateway、Amazon CloudFront、Amazon Cognito、Amazon S3
Feedback Sentiment Analyzer	applications/feedback_sentiment_analyzer	Ruby、JavaScript	Amazon Textract、Amazon Comprehend、Amazon Translate、Amazon Polly、AWS Step Functions

每个应用遵循统一的内容约定，便于扩展与复刻：AWS CloudFormation（CFN）与 AWS Cloud Development Kit（CDK）提供自动/半自动的资源创建脚手架；每个示例至少有一个功能用多种语言实现；多数带有前端组件；并配套四份文档——README.md（部署与使用概览）、SPECIFICATION.md（架构与业务逻辑）、DEVELOPMENT.md（如何用另一种语言扩展该应用）、README_TEMPLATE.md（语言侧 README 的模板）以及DESIGN.md（开发决策记录）。例如 applications/photo-asset-manager 与 applications/feedback_sentiment_analyzer 根目录下均完整携带这些文件。

共享资源目录（resources）

resources/ 是支撑大量示例的公共资产库，从当前仓库结构看可细分为：

resources/cdk：面向具体示例的 CDK 堆栈集合，覆盖 DynamoDB 数据表、Lambda + API Gateway、S3 事件通知、SQS SSE-KMS 加密、Textract 视频分析、Rekognition 无认证角色、Step Functions 演示等约三十个场景，例如cognito_scenario_user_pool_with_mfa/、lambda_using_api_gateway/、textract_example_s3_sns_sqs/；
resources/cfn：CloudFormation 模板集合，目前包含entity-resolution-basics/、iotsitewise_basics/、s3_express_basics/等基础场景；
resources/clients：前端组件，如 resources/clients/react；
resources/sample_files：示例代码运行所需的样例文件。

测试与工程化基础设施

README 提及的自定义测试自动化框架，在仓库中对应 .tools/ 目录，内含测试栈（.tools/test）、Docker 镜像（.tools/docker-images）、校验工具（.tools/validation）、脚本与代码片段等。此外，多数语言目录自带测试工具链，例如 python/test_tools 提供了统一的测试运行入口（见下文"测试体系"一节）。

运行示例代码的前提条件

README 明确指出，要调用这些示例代码，必须满足两个前提：

拥有 AWS 账户：示例会真实创建、修改乃至删除 AWS 资源，需要可用的账户环境；
配置 AWS 凭据：需要完成 AWS CLI 的配置基础流程（configure credentials），通常即配置aws_access_key_id、aws_secret_access_key与默认区域，写入本地凭据文件。

以 python/README.md 为例，具体的前置条件还包括：Python 3.6.0 或更高版本，以及按 AWS Tools and SDKs Shared Configuration and Credentials Reference 配置好的默认凭据与区域。

通用运行流程（以 Python 为例）

绝大多数 Python 示例目录都带有requirements.txt，标准流程如下：

python -m venv .venv

激活虚拟环境（按操作系统选择）：

.venv\Scripts\activate # Windows source .venv/bin/activate # Linux, macOS, or Unix

安装依赖：

python -m pip install -r requirements.txt

运行示例。多数示例含__main__入口，可直接执行：

python file_with_main.py

需要命令行参数的示例，可先运行python file_with_main.py -h查看帮助；每个示例目录的 README 还会给出更具体的运行说明与其他前置条件。

测试体系：单元测试与集成测试分离

仓库的测试策略是"单元测试零成本、集成测试真上云"。

单元测试：以 Python 为例，单元测试使用 botocore Stubber 打桩返回 mock 响应，请求不会真正发送到 AWS，因此运行单元测试不会产生费用。在各示例目录下通过排除integ标记运行：

python -m pytest -m "not integ"

集成测试：集成测试会向 AWS 发送真实请求，可能创建与销毁账户内资源并产生费用。运行方式为显式指定integ标记：

python -m pytest -m "integ"

仓库还提供了批量化运行测试的入口，例如 python/test_tools/run_all_tests.py 可在一个 Docker 容器内运行全部单元测试，也支持通过-m "integ"标志执行集成测试。在多语言仓库层面，cpp/run_automated_tests.py、.tools/test 等共同构成了容器化的多语言集成测试体系。

Docker 化运行方式

Python 语言目录提供预构建的容器镜像，镜像内预装了全部 Python 示例并解析好依赖，便于在隔离环境中探索。构建与启动命令为：

docker build -t <image_name> . # 在 python/ 目录下执行 docker run -it -v ~/.aws/credentials:/root/.aws/credentials <image_name>

容器启动后进入 bash，示例代码位于容器内的python目录。其他语言目录（如 cpp/Dockerfile、javascriptv3/Dockerfile、rustv1/Dockerfile）同样提供了 Dockerfile，印证了仓库"容器化交付示例"的统一思路。

场景目录：基础场景与功能场景的沉淀

除按语言组织的示例外，仓库还提供了跨语言、面向业务场景的沉淀目录 scenarios/：

scenarios/basics：基础能力场景，涵盖 Amazon S3、S3 Express、Redshift、OpenSearch、GuardDuty、Batch、Control Tower、ECR、IoT、KMS、Location、Neptune、SSM、SiteWise、Inspector、Entity Resolution 等服务的入门用例；
scenarios/features：进阶功能场景，例如 Bedrock Converse Tool、EventBridge Scheduler、Firehose、Resilient Service、S3 Conditional Requests、S3 Object Lock、SageMaker Pipelines、SESv2 邮件、SNS/SQS 主题与队列、User Pools 与 Lambda 触发器、CloudWatch Logs 大查询等。

这些场景文档（每个以.md呈现）通常描述"跨语言的能力说明 + 各语言实现路径"，是阅读各语言示例前快速理解业务目标的最佳入口。例如 scenarios/features/topics_and_queues 与各语言目录下的topics_and_queues交叉服务示例相互呼应。

使用免责声明与成本提醒

README 以醒目的方式给出了两条使用警示，属于必读的合规信息：

费用风险：这些代码示例会与 AWS 服务交互，可能对你的账户产生费用，需参考 AWS Pricing 评估成本；
资源风险：示例代码理论上可能修改或删除现有的 AWS 资源。作为尽职调查，请务必做到：清楚了解这些示例会创建或删除哪些资源；了解由此可能产生的账户费用；备份重要数据。

python/README.md 还补充了权限最佳实践：建议按最小权限原则（least privilege）授权，只授予完成任务所需的最低权限；并提醒示例并非在每个 AWS 区域都经过测试。在开发环境或正式账户中运行示例前，务必阅读对应目录的 README 与场景文档，确认其资源清单。

贡献与示例请求流程

仓库欢迎社区贡献，README 与 CONTRIBUTING.md 共同定义了参与方式：

贡献代码：通过 Pull Request 提交，贡献者应先阅读 CONTRIBUTING.md 与行为准则（仓库根目录 CODE_OF_CONDUCT.md）；
请求示例：通过 Issue tracker 提交 enhancement 类型的请求。团队会从三个维度评估所有请求——清晰度（Clarity）、相关性（Relevance）、可行性（Feasibility），据此确定优先级并分配资源；清晰、相关且能在合理时间内完成的请求优先，附带高质量 PR 会显著提高请求被受理的概率；
时间要求：所有示例请求应尽早提出，对于较大的示例，至少应在需求日期前两个月提交；
优先级说明：Bug 修复与安全问题等请求优先于新示例的开发；团队自身有限资源与内部优先级也会影响排期。

多语言贡献时需遵循各语言的工程规范，例如 Python 代码使用 pylint，并通过 CI（如 .github/workflows 下的 lint 工作流）对变更文件自动执行检查。

上游来源（Tributaries）机制

README 用一个形象的比喻解释了 AWS 文档中代码示例的来源：除本仓库外，还有若干"支流"汇入 AWS 文档这条"大河"，包括本仓库（awsdocs/aws-doc-sdk-examples）、serverless-snippets（AWS Samples 组织）以及 AWS Tools for PowerShell 等。这意味着，在 AWS 官方文档中看到的代码，可能来自多个上游仓库，本仓库是其中最主要的一个。查找示例时，如果在本仓库未找到某段文档代码，可以留意它是否来自上述其他上游来源。

版权与许可证

除非另有说明，仓库内所有内容版权归 Amazon Web Services, Inc. 及其关联公司所有。除特别注明外，所有示例依据 Apache License 2.0 授权（完整文本见仓库根目录 LICENSE 文件）。许可证要求在所有可能的文件顶部包含如下许可文本：

Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0

结语：从导航到实践

概括而言，在 aws-doc-sdk-examples 仓库中高效工作只需三步：先依据 README 的 SDK 版本对照表定位正确的语言目录与版本；再通过目录内 README 与 scenarios/ 场景文档找到目标示例及其运行说明；最后按各语言标准流程（虚拟环境、依赖安装、pytest/Docker 测试）运行与验证。无论是学习 AWS SDK 用法、为文档提供示例，还是基于 applications/ 中的生产级应用做二次开发，这个仓库都是最直接的起点。

示例工程
教程
后端

【免费下载链接】aws-doc-sdk-examples

Welcome to the AWS Code Examples Repository. This repo contains code examples used in the AWS documentation, AWS SDK Developer Guides, and more. For more information, see the Readme.md file below.

项目地址：https://gitcode.com/gh_mirrors/aw/aws-doc-sdk-examples

点击查看免费下载