企业官网建设流程全解析

• 示例工程
• 教程
• 后端

导读

本文以 AWS 官方代码示例仓库aws-doc-sdk-examples中 kotlin/services/secrets-manager 目录下的示例为核心，系统讲解如何使用 AWS SDK for Kotlin 安全地加密、存储与检索 AWS Secrets Manager 中的凭据。你将掌握GetSecretValue单操作的完整代码结构、客户端初始化方式、Gradle 构建配置以及 JUnit 测试的运行方法，可直接将示例迁移到自己的 Kotlin 应用中用于数据库口令、API 密钥等敏感凭据的读取。

Secrets Manager 与 SDK for Kotlin 示例概览

AWS Secrets Manager 是一项托管密钥管理服务，帮助用户安全地加密、存储和检索数据库及其他服务的凭据。它支持自动轮换密钥、细粒度访问控制，并可与 IAM、KMS 深度集成，避免把明文口令硬编码在应用代码或配置文件中。

本仓库的 README 展示了如何使用 AWS SDK for Kotlin 与 Secrets Manager 交互，目前收录了一个**单一操作（Single action）**示例——GetSecretValue，即通过密钥名称读取密钥内容。整个目录结构如下：

kotlin/services/secrets-manager/ ├── README.md ├── build.gradle.kts └── src/ ├── main/kotlin/com/kotlin/secrets/GetSecretValue.kt └── test/kotlin/SecretsManagerKotlinTest.kt

从源码结构看，该模块遵循标准的 Gradle JVM 工程布局，主程序与测试分离，依赖通过 build.gradle.kts 统一管理。

⚠ 运行前必须了解的成本与安全注意事项

原 README 中特别强调了四类注意事项，在运行本示例或将其用于生产环境前务必阅读：

• 费用风险：运行本代码（以及运行测试）可能会在你的 AWS 账户中产生费用，请先了解 AWS 定价与免费套餐政策，避免意外账单。
• 最小权限原则（least privilege）：建议为代码授予最小必要权限——仅授予完成当前任务所需的 IAM 权限即可。例如读取密钥只需要secretsmanager:GetSecretValue操作，不需要附加管理员权限。
• 区域可用性：本代码并未在所有 AWS 区域进行测试。部分 AWS 服务仅在特定区域可用，部署前应查阅区域服务清单确认目标区域支持 Secrets Manager。
• 凭据配置：运行前必须先在本地配置 AWS 默认凭据与区域，具体方式参见 SDK for Kotlin 的开发者指南。这也是SecretsManagerClient在代码中以fromEnvironment方式创建的前提。

这些注意事项同样适用于本目录下的 JUnit 测试——测试会真实调用 Secrets Manager 服务，因此同样可能产生费用。

前置条件：环境与账号准备

根据 kotlin 目录总 README 中的 Prerequisites 说明，运行本示例需要满足：

1. AWS 账户，并已按 AWS SDK for Kotlin 开发者指南完成默认凭据与默认区域的配置；
2. Kotlin 开发环境，推荐使用 Gradle 来配置和构建 AWS SDK for Kotlin 项目，具体可参考 "Get started with the AWS SDK for Kotlin" 指南；
3. 一个已存在的 Secrets Manager 密钥，作为GetSecretValue的读取目标。

前置条件细节可查看 README 的对应章节。

单一操作：GetSecretValue 完整实现剖析

源码文件与包结构

示例主程序位于 GetSecretValue.kt，包名为com.kotlin.secrets。文件顶部引入了三个关键依赖：

import aws.sdk.kotlin.services.secretsmanager.SecretsManagerClient import aws.sdk.kotlin.services.secretsmanager.model.GetSecretValueRequest import kotlin.system.exitProcess

• SecretsManagerClient：SDK for Kotlin 提供的 Secrets Manager 服务客户端；
• GetSecretValueRequest：封装getSecretValue请求的请求模型，用于指定要读取的密钥标识；
• exitProcess：用于参数校验失败时的进程退出。

main 入口与参数校验

suspend fun main(args: Array<String>) { val usage = """ Usage: <secretName> <secretValue> Where: secretName - The name of the secret (for example, tutorials/MyFirstSecret). """ if (args.size != 1) { println(usage) exitProcess(0) } val secretName = args[0] getValue(secretName) }

需要说明的是，代码中的 usage 文本仍保留了<secretValue>占位符，但实际校验逻辑要求恰好一个命令行参数（args.size != 1即退出），因此程序运行时只需传入密钥名称，例如：

gradle run --args="tutorials/MyFirstSecret"

密钥名称的典型格式如tutorials/MyFirstSecret，可通过 Secrets Manager 控制台或 AWS CLI 预先创建。

核心调用链：getValue

suspend fun getValue(secretName: String?) { val valueRequest = GetSecretValueRequest { secretId = secretName } SecretsManagerClient.fromEnvironment { region = "us-east-1" }.use { secretsClient -> val response = secretsClient.getSecretValue(valueRequest) val secret = response.secretString println("The secret value is $secret") } }

这一段是整个示例的核心，由三步组成：

1. 构造请求：通过 Kotlin DSL 风格的构造器创建GetSecretValueRequest，将命令行传入的secretName赋给secretId字段。secretId可以是一个密钥的名称（Name），也可以是 ARN，示例使用名称。
2. 创建客户端：调用SecretsManagerClient.fromEnvironment { region = "us-east-1" }创建客户端。fromEnvironment表示客户端配置（凭据、区域）从环境变量、默认凭据链等来源解析；示例中显式指定了区域us-east-1。客户端实现Closeable/Use接口，因此采用.use { ... }作用域函数确保用后自动关闭，释放底层 HTTP 连接资源。
3. 发起请求并读取结果：secretsClient.getSecretValue(valueRequest)返回GetSecretValueResponse，其中secretString字段保存解密后的字符串型密钥内容，最后打印输出。

需要注意：getValue是suspend函数，说明 SDK for Kotlin 的 API 基于协程（coroutine）设计，调用必须在协程作用域或runBlocking中执行——这正是测试文件中使用runBlocking包裹调用的原因。

关于返回值的补充说明

从代码可见，示例只读取了response.secretString，即字符串类型的密钥值。对于以二进制形式存储的密钥（如密钥对私钥），Secrets Manager 会将其 Base64 编码后通过secretBinary字段返回，需要额外的 Base64 解码步骤；本示例的 GetSecretValue.kt 中并未处理该场景，读者在实际项目中可根据密钥类型自行扩展。

构建配置：build.gradle.kts 深度解读

示例的构建脚本 build.gradle.kts 完整定义了工程的编译、依赖与测试配置，关键点如下：

此外，构建脚本还应用了org.jlleitschuh.gradle.ktlint插件用于 Kotlin 代码风格检查，并在tasks.test中启用 JUnit Platform 与测试事件输出（passed/skipped/failed），方便在终端直接观察每个测试的通过情况。

运行示例的命令

在满足前置条件的前提下，可在 kotlin/services/secrets-manager 目录执行：

gradle run --args="<secretName>"

程序会调用 Secrets Manager 的GetSecretValue接口，并在控制台输出The secret value is ...。

测试实现：JUnit 5 + 协程验证

测试源码结构

测试文件位于 SecretsManagerKotlinTest.kt，核心代码如下：

@TestInstance(TestInstance.Lifecycle.PER_CLASS) @TestMethodOrder(OrderAnnotation::class) class SecretsManagerKotlinTest { private val logger: Logger = LoggerFactory.getLogger(SecretsManagerKotlinTest::class.java) private var secretName = "mysecret" @Test @Order(1) fun getSecretValue() = runBlocking { getValue(secretName) logger.info("Test 1 passed") } }

几个值得注意的实现细节：

• 测试类使用PER_CLASS生命周期与@TestMethodOrder(OrderAnnotation::class)保证测试按@Order注解顺序执行；
• 测试直接复用主程序中的getValue函数（通过import com.kotlin.secrets.getValue），而不是重新实现调用逻辑，体现了示例代码的可复用性；
• 由于getValue是suspend函数，测试用runBlocking将其包裹，在阻塞式测试线程中启动协程；
• 测试前需要确保名为mysecret的密钥已存在于 Secrets Manager 中，否则调用会抛异常导致测试失败；
• 日志输出依赖org.slf4j.Logger，配合 src/test/resources/logback.xml 中配置的 Logback 控制台输出，可在终端看到Test 1 passed之类的信息。

运行测试

根据 kotlin 目录总 README 的说明，测试可以从 IDE（如 IntelliJ IDEA）直接运行，也可以从命令行执行：

gradle test

每个测试运行时，终端会打印成功/失败消息，例如：

Test 1 passed

需要注意：总 README 中提到，部分 Kotlin 服务模块的 JUnit 测试依赖resources目录下的config.properties文件中的配置值；若未定义全部所需值，测试会失败。就本模块而言，测试直接硬编码了secretName = "mysecret"，因此在运行前请确保该密钥已创建。

附加资源与延伸阅读

原 README 的 Additional resources 章节推荐了以下官方资料，读者可按需查阅：

• Secrets Manager 用户指南：覆盖密钥创建、轮换、权限模型等完整概念；
• Secrets Manager API Reference：GetSecretValue、CreateSecret、PutSecretValue等接口的字段与行为定义；
• SDK for Kotlin Secrets Manager API 参考：Kotlin 语言视角下的客户端与模型类文档。

若希望在多服务场景中深入练习，可进一步阅读 kotlin/README.md 中列出的 usecases 教程（涵盖 SQS、DynamoDB、Redshift、Aurora、Step Functions 等组合示例），以及本仓库 scenarios/basics 下的跨服务基础场景文档。

小结

本文围绕仓库中 secrets-manager 目录 的 README 与其源码，完整梳理了使用 AWS SDK for Kotlin 调用 Secrets ManagerGetSecretValue的路径：从请求构造（GetSecretValueRequest）、客户端初始化（fromEnvironment）到协程化调用与结果读取；并深入讲解了 Gradle 构建配置（Kotlin 2.1.0、Java 17、SDK BOM 1.5.63）与 JUnit 测试的组织方式。掌握了这套示例后，你可以将其扩展为完整的密钥管理工具——例如结合CreateSecret、PutSecretValue与RotateSecret接口，为应用构建安全、可轮换的凭据读取链路。

• 示例工程
• 教程
• 后端