📚 课程目录第3章整体架构分层

03 整体架构分层：接口层、核心层、硬件抽象层

做HSM SDK接入，我见过不少团队一上来就怼代码。结果呢？换了颗安全芯片，整个SDK要重写。说白了，就是没想清楚分层这件事。

我个人习惯，先画一张架构图，把边界定清楚。HSM SDK的核心原则就一句话：高频业务不阻塞，底层硬件可替换。这节课我们就拆开看，三层架构到底怎么分。

  分层收益：
  接口层变动不影响核心密钥逻辑
换芯片时只重写HAL层，接口层零感知
业务方不需要懂硬件细节

3.1 接口层：业务与安全的解耦面

接口层是应用开发者的直接接触面。它的职责很简单：让调用方只关心“做什么”，不关心“怎么做”。

核心职责：

安全服务抽象：封装密钥派生、签名验签、加解密等标准操作
会话管理：建立/销毁安全通道，管理连接池
异步/同步双模式：高性能场景走异步回调，低延迟场景走同步阻塞

我记得有一次对接车机通信模块，对方只给了一个封装好的hsm_sign(data)接口。他根本不知道底层是SPI还是I2C，也没必要知道。这就是接口层该有的样子。

// 接口层示例：异步签名调用
hsm_session_t *session = hsm_session_open("sec_channel_1");
hsm_sign_async(session, data_buf, data_len, on_sign_done, user_ctx);

// 回调处理
void on_sign_done(hsm_result_t *result, void *ctx) {
    if (result->status == HSM_OK) {
        // 使用签名结果
    }
}

小技巧：接口层的结构体尽量设计成不透明句柄（opaque handle），底层实现变化时业务方不需要重新编译。

3.2 核心层：密钥与安全策略的大脑

核心层是三层里最重的一部分。它管理密钥的整个生命周期——从生成、存储、更新到销毁。还有安全策略引擎，决定哪些操作可以执行，哪些不行。

核心层到底管什么？

子模块	说明	常见陷阱
密钥生命周期管理	密钥生成、导入、存储、轮换、销毁	密钥未安全擦除即下电
安全通道协商	双方身份认证、会话密钥协商	协商超时后未清理上下文
数据包封装/解析	TLV格式的协议包组装和拆解	长度字段溢出导致内存拷贝越界
会话状态机	控制会话的建立、维持、释放、异常跳转	状态跳转不完整，漏掉释放逻辑

举个例子，密钥生命周期至少要覆盖这几个状态：

创建：HSM内部或安全导入
激活：密钥可以使用
暂停/禁用：临时不可用，不销毁
归档：只用于验证，不用于签名
销毁：彻底擦除

  关键设计：核心层不应该直接操作硬件。它只下发指令包，硬件交互全部委托给 HAL 层。这样做的好处是——你可以在纯软件环境下跑单元测试，模拟硬件返回任何数据。

3.3 硬件抽象层：屏蔽厂商差异的适配器

HAL 层是真正的“脏活累活”。不同的安全芯片，命令格式、通信协议、寄存器地址全不一样。HAL 层的任务就是把这些差异消化掉。

我在项目中遇到过最典型的场景：上游用的英飞凌 SLM97，下游方案换成了 Microchip ATECC608。接口层和核心层没动，HAL 层重写了 SPI 驱动和命令组包逻辑。

HAL 层要覆盖的能力：

物理接口封装：SPI/I2C/UART 的收发，包括 DMA 模式的支持
命令/响应转换：把核心层的标准指令转成芯片私有的 APDU 或 AT 指令
超时与重传：硬件可能忙、可能掉线，重传策略必须做
电源管理与唤醒：有些安全芯片需要上电唤醒序列

// HAL 层接口示例：SPI 接收一帧数据
int hal_spi_receive(uint8_t *buf, uint32_t len, uint32_t timeout_ms) {
    // 具体实现依赖硬件，可能是阻塞轮询，也可能是中断 + DMA
    // 这里只返回收到数据长度，或负值表示超时/错误
}

避坑指南：我曾经在 HAL 层漏掉了命令超时重传机制，极端场景下芯片进入死锁状态，必须硬件复位才能恢复。后来我强制每一条命令都带超时计数器，超时后先尝试软复位，再不行才报告错误。

3.4 三层之间的数据流与控制流

数据流是自上而下的，控制流则反向自下而上汇报结果。这里有一个容易被忽略的点：核心层负责组装完整的请求包，HAL 层只负责收发，不做任何业务校验。

为什么？因为业务逻辑放在 HAL 层的话，换芯片时你要把校验逻辑也重写一遍。我建议把校验全集中在核心层，HAL 层只保证收发可靠就够了。

典型的数据流向：

业务方调 hsm_sign()（接口层）
核心层构造签名请求包（TLV 格式），加上序列号和校验和
核心层调用 HAL 层的 hal_spi_send()
HAL 层逐字节写 SPI FIFO，等待芯片响应
HAL 层收到完整响应包，返回给核心层
核心层解包、校验、提取签名结果
接口层把结果格式化成业务方的结构体返回

你想想看，如果哪一步出了问题，只需要定位到对应的层。接口层收不到回调，去看核心层有没有返回到队列；核心层报解包失败，去看 HAL 层收到的原始数据对不对。

  分层排障口诀：
  没回调 → 查接口层到核心层的异步队列
返回错误码 → 查核心层的校验逻辑
硬件无响应 → 查 HAL 层的驱动和物理连接

嗯，三层结构看起来简单，但真正做到层与层之间干净隔离，需要很强的“边界意识”。我在前面好几个项目里吃过亏，都是因为边界没划清楚——核心层直接调了 SPI 函数，后来一换芯片就崩。框架对了，后面才走得稳。