C语言从句柄到对象 (一) —— 全局变量的噩梦与“多实例”的救赎

前言： 在《嵌入式开发基础与工程实践》系列中，我们聊了“回调函数”，解决了逻辑层面的解耦问题。 而在后台，经常有读者问我：“代码里的句柄（Handle) 到底是个什么东西？为什么大厂的代码库（SDK）里到处都是句柄？”

其实，“句柄” (Handle) 不仅仅是一个指针，它是 C 语言通向模块化和面向对象架构的第一把钥匙。

今天，我们不谈枯燥的语法，只谈一个最痛的实际问题：当产品需求从“控制 1 个电机”变成“控制 10 个电机”时，你的代码需要推倒重写吗？

---

一、 这种“菜鸟代码”，你一定写过

假设我们接到了一个任务：写一个电机驱动，控制转速和启停。 对于大多数初学者，或者在为了赶进度的场景下，代码通常是这样写出来的：

1.1 典型的“隐式单例”写法

motor.c (驱动文件) 我们把电机的状态定义为文件内部的全局变量（static），然后用函数直接操作它们。

// [数据区] 全局变量：隐式地只支持一个设备
static uint8_t g_current_speed = 0;
static uint8_t g_is_running = 0;

// [代码区] 操作函数
void Motor_Init(void) {
    HAL_GPIO_Init(GPIOA, GPIO_PIN_0, ...); // 硬件引脚写死在代码里
    g_current_speed = 0;
}

void Motor_SetSpeed(uint8_t speed) {
    g_current_speed = speed;
    // ... 操作硬件寄存器 ...
}

main.c (应用文件)

int main(void) {
    Motor_Init();
    Motor_SetSpeed(50); // 设置速度
}

1.2 这种写法有问题吗？

坦白说，如果你的板子上这辈子只会有 1 个电机，这种写法完全没问题。 这种写法叫 “单例模式” (Singleton)。它的优点是简单、直观、调用方便，不需要传参。在嵌入式系统中，对于 全局唯一的资源（比如系统滴答定时器 SysTick、唯一的看门狗 WDT、调试日志 Log），这种写法甚至是推荐的。

但是，噩梦往往源于那句：“老板说，新产品要加功能。”

---

二、 复制粘贴的灾难

老板突然走过来说：“这一版硬件升级了，我们需要控制 4 个电机。”

这时候，如果你坚持上面的写法，你只能祭出“复制粘贴大法”：

// 这种写法被称为“维护者的噩梦”

// --- 电机 1 ---
static uint8_t g_speed_1 = 0;
void Motor1_SetSpeed(uint8_t speed) { ... }

// --- 电机 2 ---
static uint8_t g_speed_2 = 0;
void Motor2_SetSpeed(uint8_t speed) { ... }

// --- 电机 3 ... (代码量膨胀 4 倍)

后果是显而易见的：

1. 代码冗余：同样的逻辑重复了 4 遍，Flash 空间被浪费。

2. 维护困难：如果发现电机启动逻辑有个 Bug，你得去改 4 个地方。只要漏改一个，Bug 就依然存在。

3. 无法扩展：如果明天老板要 10 个电机呢？

这就是 “面向过程” 编程在面对 “多实例” 需求时的死穴。

---

三、 句柄的诞生：将“数据”与“逻辑”剥离

为了解决这个问题，我们需要转换思维。 仔细观察上面的代码，你会发现：

• 变的（数据）：每个电机的引脚、当前速度、运行状态，是各自独立的。

• 不变的（逻辑）：设置 PWM、计算转速的算法（代码指令），对所有电机都是一样的。

我们为什么不能 只写一份代码，让它去操作 多份数据 呢？

3.1 第一步：定义对象 (The Context)

我们把原本散落在全局变量里的东西，全部“打包”进一个结构体。这个结构体，在架构术语里叫 Context（上下文），或者是 Instance（实例）。

// motor_driver.h

typedef struct {
    // 静态属性 (配置)
    GPIO_TypeDef *gpio_port;
    uint16_t      gpio_pin;
    
    // 动态状态 (变量)
    uint8_t       current_speed;
    uint8_t       is_running;
} Motor_t;

3.2 第二步：引入句柄 (The Handle)

现在，我们的函数不再操作死板的全局变量，而是操作作为参数传进来的指针。 这个指针，就是我们俗称的 “句柄”。

// motor_driver.h

// 定义句柄类型：也就是指向 Motor_t 的指针
typedef Motor_t* Motor_Handle; 

// 接口函数的第一个参数，永远是句柄！
// 翻译过来就是：“你要让我操作哪一个电机？”
void Motor_Init(Motor_Handle h, GPIO_TypeDef *port, uint16_t pin);
void Motor_SetSpeed(Motor_Handle h, uint8_t speed);

3.3 第三步：实现逻辑 (Implementation)

在 .c 文件里，我们通过句柄（指针）来访问具体的数据。

// motor_driver.c

void Motor_Init(Motor_Handle h, GPIO_TypeDef *port, uint16_t pin) {
    // 【核心】把配置信息存入句柄指向的内存区域
    h->gpio_port = port;
    h->gpio_pin  = pin;
    h->current_speed = 0;
    
    // 使用句柄里的信息初始化硬件
    HAL_GPIO_Init(h->gpio_port, h->gpio_pin, ...);
}

void Motor_SetSpeed(Motor_Handle h, uint8_t speed) {
    // 1. 修改句柄指向的状态
    h->current_speed = speed;
    
    // 2. 操作句柄指向的硬件
    Set_PWM_Hardware(h->gpio_port, h->gpio_pin, speed);
}

四、 工业级复用：一套代码，处处运行

现在，当我们要控制 4 个电机时，main.c 里的画风完全变了：

// main.c

// 1. 分配内存（创建 4 个对象实例）
Motor_t motor_1, motor_2, motor_3, motor_4;

int main(void) {
    // 2. 初始化：复用同一套 Init 代码，但传入不同的句柄
    // 就像给每个人发不同的身份证
    Motor_Init(&motor_1, GPIOA, GPIO_PIN_0);
    Motor_Init(&motor_2, GPIOA, GPIO_PIN_1);
    // ...

    // 3. 业务逻辑：想控制谁，就传谁的句柄
    Motor_SetSpeed(&motor_1, 50); // 让电机1 转 50%
    Motor_SetSpeed(&motor_2, 80); // 让电机2 转 80%
    
    // 无论你有 100 个电机，我的驱动代码一行都不用加！
}

这就是 C 语言的面向对象 雏形。

• Motor_t 结构体就是 “类” (Class) 的成员变量。

• Motor_SetSpeed 函数就是 “方法” (Method)。

• Motor_Handle 就是 “this 指针”。

---

五、 架构师的决策：什么时候该用句柄？

有些同学学会了这招后，觉得太酷了，恨不得把 LED_On() 都改成 LED_On(handle)。

请停下来！架构设计的核心在于“权衡”。

以下是一份决策参考表:

度	单例模式 (Global/Static)	多实例模式 (Handle)
典型场景	1. 系统滴答 (SysTick)   2. 调试日志 (Logger)   3. 唯一的看门狗 (WDT)	1. 外设驱动 (UART, I2C, SPI)   2. 功能模块 (电机, 传感器)   3. 软件对象 (定时器, 队列, 任务)
代码特征	Logger_Print("Msg");	UART_Send(hUart1, "Msg");
优点	调用极其简单，零开销。	代码复用性极高，逻辑清晰。
缺点	无法扩展，有第2个设备就得重写。	调用时必须维护一个句柄变量。

架构建议： 如果你正在写一个底层驱动库 (Driver/HAL)，请务必默认使用 句柄模式。即使现在板子上只有一个 I2C，保不齐下一代产品就用了两个。把驱动写成通用的库，是一劳永逸的事情。

---

六、 留个悬念：这种写法安全吗？

到目前为止，我们实现了代码的 复用。 但是，细心的读者会发现，在 main.c 里，用户其实可以直接访问结构体成员：

// 用户手滑，直接改了内存，但没有触发硬件更新！
motor_1.current_speed = 100;

这种 “裸露的结构体” 是非常危险的。用户可以绕过你的 API，随意修改内部状态，导致软件记录的值和硬件实际行为不一致，甚至让状态机逻辑崩溃。

真正的高级代码，用户是看不见结构体内部长什么样的。他们手里只握着一个“黑盒子”。

这就是 Windows 句柄 (HANDLE) 和 FreeRTOS 句柄 (TaskHandle_t) 的真面目。

下期预告： 如何利用 C 语言的 “前向声明” 和 “不透明指针” 技术，实现 SDK 级的极致封装？ 请关注专栏第二篇：《极致的封装：不透明指针与 SDK 级设计》。

/*******************************************
* Description:
* 本文为作者《嵌入式开发基础与工程实践》系列文之一。
* 关注我即可订阅后续内容更新，采用异步推送机制。
* 转发本文可视为广播分发，有助于信息传播至更多节点。
*******************************************/