📚 课程目录第2章接口抽象层设计

接口抽象层设计：头文件规范、函数指针注册机制、回调函数注册表实现

好，咱们进入第二章。上一章聊了低耦合的大方向，这一章直接落地——接口抽象层。

说白了，接口抽象层就是给模块之间划一条「楚河汉界」。左边模块只管调用，右边模块只管实现，中间靠什么？靠一套稳定的接口契约。我做了十几年嵌入式，见过太多项目因为接口定义混乱，最后联调时鸡飞狗跳。嗯，这一章咱们就把这个「契约」定清楚。

2.1 头文件规范：接口的「法律条文」

头文件不是随便写写的。它是模块对外的承诺。我个人习惯，每个模块只暴露一个头文件，里面只放接口声明，绝不放实现细节。

核心原则：头文件里只放「别人需要知道的东西」，把「别人不需要知道的东西」藏进 .c 文件。

来看一个我常用的头文件模板：

/* module_comm.h - 通信模块接口抽象层 */
#ifndef MODULE_COMM_H
#define MODULE_COMM_H

#include <stdint.h>

/* 1. 错误码定义 - 统一返回状态 */
typedef enum {
    COMM_OK         = 0,
    COMM_ERR_PARAM  = -1,
    COMM_ERR_BUSY   = -2,
    COMM_ERR_TIMEOUT = -3,
    COMM_ERR_UNKNOWN = -4
} comm_err_t;

/* 2. 回调函数类型定义 - 用 typedef 统一签名 */
typedef void (*comm_rx_cb_t)(uint8_t *data, uint16_t len);
typedef void (*comm_tx_done_cb_t)(uint16_t tx_id, comm_err_t status);

/* 3. 注册接口 - 让外部模块把回调挂进来 */
comm_err_t comm_register_rx_callback(comm_rx_cb_t cb);
comm_err_t comm_register_tx_done_callback(comm_tx_done_cb_t cb);

/* 4. 主动调用接口 - 发送数据 */
comm_err_t comm_send(uint8_t *data, uint16_t len, uint16_t *tx_id);

#endif /* MODULE_COMM_H */

注意几个细节：

头文件守卫：#ifndef / #define / #endif 是标配，别用 #pragma once，有些老编译器不认。
类型前置：所有回调函数类型先用 typedef 定义好，后面注册接口直接用类型名，清晰。
返回值统一：所有接口返回 comm_err_t，调用方不用猜返回值含义。

我的习惯：头文件里只放 #include 必要的系统头文件（比如 <stdint.h>），不要乱 #include 其他模块头文件。模块之间依赖越少越好。

2.2 函数指针注册机制：把「钩子」挂上去

函数指针注册机制，说白了就是让模块 A 把自己的函数地址告诉模块 B。B 不关心 A 是谁，只关心这个地址能不能调用。

我在项目中遇到过一个问题：两个团队各自写了自己的通信协议栈，联调时发现回调函数签名差了一个参数。嗯，从那以后我强制要求所有回调函数类型必须在头文件里用 typedef 定义，谁都不许自己写签名。

来看注册机制的实现：

/* module_comm.c */
#include "module_comm.h"

/* 静态函数指针变量 - 只在本文件可见 */
static comm_rx_cb_t     s_rx_cb = NULL;
static comm_tx_done_cb_t s_tx_done_cb = NULL;

comm_err_t comm_register_rx_callback(comm_rx_cb_t cb)
{
    if (cb == NULL) {
        return COMM_ERR_PARAM;
    }
    s_rx_cb = cb;
    return COMM_OK;
}

comm_err_t comm_register_tx_done_callback(comm_tx_done_cb_t cb)
{
    if (cb == NULL) {
        return COMM_ERR_PARAM;
    }
    s_tx_done_cb = cb;
    return COMM_OK;
}

这里有个关键点：静态变量。用 static 把函数指针藏在 .c 文件里，外部模块拿不到、改不了。只能通过注册接口来设置。

避坑指南：注册时一定要做 NULL 检查。我曾经在一个项目里漏了这一步，结果某个模块没注册回调就直接调用了，系统直接 HardFault。从那以后，我所有注册接口第一行就是 if (cb == NULL) return ERR;。

2.3 回调函数注册表实现：管理多个回调

单个回调好办，但实际项目中往往需要多个回调。比如一个通信模块，可能有多个上层模块都想接收数据。这时候就需要一张「注册表」。

来看注册表的设计：

/* module_comm.h - 增加注册表相关定义 */

#define MAX_CALLBACKS  8

/* 注册表条目 */
typedef struct {
    uint8_t        slot_id;    /* 槽位ID，用于注销 */
    comm_rx_cb_t   cb;         /* 回调函数指针 */
    uint8_t        in_use;     /* 0:空闲, 1:已占用 */
} comm_rx_cb_entry_t;

/* 注册表操作接口 */
comm_err_t comm_rx_cb_register(comm_rx_cb_t cb, uint8_t *slot_id);
comm_err_t comm_rx_cb_unregister(uint8_t slot_id);

实现部分：

/* module_comm.c - 注册表实现 */

static comm_rx_cb_entry_t s_rx_cb_table[MAX_CALLBACKS];

/* 初始化 - 清空注册表 */
void comm_rx_cb_table_init(void)
{
    for (int i = 0; i < MAX_CALLBACKS; i++) {
        s_rx_cb_table[i].in_use = 0;
        s_rx_cb_table[i].cb = NULL;
        s_rx_cb_table[i].slot_id = i;
    }
}

/* 注册 - 找一个空闲槽位 */
comm_err_t comm_rx_cb_register(comm_rx_cb_t cb, uint8_t *slot_id)
{
    if (cb == NULL || slot_id == NULL) {
        return COMM_ERR_PARAM;
    }

    for (int i = 0; i < MAX_CALLBACKS; i++) {
        if (s_rx_cb_table[i].in_use == 0) {
            s_rx_cb_table[i].cb = cb;
            s_rx_cb_table[i].in_use = 1;
            *slot_id = i;
            return COMM_OK;
        }
    }

    return COMM_ERR_BUSY;  /* 没有空闲槽位 */
}

/* 注销 - 根据 slot_id 释放 */
comm_err_t comm_rx_cb_unregister(uint8_t slot_id)
{
    if (slot_id >= MAX_CALLBACKS) {
        return COMM_ERR_PARAM;
    }
    if (s_rx_cb_table[slot_id].in_use == 0) {
        return COMM_ERR_UNKNOWN;  /* 槽位未使用 */
    }

    s_rx_cb_table[slot_id].in_use = 0;
    s_rx_cb_table[slot_id].cb = NULL;
    return COMM_OK;
}

/* 触发所有已注册的回调 - 收到数据时调用 */
void comm_rx_cb_trigger_all(uint8_t *data, uint16_t len)
{
    for (int i = 0; i < MAX_CALLBACKS; i++) {
        if (s_rx_cb_table[i].in_use && s_rx_cb_table[i].cb != NULL) {
            s_rx_cb_table[i].cb(data, len);
        }
    }
}

你想想看，这种设计的好处是什么？上层模块可以随时注册、随时注销，互不影响。通信模块收到数据后，遍历注册表，逐个调用。这就是典型的「观察者模式」在嵌入式里的落地。

性能考量：注册表遍历是 O(n) 的。如果回调数量很少（比如不超过 8 个），直接遍历没问题。如果数量大，可以用链表或者哈希表优化。我个人习惯先定一个合理的最大值，用数组实现，简单可靠。

2.4 整体架构图

下面这张图展示了接口抽象层的整体结构。从底层硬件到上层应用，中间通过注册表解耦。

2.5 注册表 vs 单回调：怎么选？

很多初学者会问：什么时候用单回调，什么时候用注册表？我整理了一个对比表格：

对比维度	单回调模式	注册表模式
适用场景	一对一通信（一个发送者一个接收者）	一对多通信（一个事件通知多个模块）
代码复杂度	低，一个函数指针变量搞定	中，需要数组/链表管理
内存开销	极小（4字节/8字节）	较大（取决于槽位数）
灵活性	低，只能有一个接收者	高，支持动态注册/注销
典型例子	定时器超时回调、DMA传输完成回调	数据接收分发、事件通知系统

我的建议是：能用单回调就别用注册表。简单就是可靠。只有明确需要「一对多」时，才上注册表。

2.6 避坑指南：我踩过的三个坑

做接口抽象层设计，有几个坑我反复踩过，今天一并说出来：

回调函数中不要做耗时操作。回调是在中断上下文还是任务上下文？这个必须明确。如果在中断里调回调，回调里千万不能有 printf、malloc 或者信号量等待。我曾经在一个中断回调里调了 printf，结果系统直接卡死。
注册表遍历时注意重入。如果在遍历注册表的过程中，有模块注销了自己，怎么办？我的做法是：先标记删除，遍历完再统一清理。或者用读写锁保护。
头文件不要互相包含。模块 A 的头文件包含模块 B，模块 B 又包含模块 A，编译时直接报错。我习惯用前置声明解决：struct module_b_t; 而不是 #include "module_b.h"。

血的教训：我曾经在一个项目里，回调注册表没有做重入保护。结果模块 A 在回调里注销了自己，注册表索引直接乱掉，后续模块 B 的回调被错误地调用了。排查了整整两天。从那以后，我所有注册表操作都加了临界区保护。

2.7 小结

接口抽象层设计，说白了就是三件事：

头文件规范：只暴露接口，隐藏实现。类型定义先行，返回值统一。
函数指针注册机制：用静态变量藏函数指针，通过注册接口暴露。NULL 检查不能省。
回调注册表：用数组管理多个回调，支持动态注册/注销。注意重入和性能。

这一套东西，我在多个项目里反复用过。从智能家居网关到工业控制器，从蓝牙协议栈到传感器融合，底层逻辑都一样。你把这个基础打牢了，后面讲组件通信、事件总线、消息队列，都会轻松很多。