4. 接口设计规范：函数命名、参数传递、错误码定义与返回值约定
接口设计这件事，说白了就是定规矩。你在一个团队里写驱动，今天你按自己的习惯命名，明天他按另一套风格传参，后天项目一合并，光改接口名就能改到崩溃。我经历过这种痛苦，所以现在特别看重接口规范。
这一章，我们就把接口设计的几个核心问题掰开揉碎讲清楚。函数怎么取名？参数怎么传？错误码怎么定义？返回值怎么约定？这些看似琐碎的东西，恰恰是决定你的HAL层能不能真正“可移植”的关键。
4.1 函数命名规范：一眼看懂，不用猜
函数命名，我个人的习惯是“模块_动作_对象”。比如：
// 好的命名
HAL_UART_Init()
HAL_UART_Write()
HAL_UART_Read()
// 不好的命名
uart_init()
uart_write()
uart_read()
你可能会问，后面那种写法不是更短吗？短是短，但问题在于——它没有“归属感”。当你的项目里有10个模块，每个模块都有init、write、read，你根本分不清哪个是哪个。加上模块前缀，一眼就能定位。
命名三要素：
- 模块前缀：HAL_UART、HAL_SPI、HAL_GPIO
- 动作动词：Init、Write、Read、Config、DeInit
- 操作对象：Buffer、Byte、Callback、Config
我在项目中遇到过一种情况：有人把初始化函数写成HAL_UART_Config()，另一个模块写成HAL_UART_Init()。结果后面维护的人根本搞不清这两个函数有什么区别。后来我们统一规定：Init是初始化硬件，Config是配置参数。这样就不会混淆了。
4.2 参数传递规范：指针还是值？这是个问题
参数传递，看起来简单，其实坑很多。我总结了几条铁律：
| 参数类型 | 传递方式 | 说明 |
|---|---|---|
| 基本类型（int, char） | 值传递 | 直接传值，简单高效 |
| 结构体（小，< 64字节） | 值传递或指针 | 看性能要求，指针更省栈空间 |
| 结构体（大，> 64字节） | 指针传递 | 必须用指针，否则栈溢出 |
| 缓冲区（数组） | 指针 + 长度 | 必须同时传长度，防止越界 |
| 回调函数 | 函数指针 | 注意生命周期，别传野指针 |
这里有个细节：传指针时，一定要加const修饰。如果函数只读不写，就用const。这不仅是语法规范，更是一种“契约”——告诉调用者：你放心，我不会改你的数据。
// 好的做法
HAL_StatusTypeDef HAL_UART_Write(
UART_HandleTypeDef *huart,
const uint8_t *pData, // 只读，加const
uint16_t Size
);
// 不好的做法
HAL_StatusTypeDef HAL_UART_Write(
UART_HandleTypeDef *huart,
uint8_t *pData, // 没加const，调用者会担心
uint16_t Size
);
小技巧：参数顺序尽量统一。我习惯按“句柄 → 数据 → 长度 → 超时”的顺序排列。这样所有驱动接口看起来都像“一个模子刻出来的”，调用者不用每次都查手册。
4.3 错误码定义：别用魔法数字
错误码这件事，我曾经吃过亏。早期一个项目里，有人用0表示成功，-1表示失败，1表示超时。后来另一个模块用0表示成功，1表示失败，2表示超时。两个模块一对接，全乱套了。
所以，错误码必须统一。我推荐用枚举类型：
typedef enum {
HAL_OK = 0x00U, // 成功
HAL_ERROR = 0x01U, // 通用错误
HAL_BUSY = 0x02U, // 忙
HAL_TIMEOUT = 0x03U, // 超时
HAL_INVALID = 0x04U, // 参数无效
HAL_UNSUPPORTED = 0x05U // 不支持
} HAL_StatusTypeDef;
为什么用枚举？因为枚举有名字，调试的时候一眼就能看出是什么错误。如果用宏定义，也能达到类似效果，但枚举更“干净”——它把相关的错误码组织在一起，不会散落在代码各处。
注意：错误码不要用负数。很多嵌入式系统的返回值是unsigned类型，负数会被隐式转换，导致判断逻辑出错。我见过一个案例：函数返回-1，调用者用if (ret < 0)判断，结果因为类型转换，永远进不了错误处理分支。
4.4 返回值约定：成功还是失败？一次说清楚
返回值怎么约定？我个人的原则是：函数只做一件事，返回值只表示这件事做没做成。
举个例子：
// 好的设计
HAL_StatusTypeDef HAL_UART_Write(
UART_HandleTypeDef *huart,
const uint8_t *pData,
uint16_t Size
);
// 返回值：HAL_OK 表示写入成功，其他表示失败
// 不好的设计
int HAL_UART_Write(
UART_HandleTypeDef *huart,
const uint8_t *pData,
uint16_t Size
);
// 返回值：正数表示实际写入的字节数，负数表示错误码
// 调用者要同时判断正负和大小，逻辑复杂
你可能会说，第二种设计更“灵活”——它既返回了状态，又返回了数据。但问题在于，这种“灵活”增加了调用者的心智负担。每次调用都要想：这个返回值到底是数据还是状态？
我的建议是：状态和数据分开返回。状态用返回值，数据用参数（指针）。这样职责清晰，调用者一目了然。
返回值约定总结：
- 成功/失败：用枚举类型，如HAL_OK / HAL_ERROR
- 数据量：用指针参数返回，如uint16_t *pActualSize
- 状态信息：用单独的函数或全局变量，如HAL_GetError()
4.5 接口设计全景图
说了这么多，我们用一个SVG图来总结一下接口设计的整体框架。这张图展示了从函数命名到返回值约定的完整链路：
4.6 实战中的避坑指南
最后，分享几个我在实际项目中踩过的坑：
避坑1：不要用void*万能指针
我曾经在一个项目里看到有人用void*传所有参数，美其名曰“通用接口”。结果呢？每次调用都要强制类型转换，稍有不慎就传错类型，编译还检查不出来。后来我们规定：能用具体类型就用具体类型，实在需要泛型才用void*，而且必须加类型标识参数。
避坑2：不要用全局变量传参
有人图省事，把参数放在全局变量里，函数直接读全局。这样做在单线程下勉强能用，但一旦引入多任务或中断，全局变量被意外修改，bug极难排查。我见过一个案例：一个中断服务程序改了全局参数，导致主循环里的驱动函数行为异常，查了三天才找到原因。
避坑3：错误码要留扩展空间
定义错误码时，不要用连续的1、2、3。我习惯用位域或预留区间，比如0x00-0x0F是通用错误，0x10-0x1F是UART专用，0x20-0x2F是SPI专用。这样后续扩展时，不会跟已有错误码冲突。
嗯，接口设计规范就讲到这里。这些规则看起来琐碎，但每一条都是用实际教训换来的。你想想看，如果你的团队里每个人都遵循同一套规范，代码读起来就像同一个人写的，那维护成本会降低多少？