📚 课程目录第2章模块化编程思想

模块化编程思想：头文件与源文件分离、全局变量管理、模块接口设计

好，咱们进入第二章。说实话，模块化编程这个概念，很多刚入行的朋友觉得不就是把代码拆开嘛，有啥好讲的？

但我见过太多项目，前期图省事，所有代码堆在一个 main.c 里，写到后面连自己都看不懂。我有个同事，一个文件写了三千多行，改个定时器参数要找半天，最后实在受不了，重写了。

所以这一章，咱们把模块化这件事聊透。说白了，就是怎么把代码组织得清清楚楚，让单片机项目像搭积木一样，好维护、好复用。

2.1 为什么要做头文件与源文件分离？

你想想看，一个单片机项目，少则几个模块，多则几十个。如果每个模块的声明和实现都混在一起，会是什么后果？

编译慢：改一行代码，整个项目重新编译。
依赖乱：A模块用了B模块的变量，B模块又依赖C模块，牵一发动全身。
复用难：想把某个功能移植到新项目，得从一堆代码里把相关部分抠出来。

我个人习惯，每个功能模块都拆成一对文件：.h 头文件和 .c 源文件。

核心原则：头文件只放“承诺”，源文件放“实现”。

.h 文件：对外暴露的接口声明、数据类型定义、宏定义。
.c 文件：具体的函数实现、模块内部使用的静态变量和辅助函数。

举个例子，一个 LED 驱动模块：

// led.h —— 对外接口
#ifndef __LED_H__
#define __LED_H__

#include "stdint.h"

// 初始化LED引脚
void LED_Init(void);

// 设置LED状态：1-亮，0-灭
void LED_Set(uint8_t status);

// 翻转LED
void LED_Toggle(void);

#endif

// led.c —— 内部实现
#include "led.h"
#include "gpio.h"  // 依赖底层GPIO驱动

static uint8_t led_status = 0;  // 静态全局变量，外部不可见

void LED_Init(void) {
    GPIO_SetPinDirection(LED_PIN, GPIO_OUTPUT);
    GPIO_WritePin(LED_PIN, 0);
    led_status = 0;
}

void LED_Set(uint8_t status) {
    GPIO_WritePin(LED_PIN, status ? 1 : 0);
    led_status = status;
}

void LED_Toggle(void) {
    led_status = !led_status;
    GPIO_WritePin(LED_PIN, led_status);
}

看到了吗？外部只需要知道 LED_Init()、LED_Set()、LED_Toggle() 这三个函数。至于内部怎么操作寄存器、用了哪个引脚，外部完全不用关心。

小技巧：头文件里一定要加 #ifndef / #define / #endif 防止重复包含。这是基本功，但总有人忘。

2.2 全局变量管理：能不用就不用，用就管好

全局变量，是嵌入式开发里最容易出问题的地方之一。我刚开始做项目时，特别喜欢用全局变量，觉得方便，哪里都能访问。结果呢？

调试的时候，不知道这个变量在哪个文件被改了。
多任务环境下，一个全局变量被多个中断和服务函数同时操作，数据就乱了。
想复用模块，发现它依赖了一堆外部全局变量，根本拆不开。

所以，我的原则是：能不用全局变量就不用，必须用的时候，要管好。

2.2.1 全局变量的三种管理方式

管理方式	说明	适用场景
模块内静态全局变量	在 .c 文件中用 `static` 修饰，只在当前文件可见	模块内部状态、缓存、计数器
通过接口函数访问	对外提供 get/set 函数，隐藏变量本身	系统参数、配置项、状态标志
全局结构体统一管理	把所有全局变量放在一个结构体中，集中定义	系统级状态、多模块共享数据

我个人最推荐的是第一种和第二种结合。模块内部的状态，用 static 藏起来；必须对外暴露的数据，通过函数接口访问。

我曾经踩过的坑：在一个电机控制项目里，我在头文件里定义了一个全局变量 uint8_t motor_speed，结果三个模块都在改它。调试了整整两天，才发现是中断服务函数和主循环同时写这个变量，导致速度值跳变。从那以后，我规定：所有跨模块共享的变量，必须通过函数访问，并且加上临界区保护。

2.2.2 全局结构体示例

// system_global.h
#ifndef __SYSTEM_GLOBAL_H__
#define __SYSTEM_GLOBAL_H__

#include "stdint.h"

typedef struct {
    uint8_t  system_mode;      // 系统工作模式
    uint16_t adc_value;        // ADC采样值
    uint8_t  error_code;       // 错误码
    uint32_t uptime_ms;        // 系统运行时间(ms)
} SystemGlobal_t;

// 对外声明，但定义在 .c 文件中
extern SystemGlobal_t g_sys;

#endif

// system_global.c
#include "system_global.h"

SystemGlobal_t g_sys;  // 实际定义在这里

void SystemGlobal_Init(void) {
    g_sys.system_mode = 0;
    g_sys.adc_value = 0;
    g_sys.error_code = 0;
    g_sys.uptime_ms = 0;
}

这样，所有全局变量都集中在一个结构体里，清晰明了。而且，你可以在 SystemGlobal_Init() 里统一初始化，避免遗漏。

2.3 模块接口设计：好的接口让人用着舒服

模块接口设计，说白了就是定义好“别人怎么用你的模块”。好的接口，使用者看一眼就知道怎么调用；差的接口，得翻半天文档，还容易用错。

2.3.1 接口设计三原则

单一职责：一个函数只做一件事。比如 LED_Set() 只负责设置状态，不要在里面加延时、读按键。
参数简洁：函数参数不要超过3个。超过3个，使用者容易搞混顺序。我见过一个函数有7个参数，每次调用都要对着头文件数半天。
返回值明确：成功或失败，用返回值或错误码表达清楚。不要用全局变量传错误状态。

2.3.2 接口命名规范

命名这件事，团队里一定要统一。我习惯用这种风格：

模式	示例	说明
模块名_动作	`UART_SendByte()`	最常用，一看就知道是哪个模块的什么操作
模块名_Get/Set	`Temperature_GetValue()`	读写属性时使用
模块名_Init	`Timer_Init()`	初始化函数，统一命名方便查找
模块名_Is/Has	`Button_IsPressed()`	返回布尔值的查询函数

2.3.3 接口设计示例：一个简单的按键驱动

// key.h
#ifndef __KEY_H__
#define __KEY_H__

#include "stdint.h"

// 按键事件类型
typedef enum {
    KEY_EVENT_NONE = 0,
    KEY_EVENT_PRESS,
    KEY_EVENT_RELEASE,
    KEY_EVENT_LONG_PRESS
} KeyEvent_t;

// 初始化按键模块
void Key_Init(void);

// 获取按键事件（非阻塞）
KeyEvent_t Key_GetEvent(uint8_t key_id);

// 设置长按阈值（毫秒）
void Key_SetLongPressThreshold(uint16_t ms);

#endif

这个接口设计得怎么样？

Key_Init()：初始化，必须最先调用。
Key_GetEvent()：获取事件，非阻塞，返回枚举值，清晰明了。
Key_SetLongPressThreshold()：配置参数，使用者可以按需调整。

你看，使用者不需要知道内部用了什么定时器、怎么消抖，只需要调用这三个函数就行。

我的习惯：接口设计好后，先写一个使用示例，看看调用起来顺不顺。如果调用代码看起来很别扭，那接口设计就有问题，需要调整。

2.4 模块化编程的完整结构图

下面这张图，展示了模块化编程的核心结构。每个模块独立编译，通过头文件暴露接口，模块之间通过接口交互，不直接访问对方的内部变量。

2.5 避坑指南：模块化编程常见问题

最后，分享几个我实际项目中遇到的坑，希望能帮你少走弯路。

坑一：头文件里放变量定义

我曾经在头文件里写了 uint8_t flag = 0;，结果多个 .c 文件包含这个头文件后，链接时报重复定义。记住：头文件里只能放 extern 声明，不能放定义。

坑二：模块之间循环依赖

A模块的.h文件包含了B模块的.h，B模块的.h又包含了A模块的.h。编译时就会报错。解决办法：重新审视模块划分，或者用前置声明（struct XXX;）打破循环。

坑三：接口设计得太“智能”

有人喜欢在接口函数里做太多事情，比如 LED_Init() 里不仅初始化引脚，还顺便点亮LED、启动一个定时器。结果使用者想单独初始化引脚都不行。记住：一个函数只做一件事。

好了，模块化编程的核心思想就这些。说白了，就是高内聚、低耦合。每个模块把自己的事做好，对外只暴露必要的接口，内部细节藏起来。这样，你的代码才能经得起时间考验，才能在多个项目间复用。