接口与实现分离：抽象数据类型、不透明指针、回调函数机制

各位同学，今天我们来聊聊嵌入式开发里一个特别实在的话题——接口与实现分离。说白了，就是怎么把“别人怎么用你的代码”和“你的代码内部怎么折腾”彻底切开。我做了十几年嵌入式，见过太多因为耦合太紧导致后期改不动、测不了的烂摊子。今天这三个工具，就是专门治这个毛病的。

一、抽象数据类型——把数据和操作打包

抽象数据类型，英文叫 Abstract Data Type，简称 ADT。它不是什么高深理论，就是一种编程思想：你定义一组操作，但不暴露内部数据怎么存的。

举个例子。你要做一个队列。别人只需要知道：queue_create、queue_push、queue_pop、queue_destroy。至于底层是用数组还是链表，是静态分配还是动态分配，调用者完全不用管。

我在项目中遇到过一件事：一个同事写了个队列模块，内部用数组实现，所有结构体定义都写在头文件里。后来需求变了，要改成支持动态扩容的链表。结果所有用到这个队列的模块都得重新编译，因为头文件里的结构体大小变了。这就是典型的“接口没分离好”。

二、不透明指针——真正的“黑盒子”

不透明指针，英文叫 Opaque Pointer。它是实现 ADT 最常用的手段。说白了就是：你在头文件里声明一个结构体类型，但只给一个前向声明，不给成员定义。

// queue.h
typedef struct Queue Queue;  // 前向声明，不暴露成员

Queue* queue_create(int capacity);
void   queue_push(Queue* q, int value);
int    queue_pop(Queue* q);
void   queue_destroy(Queue* q);

// queue.c
struct Queue {
    int* data;
    int  head;
    int  tail;
    int  capacity;
    int  count;
};

Queue* queue_create(int capacity) {
    Queue* q = (Queue*)malloc(sizeof(Queue));
    q->data = (int*)malloc(sizeof(int) * capacity);
    q->head = 0;
    q->tail = 0;
    q->capacity = capacity;
    q->count = 0;
    return q;
}

你看，调用者拿到的只是一个 Queue* 指针，根本不知道里面有什么。这就是不透明指针的精髓。

为什么会这样？因为一旦你暴露了结构体成员，别人就可能直接写 q->count = 0，绕过你的合法性检查。你想想看，这多危险。

三、回调函数机制——让调用者决定行为

回调函数，就是你把一个函数指针传给模块，模块在特定时机调用它。这是实现“控制反转”的经典手段。

我举个例子。你写一个定时器模块，希望定时器到期时执行某个动作。但你不知道用户想做什么动作。怎么办？让用户传一个函数指针进来。

// timer.h
typedef void (*TimerCallback)(void* context);

typedef struct Timer Timer;

Timer* timer_create(int interval_ms, TimerCallback cb, void* context);
void   timer_start(Timer* t);
void   timer_stop(Timer* t);

// 用户代码
void my_led_blink(void* ctx) {
    // 翻转LED
    HAL_GPIO_TogglePin(LED_GPIO_Port, LED_Pin);
}

int main() {
    Timer* t = timer_create(500, my_led_blink, NULL);
    timer_start(t);
    // 主循环做其他事
    while(1) {
        // ...
    }
}

这里的关键是 void* context 参数。它让回调函数能访问用户自定义的数据。我曾经踩过一个坑：早期版本没加 context 参数，结果回调函数里只能用全局变量，多实例场景下根本没法用。后来加了 context，问题迎刃而解。

四、三者如何配合——一个完整的例子

我们来看一个实际场景：一个按键检测模块。它需要检测按键按下、释放、长按，然后通知上层应用。

// button.h
typedef struct Button Button;

typedef enum {
    BUTTON_EVENT_PRESS,
    BUTTON_EVENT_RELEASE,
    BUTTON_EVENT_LONG_PRESS
} ButtonEvent;

typedef void (*ButtonCallback)(ButtonEvent event, void* context);

Button* button_create(int gpio_pin, ButtonCallback cb, void* context);
void    button_update(Button* btn);  // 周期性调用
void    button_destroy(Button* btn);

// button.c
struct Button {
    int  gpio_pin;
    int  state;
    int  press_count;
    ButtonCallback callback;
    void* context;
};

Button* button_create(int gpio_pin, ButtonCallback cb, void* context) {
    Button* btn = (Button*)malloc(sizeof(Button));
    btn->gpio_pin = gpio_pin;
    btn->state = 0;
    btn->press_count = 0;
    btn->callback = cb;
    btn->context = context;
    return btn;
}

void button_update(Button* btn) {
    int level = HAL_GPIO_ReadPin(btn->gpio_pin);
    // 简单的状态机处理
    if (level == 0 && btn->state == 0) {
        btn->state = 1;
        btn->press_count = 0;
        btn->callback(BUTTON_EVENT_PRESS, btn->context);
    } else if (level == 1 && btn->state == 1) {
        btn->state = 0;
        btn->callback(BUTTON_EVENT_RELEASE, btn->context);
    } else if (level == 0 && btn->state == 1) {
        btn->press_count++;
        if (btn->press_count > 100) {  // 假设100个周期算长按
            btn->callback(BUTTON_EVENT_LONG_PRESS, btn->context);
            btn->press_count = 0;
        }
    }
}

你看，这个模块用了不透明指针隐藏内部状态，用了回调函数让上层决定怎么处理按键事件。上层代码只需要创建 Button 对象，然后定期调用 button_update 就行。

五、知识体系总览

下面这张图把今天讲的核心逻辑串起来了。你仔细看看，三个概念之间的关系一目了然。

六、实际项目中的避坑指南

讲了这么多，我总结几条实战经验，都是血泪换来的。

• 不要为了抽象而抽象。如果模块只有内部使用，永远不会被外部调用，那没必要搞不透明指针。我见过有人给一个只有 3 个函数的模块也搞 ADT，纯粹浪费时间。
• 回调函数里别做阻塞操作。我曾经在一个网络模块的回调里做了 printf 打印日志，结果打印太慢导致丢包。后来改成用环形缓冲区异步打印，问题解决。
• 不透明指针的生命周期要清晰。谁创建谁销毁，别交叉管理。我见过一个项目，模块 A 创建了对象，模块 B 释放了，结果模块 A 还在用，直接野指针崩溃。
• 回调函数的 context 参数一定要用。别偷懒传 NULL。否则多实例场景下你根本不知道回调来自哪个对象。

---

公众号:蓝海资料掘金营，微信deep3321