第4章 Secrets Manager API 需求分析
做 API 设计，说白了就是给系统画图纸。你得先搞清楚，谁要来用？怎么用？用多久？我早年吃过不少亏，代码写完了才发现接口没考虑轮转场景，结果推倒重来。嗯，今天咱们就聊聊 Secrets Manager 的 API 到底要满足哪些需求。
4.1 功能需求：增删改查只是起点
一般提到 Secrets Manager，大家第一反应就是「存密码、取密码」。没错，这是基本功。但实际项目中，真正的需求要复杂得多。
我整理了一个功能需求清单，你可以照着它去做接口设计：
| 需求分类 | 核心功能 | 典型场景 |
|---|---|---|
| 生命周期管理 | 创建、读取、更新、删除 Secret | 应用启动时加载数据库密码 |
| 版本控制 | 创建新版本、回滚、查看历史 | 密码轮转后保留上一个版本 |
| 访问控制 | 基于身份的策略绑定、临时授权 | 只允许特定服务获取 Secret |
| 审计日志 | 记录谁在什么时间做了什么操作 | 安全审计排查权限泄露 |
| 自动轮转 | 按策略自动更新 Secret 值 | 每 90 天更换数据库密码 |
核心洞察：增删改查只是地表层。真正决定接口好坏的，是版本控制与轮转策略的设计。这俩没想清楚，后面全是坑。
举个例子。我参与过一个金融项目，要求密码轮转时必须「零停机」。这意味着新版本写入时，旧版本仍然可读。直到所有客户端都更新完，才能把旧版本彻底删掉。你看，这就不只是简单的 PUT /secret/{name} 了。
4.1.1 数据结构的设计陷阱
API 需求里最容易被忽略的，是「数据应该长什么样」。我个人习惯，先把资源模型画出来，再谈接口。
Secret {
name: string
description: string
currentVersion: string
versions: [
{
id: string
value: encrypted string
createdTime: timestamp
status: "active" | "pending" | "expired"
}
]
metadata: {
rotationPeriod: duration
lastRotatedTime: timestamp
tags: map[string]string
}
}
注意看 status 字段。我早期设计时没考虑过期状态，结果轮转时旧版本到处都是，根本分不清哪个还在用。后来加了这个字段，管理起来就清晰多了。
我的习惯：数据结构最好包含元数据字段，比如标签、描述、创建者。这些在排查问题时特别有用。我曾经靠标签字段，5 分钟定位到一个被遗忘的测试环境密钥。
4.2 非功能需求：性能与可靠性
功能需求决定了「能不能用」，非功能需求决定了「好不好用」。想想看，如果 API 响应时间达到 2 秒，那所有依赖它的服务都得跟着卡。
常见的非功能需求包括：
- 低延迟：读取操作应当在 10ms 以内完成
- 高可用：99.99% 的 SLA，不能有单点故障
- 可扩展：支持十万级的 Secret 和百万级的访问频率
- 加密存储：所有 Secret 值在存储时必须加密
- 访问隔离：不同租户的数据要物理隔离
这里有一个常见的权衡：延迟 vs 一致性。读操作需要快，但 Write 操作又必须保证数据不丢。怎么平衡？
我倾向的做法是：读走缓存，写走主库。缓存过期时间设为 30 秒左右，既能扛住高频读，又不会让数据太滞后。当然，这得看你的业务对一致性有多敏感。
| 指标 | 阈值 | 备注 |
|---|---|---|
| 读取 P99 延迟 | < 10ms | 直接读缓存层 |
| 写入 P99 延迟 | < 200ms | 包含加密和存储 |
| 可用性 | > 99.99% | 多副本 + 自动故障转移 |
| 并发连接数 | > 50,000 | 无状态服务横向扩展 |
注意：千万不要把缓存作为唯一数据源。我曾经在项目中看到有人把 Secret 全部放在 Redis 里，结果 Redis 一挂，所有服务都拿不到密码了。缓存必须配合持久化存储使用。
4.3 API 需求全景图
说了这么多，咱们还是看一张图来得直观。下面这张图把 Secrets Manager API 的需求层和依赖关系画了出来。
从图上你可以看出，功能需求是骨架，非功能需求是血肉，支撑能力是连接器。三层相辅相成，缺一不可。
一句话总结：API 需求分析不只是罗列接口，而是要搞清楚每个接口背后要解决什么问题，以及可能带来的副作用。我曾经因为漏掉审计需求，最后不得不在线上加一套旁路系统抄日志，搞得团队加班两周。
4.4 避坑指南：常见需求遗漏
根据我多年经验，下面这几个坑几乎每个项目都会遇到：
- 批量操作缺失：只有单条读取，没有批量查询。结果每次启动都要发几百次请求。
- 没有轮转前检查：新密码生成后，没有验证是否可用。导致轮转出一个不可用的密码，锁死了整个系统。
- 忽略错误码规范：不同的错误返回不同格式，下游客户端解析起来非常痛苦。
- 缺少资源占用限制：没有限制单个 Secret 的版本数量，结果用户攒了几千个版本，接口越查越慢。
我的建议：在需求分析阶段，拉一个「负面清单」。把可能会出错的地方、可能会超用的地方、可能会遗漏的地方都列出来。这比事后补文档要高效得多。
好了，这一章的内容就到这儿。API 需求分析是接口标准化的第一步，也是最重要的一步。你有想法或者踩过什么坑，随时可以对照这张全景图来看一看，看看自己是不是也漏掉了什么。