AWS SDK for Kotlin 代码示例仓库使用指南：从环境搭建到跨服务应用开发

• 示例工程
• 教程
• 后端

本指南以开源仓库aws-doc-sdk-examples中 kotlin/README.md 为骨架，系统讲解如何基于 AWS SDK for Kotlin（beta 版）构建、运行与测试 AWS 服务代码示例。你将掌握 Gradle 项目搭建、JUnit 测试配置、50 余个服务级示例的组织方式，并通过多服务 Usecases 教程深入理解 Spring REST + React 前端 + AWS 服务（SQS、DynamoDB、Rekognition、Step Functions 等）的组合开发模式。

仓库概览：Kotlin 示例代码的组织方式

本仓库的 Kotlin 部分位于根目录下的kotlin/文件夹，由以下核心部分组成：

• kotlin/services：按 AWS 服务组织的独立 Gradle 工程，每个目录包含该服务的单操作（Single actions）、基础场景（Basics）与多操作场景（Scenarios）示例代码，共覆盖 50 余个 AWS 服务，包括 S3、DynamoDB、SQS、SNS、Lambda、EC2、IAM、Rekognition、Comprehend、Bedrock、Step Functions 等；
• kotlin/usecases：端到端的分步开发教程，每个教程组合多个 AWS 服务，演示如何构建真实可运行的应用；
• kotlin/Dockerfile 与 kotlin/run_tests.sh：容器化构建与自动化测试脚本；
• kotlin/premium-ex.md：用于工作流消费的高质量示例索引，标记了基础示例（如iotfleetwise）与特性场景（如 PartiQL 相关场景）。

根 README 明确指出这些示例演示的是beta 版 AWS SDK for Kotlin的服务操作，因此在阅读源码时如果遇到 API 与当前正式版略有差异，属于正常现象，应以各服务目录下的 README 为准。

环境准备（Prerequisites）

运行这些示例之前，必须满足以下前提：

1. AWS 账号：拥有一个可用的 AWS 账号；
2. 凭据与区域：已按 AWS SDK for Kotlin 开发者指南完成默认凭据（credentials）和默认 AWS 区域的配置。SDK 会通过环境变量、共享凭据文件等方式自动发现默认配置；
3. 开发环境：从示例的 kotlin/usecases/creating_message_application/README.md 的实操教程可以归纳出典型环境组合：Kotlin IDE（如 IntelliJ IDEA，需安装 Kotlin 插件）、Java 17 JDK、Gradle 8.1 或更高版本，以及完成 AWS SDK for Kotlin 的 设置流程。

在配置凭据时，建议遵循最小权限原则（least privilege），即仅授予完成任务所需的最小权限，并注意部分 AWS 服务仅在特定区域可用。

使用 Gradle 构建与运行示例

根 README 推荐使用Gradle来配置和构建 AWS SDK for Kotlin 工程。仓库中的每个服务目录都是一个独立的 Gradle 工程，例如 kotlin/services/s3/settings.gradle.kts 中仅包含一行工程声明：

rootProject.name = "s3"

而在多服务教程（如 SQS 消息应用）中，build.gradle.kts的完整依赖配置如下（摘自 kotlin/usecases/creating_message_application/README.md）：

import org.jetbrains.kotlin.gradle.tasks.KotlinCompile plugins { kotlin("jvm") version "1.9.0" application } group = "me.scmacdon" version = "1.0-SNAPSHOT" java { sourceCompatibility = JavaVersion.VERSION_17 targetCompatibility = JavaVersion.VERSION_17 } buildscript { repositories { maven("https://plugins.gradle.org/m2/") } dependencies { classpath("org.jlleitschuh.gradle:ktlint-gradle:10.3.0") } } repositories { mavenCentral() jcenter() } apply(plugin = "org.jlleitschuh.gradle.ktlint") dependencies { implementation("aws.sdk.kotlin:sqs:0.33.1-beta") implementation("aws.sdk.kotlin:comprehend:0.33.1-beta") implementation("aws.smithy.kotlin:http-client-engine-okhttp:0.28.0") implementation("aws.smithy.kotlin:http-client-engine-crt:0.28.0") implementation("org.springframework.boot:spring-boot-starter-web:2.7.3") implementation("com.fasterxml.jackson.module:jackson-module-kotlin:2.13.3") implementation("org.jetbrains.kotlin:kotlin-reflect") implementation("org.jetbrains.kotlin:kotlin-stdlib-jdk8") testImplementation("org.springframework.boot:spring-boot-starter-test:2.7.3") } tasks.withType<KotlinCompile> { kotlinOptions { freeCompilerArgs = listOf("-Xjsr305=strict") jvmTarget = "17" } } tasks.withType<Test> { useJUnitPlatform() }

其中关键的几项值得说明：

• aws.sdk.kotlin:sqs、aws.sdk.kotlin:comprehend等以aws.sdk.kotlin为 group 的依赖，正是 AWS SDK for Kotlin 各服务模块（此处为 beta 版本号0.33.1-beta）；
• aws.smithy.kotlin:http-client-engine-okhttp与http-client-engine-crt是 SDK 底层使用的 HTTP 客户端引擎；
• org.jetbrains.kotlin:kotlin-reflect与kotlin-stdlib-jdk8保证 Kotlin 运行时与反射能力；
• tasks.withType<Test> { useJUnitPlatform() }启用 JUnit 5 平台，与后文测试章节呼应。

以 S3 基础场景为例的运行方式

每个服务的"基础场景"示例一般提供带命令行参数的main函数。以 kotlin/services/s3/src/main/kotlin/com/kotlin/s3/S3Operations.kt 为例，它通过suspend fun main接收 5 个位置参数，按顺序完成一条完整的 S3 生命周期链路：

suspend fun main(args: Array<String>) { val usage = """ Usage: <bucketName> <key> <objectPath> <savePath> <toBucket> Where: bucketName - The Amazon S3 bucket to create. key - The key to use. objectPath - The path where the file is located (for example, C:/AWS/book2.pdf). savePath - The path where the file is saved after it's downloaded (for example, C:/AWS/book2.pdf). toBucket - An Amazon S3 bucket to where an object is copied to (for example, C:/AWS/book2.pdf). """ if (args.size != 4) { println(usage) exitProcess(1) } val bucketName = args[0] val key = args[1] val objectPath = args[2] val savePath = args[3] val toBucket = args[4] createBucket(bucketName) putObject(bucketName, key, objectPath) getObjectFromMrap(bucketName, key, savePath) listBucketObs(bucketName) copyBucketOb(bucketName, key, toBucket) deleteBucketObs(bucketName, key) deleteBucket(bucketName) println("All Amazon S3 operations were successfully performed") }

该场景对应的操作清单为（见 kotlin/services/s3/README.md）：

1. 创建桶并上传文件；
2. 从桶中下载对象；
3. 将对象复制到桶的子文件夹；
4. 列出桶内对象；
5. 删除桶对象与桶本身。

每个操作函数都遵循 AWS SDK for Kotlin 的统一调用模式：使用S3Client.fromEnvironment { region = "us-east-1" }.use { ... }构建客户端，通过CreateBucketRequest { bucket = bucketName }这类 Kotlin DSL 构造请求，再调用对应方法。例如putObject（见 S3Operations.kt）：

suspend fun putObject( bucketName: String, objectKey: String, objectPath: String, ) { val metadataVal = mutableMapOf<String, String>() metadataVal["myVal"] = "test" val request = PutObjectRequest { bucket = bucketName key = objectKey metadata = metadataVal this.body = Paths.get(objectPath).asByteStream() } S3Client.fromEnvironment { region = "us-east-1" }.use { s3 -> val response = s3.putObject(request) println("Tag information is ${response.eTag}") } }

注意这里通过asByteStream()将本地文件转换为请求体，体现了 Kotlin SDK 基于aws.smithy.kotlin运行时提供的流式类型支持。use扩展函数确保客户端在使用完毕后自动释放底层资源。

运行 JUnit 测试

根 README 的 Tests 章节说明，所有示例均配备 JUnit 测试，你可以：

• 从 IDE（如 IntelliJ）直接运行；
• 或从命令行运行。

每个测试运行时会输出成功/失败信息，例如Test 3 passed表示第 3 个测试通过。

关键前提：运行 JUnit 测试前，必须在resources文件夹下的config.properties文件中定义所有必需的值。该文件保存测试运行所需的参数（如桶名、表名、队列 URL 等）；如果存在未定义的项，相关 JUnit 测试将失败。

仓库还提供了自动化测试脚本 kotlin/run_tests.sh，其逻辑是递归遍历kotlin/services下所有包含build.gradle.kts的子目录并执行gradle test：

run_gradle_tests() { for dir in "$1"/*/; do if [[ -f "$dir/build.gradle.kts" ]]; then echo "Running gradle build test in $dir" (cd "$dir" && gradle test) fi if [[ -d "$dir" ]]; then run_gradle_tests "$dir" # Recursively call function for sub-directories fi done } root_dir="/kotlin/services"

这套脚本与 Docker 镜像配合，可在隔离容器中批量验证所有服务的测试是否通过。

服务级代码示例总览

kotlin/services目录按服务拆分了大量独立示例，主要覆盖（完整目录见 kotlin/services）：

每个服务目录都包含README.md、src/main/kotlin源码与src/test/kotlin测试，且 README 中为每个操作标注了对应源码文件与起始行号，便于按图索骥。

S3：单操作、基础场景与场景示例

以 S3 为例（见 kotlin/services/s3/README.md），其示例分为三层：

• 单操作（Single actions）：CopyObject、CreateBucket、DeleteBucketPolicy、DeleteObjects、GetBucketPolicy、GetObject、GetObjectAcl、ListObjectsV2、PutBucketAcl、PutObject等，每个都对应一个独立的.kt文件（如 CopyObject.kt、PutObject.kt）；
• 基础场景（Basics）：即上文演示的 S3Operations.kt 完整生命周期；
• 场景（Scenarios）：PresigningExamples.kt（生成预签名 URL 并上传对象）与 MrapExample.kt（从 Multi-Region Access Point 获取对象），后者还配有对应的测试 MrapExampleTest.kt 与 PresignTests.kt。

DynamoDB：基础场景与 PartiQL 场景

DynamoDB 目录（见 kotlin/services/dynamodb/README.md）展示了：

• 基础场景 Scenario.kt：建表（movie 数据）→ 写入/读取/更新单条记录 → 从 JSON 批量载入 → 按年份 Query → 按年份区间 Scan → 删除记录与删表；
• 单操作示例：CreateTable、DeleteItem、DeleteTable、GetItem、ListTables、PutItem、QueryTable、DynamoDBScanItems、UpdateItem等；
• PartiQL 场景：ScenarioPartiQ.kt（SELECT/INSERT/UPDATE/DELETE 单条语句）与 ScenarioPartiQLBatch.kt（批量执行多条语句）。这两个文件同时被 kotlin/premium-ex.md 标记为 feature-scenario 与 complex-feature-scenario 级别的优质示例。

多服务 Usecases 教程（跨服务应用开发）

kotlin/usecases目录收录了根 README 重点推荐的端到端教程。每一个教程都组合多个 AWS 服务，适合希望掌握真实应用开发的开发者：

这些教程普遍采用"Spring REST API 后端 + React/移动端前端"的解耦架构，是理解 AWS SDK for Kotlin 在真实业务中落地的理想素材。

深度示例：SQS 消息应用（Spring REST + React）

以根 README 列出的首个教程为例，creating_message_application 展示了一条完整链路：React SPA 通过 RESTful GET/POST 请求调用 Spring REST API，Spring 控制器使用aws.sdk.kotlin.services.sqs.SqsClient将消息写入FIFO 队列（保证先进先出顺序），并用 Amazon Comprehend 检测消息的语言代码。

其核心工作流程如下：

1. 用户在 React 界面输入 message 与 user，点击Send Message；
2. 消息被 POST 到 Spring REST 端点；
3. Spring 控制器构造MessageData对象（包含 GUID 形式的消息 ID、消息文本、用户名）；
4. 控制器将MessageData交给消息服务，通过SqsClient存入 FIFO 队列；
5. REST 端点调用receiveMessage方法读取队列中全部消息，将List<MessageData>以 JSON 返回给 React 前端展示。

消息服务类SendReceiveMessages（README 全文 中给出完整代码）的关键实现展示了三个 API 调用模式：

• 获取队列 URL 再操作：GetQueueUrlRequest { queueName = "Message.fifo" }→sqsClient.getQueueUrl(...)；
• 接收消息（长轮询）：ReceiveMessageRequest { maxNumberOfMessages = 10; waitTimeSeconds = 20; messageAttributeNames = attr }，通过waitTimeSeconds = 20启用长轮询以减少空轮询开销，同时读取自定义消息属性Name；
• 发送消息（FIFO 必需参数）：SendMessageRequest { messageGroupId = "GroupA_$lanCode"; messageDeduplicationId = msg.id; messageBody = msg.body }。FIFO 队列要求必须同时提供messageGroupId（消息组）与messageDeduplicationId（去重 ID），此处去重 ID 复用应用生成的 UUID，而消息组 ID 动态拼接了 Comprehend 检测出的语言代码：

  ComprehendClient { region = "us-west-2" }.use { comClient -> val resp = comClient.detectDominantLanguage( DetectDominantLanguageRequest { text = msg.body } ) // 取 resp.languages 中的 languageCode }

Spring 控制层（MessageResource，位于App.kt同文件）使用runBlocking将挂起（suspend）的 SDK 调用桥接到 Spring MVC 的同步请求处理模型，并暴露三个端点：

• GET /chat/msgs：返回队列中所有消息；
• POST /chat/add?user=xxx&message=xxx：向队列添加新消息；
• GET /chat/purge：清空队列（调用PurgeQueueRequest）。

React 前端通过修改AwsService.js中的BASE_URL指向 Spring 应用端口，并用 axios 发起请求：

export const getMessages = async () => { return await axios.get(`${configData.BASE_URL}/chat/msgs`); }; export const postMessage = async (item) => { let user = item.username; let message = item.message; await axios.post( `${configData.BASE_URL}/chat/add?user=` + user + `&message=` + message ); }; export const purgeMessages = async () => { await axios.get(`${configData.BASE_URL}/chat/purge`) }

实操时，请先在 AWS 控制台创建名为Message.fifo的 FIFO 队列，并预置 4 条样例消息（每条均指定 Message body、Message group ID、Message deduplication ID 与 Message Attributes，例如"I am going swimming soon"/ group1/ dedup1/ 属性"Name":"lam"），以便在启动应用后立即看到数据。运行 Spring 应用后，可在浏览器访问http://localhost:8080/chat/msgs验证 JSON 输出。

Docker 镜像（Beta）与容器化测试

根 README 提到示例代码即将以容器镜像形式发布在 Amazon ECR 上，镜像会预置全部 Kotlin 示例并预解析依赖，让你可以在隔离环境中直接探索。截至 2023 年 1 月，该镜像已可用但仍处于积极开发阶段。

仓库中的 kotlin/Dockerfile 展示了这一容器化思路的实现：

FROM gradle:latest RUN apt-get update && \ apt-get upgrade -y && \ apt-get clean && \ rm -rf /var/lib/apt/lists/* COPY . /kotlin RUN useradd -m automation && \ chown -R automation:automation /kotlin USER automation:automation CMD ["/kotlin/run_tests.sh"]

其要点是：

• 基于官方gradle镜像构建，免去本地安装 Gradle 的步骤；
• 将仓库整体拷贝到容器内/kotlin，并创建非 root 用户automation以安全方式运行；
• 容器启动即执行 kotlin/run_tests.sh，递归运行所有服务的 Gradle 测试，实现对全部示例的批量验证。

注意事项与成本提示

根 README 的 Notes 部分强调了三条重要事项，编写或运行示例时务必遵守：

1. 最小权限原则：建议为代码授予 least privilege（即完成任务的必要最小权限）；
2. 区域可用性：这些示例并未在所有 AWS 区域经过测试，部分 AWS 服务仅在特定区域可用；
3. 费用风险：运行这些代码可能会在 AWS 账号中产生费用，尤其要注意运行测试同样可能产生费用；教程类应用在体验后应及时删除所创建的资源（S3 桶、DynamoDB 表、SQS 队列、IAM 角色等），避免持续计费。

总结

kotlin/目录是 AWS SDK for Kotlin 官方示例的完整载体：从单服务的基础操作，到 PartiQL、预签名 URL、Multi-Region Access Point 等进阶场景，再到 Spring REST + React 的多服务全栈教程，配合 Gradle 构建、JUnit 测试与容器化运行脚本，构成了一条从"看懂 API"到"写出真实应用"的完整学习路径。建议的阅读顺序是：先按 kotlin/README.md 配置环境 → 用 Gradle 运行 services/s3 或 services/dynamodb 的基础场景 → 再进入 usecases 跟随端到端教程动手实践。

• 示例工程
• 教程
• 后端