📚 课程目录第3章 HAL层设计原则

3、HAL层设计原则：分层思想、接口与实现分离、依赖倒置、驱动模型抽象

说实话，HAL层这个词，很多工程师天天挂在嘴边，但真正把它做明白的，不多。

我见过太多项目，号称用了HAL，结果底层寄存器操作满天飞。换了个芯片型号，代码改得比重新写还痛苦。为什么会这样？说白了，就是没搞懂HAL层的设计原则。

这一章，我把这些年踩过的坑、总结的经验，掰开了讲给你听。

3.1 分层思想：别让上层知道你睡在哪个床上

分层思想的核心就一句话：每一层只关心自己该关心的事。

应用层不需要知道你的GPIO是挂在PA0还是PB1。它只知道：我调用一个 Led_On()，灯就亮了。至于这个灯是推挽输出还是开漏输出，是STM32F103还是GD32F303，应用层不关心。

分层的本质是“职责隔离”

应用层：业务逻辑，只调用抽象接口
HAL层：硬件抽象，提供统一API
驱动层：寄存器操作，直接跟硬件打交道

我早期做的一个项目，把SPI的配置代码直接写在了应用逻辑里。后来要换一颗Flash芯片，好家伙，SPI的极性、相位全变了。我翻遍了整个工程，改了十几个文件。那感觉，就像在迷宫里找钥匙。

从那以后，我给自己定了个规矩：应用代码里，不允许出现任何寄存器级别的操作。谁写我跟谁急。

3.2 接口与实现分离：你只管用，别管我怎么干

这个原则，说白了就是“头文件里只放声明，实现藏在.c文件里”。

但很多人做得不够彻底。我见过有人把结构体定义直接扔在头文件里，结果上层代码能直接访问结构体成员。这等于把家门钥匙给了别人。

// 正确的做法：头文件只暴露接口
// hal_uart.h
#ifndef __HAL_UART_H__
#define __HAL_UART_H__

#include <stdint.h>

// 不暴露结构体内部细节
typedef struct HalUart HalUart_t;

// 只暴露函数接口
HalUart_t* HalUart_Create(uint32_t baudrate);
void        HalUart_Send(HalUart_t* uart, const uint8_t* data, uint32_t len);
uint32_t    HalUart_Receive(HalUart_t* uart, uint8_t* buf, uint32_t max_len);

#endif

// 实现文件：结构体定义藏在这里
// hal_uart.c
#include "hal_uart.h"

struct HalUart {
    USART_TypeDef* instance;
    uint32_t       baudrate;
    uint8_t        tx_pin;
    uint8_t        rx_pin;
};

HalUart_t* HalUart_Create(uint32_t baudrate) {
    HalUart_t* uart = (HalUart_t*)malloc(sizeof(HalUart_t));
    if (uart) {
        uart->baudrate = baudrate;
        // 初始化硬件...
    }
    return uart;
}

我的习惯：头文件里只放 typedef 的前置声明和函数原型。结构体的完整定义、宏定义、静态函数，全部锁在 .c 文件里。这样上层代码想乱来都没机会。

3.3 依赖倒置：别让高层依赖低层，反过来才对

依赖倒置原则（DIP）听起来高大上，其实道理很简单：高层模块不应该依赖低层模块，两者都应该依赖抽象。

举个例子。你的应用层要读写EEPROM。如果应用层直接调用 I2C_Write()、I2C_Read()，那它就是依赖了具体的I2C驱动。哪天你要换成SPI接口的EEPROM，应用层代码就得重写。

我曾经踩过的坑：一个产品用了AT24C02（I2C接口），后来因为供货问题要换成25AA02（SPI接口）。因为应用层直接调用了I2C函数，我不得不把整个存储模块重写了一遍。测试还出了好几个bug，差点延误交付。

正确的做法是：定义一个抽象的存储接口，应用层只跟这个接口打交道。

// 抽象接口：存储设备
typedef struct {
    int32_t (*Init)(void);
    int32_t (*Write)(uint32_t addr, const uint8_t* data, uint32_t len);
    int32_t (*Read)(uint32_t addr, uint8_t* buf, uint32_t len);
} StorageOps_t;

// 应用层只依赖这个接口
void App_SaveConfig(StorageOps_t* storage, const Config_t* cfg) {
    storage->Write(0x0000, (uint8_t*)cfg, sizeof(Config_t));
}

这样，底层是I2C还是SPI，应用层完全不知道。换驱动？写个新的 StorageOps_t 实例就行。

3.4 驱动模型抽象：把硬件包装成“标准件”

驱动模型抽象，是我觉得HAL层设计里最见功力的一环。

它的目标是什么？让不同厂商、不同型号的同类设备，用起来感觉一样。

比如GPIO。STM32的GPIO和NXP的GPIO，寄存器结构完全不同。但如果你抽象出一个统一的GPIO接口：

// 统一的GPIO抽象
typedef struct {
    void (*SetPin)(void* handle, uint16_t pin, uint8_t level);
    uint8_t (*GetPin)(void* handle, uint16_t pin);
    void (*TogglePin)(void* handle, uint16_t pin);
} GpioOps_t;

那么上层代码写一次，换个平台只需要换底层的 GpioOps_t 实现。这就是驱动的“即插即用”。

驱动模型抽象的三个层次

设备级抽象：把单个外设（UART、SPI、I2C）封装成对象
总线级抽象：把通信总线抽象成“发送/接收”通道
平台级抽象：把整个MCU平台抽象成“初始化/运行/休眠”状态机

3.5 把这些原则串起来：一张图看懂HAL层架构

说了这么多，不如一张图来得直观。下面是我常用的HAL层架构图，你可以把它当成设计模板。

3.6 四个原则的对比与取舍

这四个原则不是孤立的，它们互相支撑。我整理了一个表格，方便你对照理解。

原则	核心思想	解决什么问题	常见反例
分层思想	职责隔离，每层只关心自己的事	代码耦合严重，牵一发而动全身	应用层直接操作寄存器
接口与实现分离	头文件只暴露接口，实现藏在.c里	上层代码依赖内部细节，无法独立演进	结构体定义放在头文件中
依赖倒置	高层依赖抽象，不依赖具体实现	更换底层驱动需要修改上层代码	应用层直接调用I2C_Write()
驱动模型抽象	同类设备统一接口，即插即用	不同厂商设备接口不统一，移植困难	每个外设都有一套独立的API风格

我的建议：这四个原则，优先级有先后。先做好分层，再搞接口分离，然后引入依赖倒置，最后才是驱动模型抽象。别想一口吃成胖子。我见过有人一上来就搞抽象接口，结果连基本功能都没调通。

3.7 避坑指南：我这些年总结的几条铁律

不要为了抽象而抽象。如果一个外设只有一种实现方式，没必要搞虚函数表。抽象是有成本的。
接口参数要稳定。一旦发布，尽量不要改。我吃过亏：把 uint32_t 改成 uint16_t，结果所有调用方都要改。
分层不是越多越好。嵌入式系统资源有限，3-4层足够了。搞个7层架构，性能扛不住。
测试先行。抽象接口的好处之一就是方便测试。写个模拟的 StorageOps_t，不用硬件也能跑单元测试。

我曾经犯过的错：在一个项目里，我把所有外设的抽象接口都设计成了“万能型”——一个函数传一个结构体指针，里面塞了各种参数。结果代码可读性极差，后来我自己都看不懂那个结构体里到底该填什么。记住：接口要简洁，参数要明确。

嗯，这一章的内容就这些。HAL层的设计原则，说白了就是“让变化可控，让复用成为习惯”。你把这些原则刻在脑子里，写出来的代码，自己看着都舒服。