第3章 SDK架构设计：模块划分、核心接口与调用链路
做个PKI SDK，最怕什么？最怕一开始没想清楚模块长什么样，后面改起来跟拆炸弹似的。
我记得刚带团队那会儿，有个项目直接把证书解析、签名验证、OCSP查询全塞进一个文件里。结果呢？性能瓶颈根本定位不了，每次发版都心惊胆战。后来我强制要求按职责拆模块，才算把命续上。今天就跟大伙儿聊聊，一个能跑出高性能的PKI SDK，到底该怎么切模块、定义接口、画清楚调用链路。
3.1 典型模块划分
我个人习惯把PKI SDK拆成6个核心模块。你想想看，证书操作无非这几件事：解析、验证、签名、存储、网络、对外暴露。每个模块各干各的，互不干扰。一旦某个模块拖后腿，换掉它不会伤筋动骨。
| 模块名称 | 核心职责 | 常见实现方向 |
|---|---|---|
| 证书解析模块 | 从DER/PEM解析出证书对象，提取公钥、有效期、扩展项 | ASN.1库（如Bouncy Castle、OpenSSL BIO） |
| 链验证模块 | 构建证书链，做路径验证、撤销检查、信任锚比对 | 自建链构建算法 + OCSP/CRL客户端 |
| 密码运算模块 | RSA/ECDSA签名验签、SM2/SM3国密实现、密钥对生成 | JNI调用OpenSSL、原生Crypto API |
| 存储与缓存模块 | 管理证书库、CRL列表、OCSP响应缓存、会话缓存 | LRU缓存、RocksDB、内存池 |
| 网络传输模块 | OCSP/CRL/SCVP的HTTP请求、连接池、超时重试 | Netty、OkHttp、异步回调 |
| API接入层 | 对外暴露同步/异步接口，统一入参出参，监控埋点 | Future/Callback、Coroutine、线程池 |
嗯，这里要注意：我见过很多团队把「密码运算」和「链验证」混在一起。结果想换个签名算法，得动整个验证逻辑。拆开的好处是，你可以在密码运算模块里做硬件加速（比如启用Intel QAT），而在链验证模块里只关心算法类型，不关心具体实现。我在项目中遇到过，某次吞吐率卡死，排查下来是密码运算模块里的慢速RSA把链验证线程全堵住了。拆了之后，链验证的预检先走缓存，密码运算走异步队列，性能直接翻倍。
3.2 核心接口定义
接口定义是SDK的骨架。骨架歪了，后面贴再多肌肉也跑不起来。我跟团队定了两个原则：单模块只暴露最少接口，接口参数用对象而不是散列参数。为啥？散列参数一多，调用的代码自己都记不住顺序，出了bug你也查不出来。
列一下那几个核心接口，都是我在实际项目中经过无数次踩坑后提炼出来的——
证书解析模块（CertParser）
Cert parse(byte[] rawCert, Format format)—— 解析原始数据PublicKey extractPublicKey(Cert cert, KeyAlgorithm algo)—— 提取公钥，支持RSA/ECDSA/SM2
链验证模块（ChainValidator）
ValidationResult validate(Cert leaf, Cert[] intermediates, TrustAnchor anchor)—— 完整链验证ValidationResult validateWithRevocation(Cert leaf, Cert[] intermediates, TrustAnchor anchor, RevocationCheckOption option)—— 带撤销检查的验证
密码运算模块（CryptoProvider）
byte[] sign(PrivateKey key, byte[] data, SignatureScheme scheme)—— 签名boolean verify(PublicKey key, byte[] data, byte[] signature, SignatureScheme scheme)—— 验签
缓存模块（CertCache）
CertCacheEntry get(String certSerial, String issuer)—— 从缓存中获取证书及验证结果void put(String certSerial, String issuer, CacheEntry entry, long ttlMs)—— 存入缓存，带过期时间
避坑指南：我曾经把缓存过期时间写死在代码里，结果OCSP响应缓存了24小时，上线后大量证书明明已被撤销还在通过验证。从那以后我强制缓存模块接受外部TTL配置，而且每次更新都要打一个版本戳，方便排障时追溯。
3.3 调用链路与性能关键路径
接口定义好了，还得理清谁先调谁。你去看市面上那些慢吞吞的PKI SDK，十有八九是调用链路里藏了长耗时的同步点。我画了一张图，把一次典型的证书验证调用链路标注出来，重点关注那些可能卡住的地方。
看图就明白了：最耗时的两个节点是密码运算和网络传输。缓存如果命中，直接从内存返回，跳过这两个拖油瓶。我这边的经验是：先把缓存做对，性能至少能提升3～5倍。
注意：千万别在API接入层直接同步调用网络模块。我有个客户，流量一上来线程池直接爆炸，因为每个请求都等OCSP响应才返回。正确做法是：API接入层开异步回调，链验证模块内部对网络IO走超时机制+本地fallback（比如先返回缓存数据，后台刷新）。
3.4 举个例子：一次完整的证书验证，内部到底怎么跑？
假设你的SDK收到一个HTTPS握手传来的叶子证书。流程是这样的——
- API接入层校验入参，转成内部Cert对象，丢给调度器。
- 调度器先调证书解析模块，把DER拆成可读结构。这部分纯内存操作，很快，一般<1ms。
- 解析完立刻查缓存模块：拿证书序列号和颁发者SHA1做key，看之前有没有验证过。如果缓存命中且未过期，直接返回缓存中的验证结果——这一步能省掉后面所有开销。我建议缓存过期时间要配上可配置的TTL，根据业务场景调，比如金融场景可以设30分钟，IoT设备可能设5分钟就够了。
- 缓存没命中？进入链验证模块。它会构建证书路径，找到中间证书和根CA。这个过程中可能会调用密码运算模块来校验每级证书的签名。
- 签名验证是RSA/ECDSA/SM2运算，尤其RSA 2048在软件实现下大概要5～10ms。如果链上有3级证书，光验签就15～30ms——所以我把这一步单独剥离，用线程池异步执行，避免阻塞后续请求的解析。
- 验证完签名，还要查撤销。网络传输模块发起OCSP请求或下载CRL。网络开销最大，通常10～200ms不等。所以我在网络模块里加了连接池（最多保持5个复用连接），并设置2秒超时。超时后直接返回缓存中上次有效的OCSP响应（如果还有效），而不是报错。
- 所有子项都通过了，链验证模块返回
ValidationResult。结果写入缓存模块，然后返回给API接入层。
整个链路按顺序跑，但如果缓存命中，实际只走了第1、2、3步，耗时不到2ms。不命中的情况下，密码运算和网络传输加起来占了95%以上的时间。你说性能优化搞哪？就是搞这两个地方。
避坑指南：我曾经碰过一个案例，链验证模块里每次重新计算CA证书的公钥对象。仔细一查，同一个根证书的PublicKey被反复从byte[]解析了上百次。后来我在密码运算模块里加了个PublicKey缓存池，按证书指纹缓存解析好的Key对象，签名验证性能直接快了30%。说白了，就是少做重复劳动。
嗯，以上就是SDK架构设计的核心：模块按职责切分，接口定义要精简，调用链路要画清楚性能瓶颈。你做设计时，多问问自己：这个模块能被单独替换吗？接口参数能序列化吗？缓存失效了会怎样？ 想明白这三件事，架构就不容易跑偏。带着思路去写代码，比边写边改靠谱得多。