Secrets Manager API 概览：关键操作与幂等性需求

说实话，Secrets Manager 的 API 并不多，满打满算就五个核心操作。但你想想看，每个操作在幂等性上的脾气都不一样。我最早接手这个项目时，觉得 GetSecretValue 肯定幂等，这没错。但 CreateSecret 和 DeleteSecret 呢？嗯，这里面的门道不少。下面我一个一个拆开讲，顺便说说我踩过的坑。

CreateSecret — 创建密钥

这个操作很简单——创建一个新的密钥。但幂等性的问题恰恰出在“新”字上。如果客户端因为超时重发了请求，服务端可能已经创建成功了，结果又来一次，那就变成两个密钥了。

我在项目中遇到过真实案例：用户在前端页面连续点了两次“创建”按钮，后端收到了两个一模一样的请求，结果生成了两个不同的密钥。当时用户一脸懵，我们也排查了半天。后来加上请求 ID 去重，才彻底解决。

伪代码示例：

// 客户端生成唯一请求ID
val requestId = UUID.randomUUID().toString()

val request = CreateSecretRequest.builder()
    .name("my-db-password")
    .secretString("s3cr3t!")
    .clientRequestToken(requestId)  // 幂等令牌
    .build()

client.createSecret(request)

GetSecretValue — 获取密钥值

这个操作是天然的幂等操作。你调用一次和调用一百次，只要密钥没有被更新，返回的值一模一样。服务端不会因为多次读取而改变任何状态。

但这里有个容易被忽视的点：幂等不代表“值永远不变”。如果有人在两次调用之间更新了密钥，返回值自然会变。这是业务逻辑决定的，不是幂等性的问题。

PutSecretValue — 更新密钥值

这个操作用来更新密钥的值。每次调用都会生成一个新的版本。问题来了：如果客户端重试，每次调用都生成一个新版本，版本数量会飞速增长。

幂等性策略：使用版本控制。客户端在请求中指定版本标签（Version Label），如果该标签对应的版本已存在，服务端可以选择覆盖或返回冲突错误。

val request = PutSecretValueRequest.builder()
    .secretId("my-db-password")
    .secretString("new-s3cr3t!")
    .versionStages(List.of("current"))  // 指定版本标签
    .build()

client.putSecretValue(request)

UpdateSecret — 更新密钥属性

这个操作用来更新密钥的描述、标签等元数据，不改变密钥值。它的幂等性问题和 PutSecretValue 类似——重复调用可能导致属性被多次修改。

解决方案是使用条件更新。客户端在请求中带入当前版本标签或时间戳，服务端检查是否匹配，匹配才更新。

val request = UpdateSecretRequest.builder()
    .secretId("my-db-password")
    .description("数据库密码（2024版）")
    .build()

client.updateSecret(request)

注意，UpdateSecret 的幂等性设计比 PutSecretValue 宽松一些。因为元数据的变更通常不会像密钥值变更那样产生严重的连锁反应。但如果你追求强一致性，条件更新是推荐的做法。

DeleteSecret — 删除密钥

这个操作的幂等性设计最特殊，也最敏感。你想想看，一旦删了，密钥就没了。如果客户端误触发了多次删除请求，后果很严重。

val request = DeleteSecretRequest.builder()
    .secretId("my-db-password")
    .forceDeleteWithoutRecovery(false)  // 软删除，可恢复
    .recoveryWindowInDays(7)
    .build()

client.deleteSecret(request)

如果客户端重复调用 DeleteSecret，服务端检测到该密钥已处于“待删除”状态，直接返回成功，不会重复执行真正的删除动作。这样就实现了幂等。

幂等性特征对比

下面这个表格总结了五个 API 的幂等性特征。你可以把它当作速查手册。

API 操作	是否天然幂等	幂等性策略	关键注意事项
CreateSecret	否	客户端请求去重（Idempotency ）	请求 ID 必须全局唯一；服务端需持久化存储已处理的 ID
GetSecretValue	是	天然幂等，无需额外设计	结合客户端缓存优化性能；注意密钥更新后值会变化
PutSecretValue	否	版本控制 + 条件更新	指定版本标签，避免版本数量失控；CAS 语义可防止并发覆盖
UpdateSecret	否	条件更新（基于版本标签或时间戳）	元数据变更影响面较小，但强一致性场景仍需条件更新
DeleteSecret	否	软删除 + 确认机制	设置等待窗口，允许撤销删除；避免使用强制删除

知识体系全景

为了让你更直观地理解这五个 API 与幂等性策略的对应关系，我画了一张全景图。上排是核心操作，下排是对应的幂等性策略。