1. 密钥系统概述：理解旧密钥体系与新SDK的差异与适配目标
做 SDK 集成这么多年，我接手过不少遗留系统的迁移项目。最让人头疼的，往往不是接口变没变，而是——密钥体系全换了。你想想看，旧的密钥写死在代码里，新的 SDK 要求动态获取。不搞清楚这两套体系的差异，直接上手改，迟早要踩雷。
这一节，咱们就把新旧密钥体系的底细彻底捋一遍。适配的目标是什么？核心难点在哪？我心里有个谱了，动手才不会慌。
1.1 旧密钥体系：那些年我们写死在代码里的秘密
早些年做 SDK 集成，密钥管理的方式很随意。说白了，就是「怎么方便怎么来」。我在一个金融项目中遇到过，密钥直接以字符串常量写在 Java 类里，编译完就躺在 APK 里了。反编译一下，一览无余。
旧密钥体系一般有这几个特征：
- 硬编码存储 — 密钥直接写在源码或配置文件中，换个环境就得重新打包。
- 本地明文文件 — 放在 assets、res/raw 或 properties 文件里，谁读都一样。
- 自建加密算法 — 总觉得自己写的 AES/RSA 包装更安全，结果往往漏洞百出。
- 手动轮换 — 密钥过期了？运维手动改代码、发版本、等审核，周期长得吓人。
- 中心化管理 — 所有服务共用一套密钥，泄露一个等于全盘皆输。
build.gradle 的 buildConfigField 里。编译后通过 BuildConfig. 就能拿到。结果代码被第三方逆向，密钥被盗刷了十几万。教训太深了。
旧体系不是不能用，而是它的安全假设在今天已经站不住了。移动端、服务端、客户端分离的架构下，密钥一旦被拿到，攻击者就能伪装成你的应用做任何事。
1.2 新SDK密钥体系：平台时代的钥匙管理
新 SDK 的做法完全不同。它不再信任客户端环境，而是把密钥当成「动态凭证」来管理。我记得第一次接触这种设计时还不太习惯，后来才发现——这才是正解。
新体系的核心变化：
- 动态获取 — 密钥从服务端下发，客户端只存临时令牌，过期就失效。
- 安全存储区域 — 使用 iOS Keychain、Android Keystore 或 TEE 环境，系统级隔离。
- 平台托管 — 密钥的生成、分发、轮换全由 SDK 或云平台完成，开发者不用碰原始密钥。
- 去中心化 — 不同服务使用不同的密钥，最小权限原则，泄露一个不影响其他。
- 自动轮换 — 密钥定期自动更新，开发者零干预。
一句话总结： 旧体系是「藏好钥匙」，新体系是「让钥匙自己失效」。思路完全不一样。
1.3 适配目标：让旧钥匙打开新锁
适配不是把旧密钥搬家到新 SDK 里就完事了。你得理解新 SDK 的信任模型，然后重新设计密钥的获取和存储方式。目标很明确：
- 消除硬编码 — 从源码、配置文件、本地资源中移除所有静态密钥。
- 接入安全存储 — 把密钥迁移到系统级安全区域，比如 Keychain 或 Keystore。
- 替换自建加密 — 用平台标准加密库（如 CommonCrypto、Android Jetpack Security）替代手写算法。
- 建立动态获取机制 — 设计密钥下发和缓存逻辑，支持服务端实时变更。
- 实现自动轮换 — 让密钥生命周期由新 SDK 管理，不再依赖人工操作。
| 对比维度 | 旧密钥体系 | 新SDK密钥体系 |
|---|---|---|
| 存储位置 | 源码 / 配置文件 / 资源文件 | Keychain / Keystore / TEE |
| 获取方式 | 编译时固定 | 运行时动态下发 |
| 加密算法 | 自建 AES / RSA | 平台标准加密库 |
| 轮换方式 | 手动改代码 + 发版 | 自动轮换 + 零停机 |
| 泄露影响范围 | 全局（所有服务共用） | 单域隔离（最小权限） |
你看到没有？每一行的变化都不是简单的「换个接口调一下」，而是整个安全架构的升级。适配工作的本质，是在不破坏现有业务的前提下，把密钥的信任根从客户端转移到服务端。
1.4 适配策略框架
说了这么多抽象的概念，不如一张图来得直观。我自己做迁移规划时习惯先画框架图，把「现状 → 转换 → 目标」三层关系理清楚。下面这张图就是适配旧密钥到新 SDK 的核心逻辑：
这张图我建议你收藏起来。每次做到对应步骤时，回头看一眼自己在哪个位置，思路就不会乱。左中右三层对应着「现状 → 转换 → 目标」，也是整套课程的核心脉络。
1.5 常见误区与避坑指南
适配过程中，有几个坑我几乎每次都会看到。提前说出来，你遇到了能少走弯路。
我曾经见过一个团队，把旧密钥字符串直接赋值给新 SDK 的初始化方法，以为就算适配完了。结果新 SDK 要求密钥是动态下发的，静态字符串根本无法触发自动轮换。白忙一场。
正确做法： 理解新 SDK 的密钥生命周期，按它的机制去设计获取逻辑。
旧体系下密钥很少过期，所以很多人迁移时根本不检查有效期。结果上线后密钥突然失效，用户全部掉线。
正确做法： 在适配层加一个密钥有效性检查逻辑，过期前提前拉取新密钥，做好缓存和降级策略。
适配密钥体系，说白了就是把「不可控」变成「可控」。旧密钥写死在代码里，你控制不了谁拿到了它。新 SDK 让密钥变成动态的、有时效的、可轮换的。你掌握的是管理策略，而不是一串静态字符串。
搞清楚了这些差异和目标，后续的实操才不会走偏。我个人习惯在做任何代码改动前，先花半天把这张框架图吃透。磨刀不误砍柴工嘛。