HAL 接口定义规范：命名、参数、返回值与错误码

接口定义规范，说白了就是 HAL 层的「普通话」标准。没有这套标准，你写的驱动别人看不懂，别人写的接口你不敢用。我在好几个项目里都见过这种惨状——同一个芯片，三个工程师写出了三套风格完全不同的 HAL，最后集成时简直是一场灾难。

今天我们就来把这套规矩定死。记住，HAL 接口不是给你一个人看的，是要给整个团队、甚至后续维护者看的。

命名规范：一眼看懂，不用猜

命名这件事，我个人的习惯是「长一点没关系，但必须自解释」。你想想看，一个叫 i2c_write() 的函数，和另一个叫 HAL_I2C_Master_Transmit() 的函数，哪个更清楚？

我建议遵循以下几条铁律：

• 前缀统一：所有 HAL 接口以 HAL_ 开头，后面跟模块名，比如 HAL_GPIO_、HAL_SPI_。
• 动词+名词：函数名结构为「操作动词 + 对象名词」，例如 HAL_UART_Receive()、HAL_ADC_Start()。
• 下划线分隔：模块名、动词、名词之间用下划线隔开，不要驼峰混用。
• 避免缩写：除非是行业通用缩写（如 DMA、GPIO），否则不要自己发明简写。

参数规范：少即是多，顺序有讲究

参数设计上，我踩过最大的坑就是「参数太多」。曾经有个同事写了个 HAL_I2C_Mem_Write()，一口气塞了 8 个参数，调用时谁都得翻手册。后来我重构时，把能合并的合并，能拆结构体的拆结构体。

参数顺序我建议统一为：

1. 句柄/对象指针（第一个，标识操作哪个外设）
2. 数据缓冲区指针（第二个，数据从哪里来/到哪里去）
3. 数据长度/数量（第三个，多少数据）
4. 超时时间或配置参数（最后一个，可选）

// 好的参数设计
HAL_StatusTypeDef HAL_SPI_Transmit(
    SPI_HandleTypeDef *hspi,    // 句柄指针
    uint8_t *pData,             // 数据缓冲区
    uint16_t Size,              // 数据长度
    uint32_t Timeout            // 超时时间
);

// 不好的参数设计（参数太多且顺序混乱）
HAL_StatusTypeDef SPI_Send(
    uint8_t *buf,
    uint16_t len,
    uint32_t timeout,
    uint8_t cs_pin,
    uint8_t mode
);

返回值规范：统一类型，别搞特殊

返回值这件事，我见过最离谱的是同一个项目里，有的函数返回 0 表示成功，有的返回 1 表示成功，还有的返回负数表示错误。你想想看，这代码怎么维护？

我建议所有 HAL 接口统一使用 HAL_StatusTypeDef 枚举类型：

typedef enum {
    HAL_OK       = 0x00U,  // 操作成功
    HAL_ERROR    = 0x01U,  // 操作失败（硬件或参数错误）
    HAL_BUSY     = 0x02U,  // 外设忙，操作被拒绝
    HAL_TIMEOUT  = 0x03U   // 操作超时
} HAL_StatusTypeDef;

为什么只用这四种？因为够用。我在项目中试过定义几十种错误码，结果发现调用方根本不会去区分，最后都统一当成「出错了」处理。少即是多，够用就好。

错误码定义：分层管理，逐级细化

错误码这块，我建议分层设计。HAL 层只定义通用错误码（就是上面那四种），具体模块的错误细节通过扩展机制来实现。

举个例子：

• HAL 层：只返回 HAL_OK、HAL_ERROR、HAL_BUSY、HAL_TIMEOUT
• 模块层：通过句柄中的 ErrorCode 字段记录详细错误，比如 HAL_SPI_ERROR_OVERRUN、HAL_I2C_ERROR_AF
• 应用层：读取 ErrorCode 做精细化处理

// 模块级错误码示例（SPI 模块）
#define HAL_SPI_ERROR_NONE      0x00U
#define HAL_SPI_ERROR_MODF      0x01U  // 模式错误
#define HAL_SPI_ERROR_OVR       0x02U  // 溢出错误
#define HAL_SPI_ERROR_DMA       0x04U  // DMA 传输错误

// 句柄中保存错误码
typedef struct {
    SPI_TypeDef *Instance;
    uint32_t ErrorCode;  // 这里记录详细错误
    // ... 其他字段
} SPI_HandleTypeDef;

知识结构总览

下面这张图把接口定义规范的四个维度串起来了。你可以把它当作设计新接口时的检查清单。

避坑指南：我踩过的那些坑

最后分享几个我亲身经历过的教训：

• 命名不一致：曾经有个项目，GPIO 模块用 HAL_GPIO_WritePin()，但 TIM 模块却用 HAL_TIM_Start_IT()，风格完全不统一。后来我强制要求所有模块必须按照同一套模板生成代码。
• 参数顺序混乱：有个同事把数据长度放在缓冲区前面，结果调用时传反了，调试了两天才发现。从那以后，我规定所有接口的参数顺序必须严格遵循「句柄→数据→长度→配置」的顺序。
• 返回值被忽略：我见过最夸张的代码，调用 HAL 接口后完全不检查返回值，出错了也不知道。后来我在代码审查时加了一条硬性规则：所有 HAL 接口的返回值必须被检查，要么用断言，要么用 if 判断。