国密SDK架构设计：模块划分与接口设计
做国密SDK改造，最怕什么？
我最怕团队上来就写代码。没有架构规划，代码就像一盘散沙。改到后面，接口乱成一团，维护成本直线飙升。
当年我第一次对接政务系统，就是吃了这个亏。一个签名接口改了三次，前端后端来回扯皮。后来我重新做了架构梳理，把所有模块切分开，接口统一约定……嗯，从那以后，我再也不敢跳过架构设计了。
一、核心模块怎么切？
国密SDK的功能不少：密钥生成、证书解析、SM2/SM3/SM4算法调用、会话管理、安全通道……如果全塞在一个模块里，迟早变成“垃圾山”。
我个人习惯按职责切分。说白了，就是每个模块只干一件事。
| 模块名称 | 核心职责 | 关键类/函数 |
|---|---|---|
| 初始化模块 | 加载配置、检测密码硬件、初始化算法上下文 | GMInit(), GMConfig |
| 会话管理模块 | 建立/销毁会话、管理会话状态、超时复用 | GMSessionCreate(), GMSessionFree() |
| 算法引擎模块 | 封装SM2/SM3/SM4、密钥生成、签名验签 | GM_SM2Sign(), GM_SM4Encrypt() |
| 密钥管理模块 | 密钥生成、存储、生命周期、密钥销毁 | GMKeyGenerate(), GMKeyDestroy() |
| 证书与PKI模块 | 证书解析、证书链验证、CRL检查 | GMCertParse(), GMCertVerifyChain() |
| 日志与异常模块 | 统一日志、错误码映射、异常回调 | GMLog(), GMErrorGet() |
你可能注意到了，我把密钥管理和证书解析拆成了两个模块。为什么？
因为政务场景下，密钥可能来自硬件密码机（比如HSM），而证书来自CA。两个生命周期完全不同。混在一起，接口就变臃肿了。
二、接口设计：少即是多
接口设计的原则，我总结了三句话：
- 参数最小化——能传一个参数的，绝不传两个。
- 责任单一化——一个函数只干一件事。
- 错误明确化——错误码要能直接定位问题。
举个例子。我见过有人写了一个万能接口：GM_DoEverything(data, key, mode, flag, extra...)。把加解密、签名、甚至密钥生成都塞进去了。结果调用方传错flag，上线就崩。这种接口，说白了自己给自己挖坑。
推荐做法：为每个原子操作定义独立接口。例如：
GM_SM4Encrypt(session, plain, key, cipher) → intGM_SM2Sign(session, msg, privateKey, sign) → int
参数里只用结构体指针传大数据，避免大量出参。
接口分类大致有这几类：
- 初始化/反初始化：
GMInit()/GMFinal()。 我建议在进程启动时一次性初始化，别在每次API调用里重复init，性能会差很多。 - 会话管理：
GMSessionCreate()/GMSessionDestroy()。 会话里可以缓存密码设备句柄和算法上下文，避免重复加载。 - 算法操作：
GM_SM2Sign()、GM_SM2Verify()、GM_SM3Hash()、GM_SM4Encrypt()、GM_SM4Decrypt()。 - 密钥管理：
GMKeyGenerate()、GMKeyImport()、GMKeyExport()、GMKeyDestroy()。 - 证书操作：
GMCertParse()、GMCertVerifyChain()。 - 错误处理：
GMErrorGet()、GMErrorString()。
小技巧：我习惯在接口参数中统一加一个“预留扩展”字段（比如 void *reserved）。这样以后需要加新参数时，不用改动接口签名，避免大量调用方代码重编。政务项目迭代频繁，这招特别管用。
三、架构图：一眼看清各模块关系
下面这张SVG图，画的就是我推荐的SDK模块划分与接口调用流程。你看，从上往下，业务系统通过统一API接口调用SDK内部模块，各模块之间通过会话上下文协作，最底层对接密码硬件。
四、避坑指南：我踩过的几个坑
讲完架构，分享几个真实教训。
⚠️ 坑1：会话管理不当导致内存泄漏
我曾经在一个项目中，每次签名都新建会话，签完又不释放。压测半小时后内存直接爆了。后来我加了会话池和引用计数，才稳住。
经验：会话一定要复用，创建和销毁必须成对出现。
⚠️ 坑2：错误码太笼统，排查困难
有个模块全部返回-1。线上报错后，根本不知道是参数错误、硬件故障，还是证书过期。我后来把所有错误码规范成0xGMXXYY格式：GM表示国密模块，XX是模块编号，YY是具体错误类型。
💡 我的推荐：接口设计时预留一个上下文ID
在 GMSession 结构体里加一个 uint64 的 trace_id。每次调用都写入日志。回溯问题时，一条 trace_id 就能串联所有操作，效率翻倍。
架构设计不是一次性的。随着对接的政务系统越来越多，你会发现接口还需要微调。但只要你模块切得清爽、接口定义得清晰，后面改起来压力会小很多。记住，好的架构设计，是为了让你少加班。