模块化编程：头文件设计、源文件分离、static与extern的正确使用

模块化编程，说白了就是「分而治之」。你想想看，一个几千行的C文件，你敢动吗？我反正不敢。早些年我接手过一个老项目，整个系统就两个.c文件，一个叫main.c，一个叫utils.c——utils.c足足八千行。改一个全局变量，编译全崩，那叫一个酸爽。

后来我学乖了。模块化不是花架子，它是让你能睡得着觉的工程手段。今天咱们就聊聊头文件怎么设计、源文件怎么拆分、static和extern这对「冤家」到底该怎么用。

一、为什么必须做模块化？

嵌入式项目有个特点：硬件耦合深、资源受限、团队协作频繁。如果你把所有代码塞进一个文件，会出现几个问题：

• 编译慢——改一行，整个项目重新编译
• 耦合高——全局变量满天飞，谁改了都不知道
• 复用难——想移植一个驱动？得从几千行里扒代码
• 测试难——单元测试？不存在的，根本拆不开

我在项目中遇到过最夸张的一次：一个同事把I2C驱动、定时器配置、LED闪烁逻辑全写在一个文件里，还用了大量全局变量。后来要换MCU，那个文件基本重写了。这就是典型的「能跑就行」思维留下的坑。

二、头文件设计——模块的「门面」

头文件是模块对外的契约。别人用你的模块，只需要看头文件就够了。所以头文件设计得好不好，直接决定了模块的易用性。

2.1 头文件的基本结构

我个人习惯，每个头文件都遵循这个模板：

#ifndef __LED_H__
#define __LED_H__

/* 头文件包含 */
#include "stdint.h"
#include "gpio.h"

/* 宏定义 */
#define LED_ON     1
#define LED_OFF    0

/* 类型定义 */
typedef enum {
    LED_RED,
    LED_GREEN,
    LED_BLUE
} led_color_t;

/* 全局变量声明（用extern） */
extern uint8_t led_brightness;

/* 函数声明 */
void led_init(void);
void led_set(led_color_t color, uint8_t state);
void led_toggle(led_color_t color);

#endif /* __LED_H__ */

注意几个要点：

• 头文件保护——#ifndef/#define/#endif 是标配，防止重复包含
• 只放声明，不放定义——函数实现、全局变量定义都在.c里
• 最小包含原则——头文件里只包含它真正需要的头文件，别图省事搞个万能头

2.2 头文件应该暴露什么？

很多新手喜欢把结构体定义、内部宏全部塞进头文件。这其实是个坏习惯。头文件暴露的应该是「接口」，而不是「实现细节」。

举个例子：

/* 不好的做法：暴露了内部结构 */
typedef struct {
    uint32_t base_addr;
    uint8_t  irq_num;
    void     (*callback)(void);
} uart_t;

/* 好的做法：只暴露操作函数 */
typedef struct uart_dev uart_t;  /* 不透明类型 */

void uart_send(uart_t *dev, const uint8_t *data, uint32_t len);
void uart_recv(uart_t *dev, uint8_t *buf, uint32_t len);

用不透明类型（opaque type），用户根本看不到结构体内部。这样你以后改结构体成员，用户代码完全不用动。我在做BSP驱动库时就是这么设计的，上层应用从来不需要关心寄存器地址。

三、源文件分离——模块的「内脏」

源文件是模块的实现。一个模块通常对应一个.c文件。但有时候一个模块太大，也可以拆成多个.c文件，只要它们共享同一个头文件就行。

3.1 文件组织原则

我一般按功能域来划分：

模块	头文件	源文件	说明
GPIO驱动	gpio.h	gpio.c	管脚操作
UART驱动	uart.h	uart.c	串口收发
定时器	timer.h	timer.c	定时/计数
应用逻辑	app.h	app.c	业务代码

每个模块内部，还可以再拆：比如uart.c里，可以把底层寄存器操作放到uart_hw.c，把协议解析放到uart_proto.c。但对外只暴露uart.h一个接口。

四、static与extern——模块的「守门员」

这两个关键字，是C语言模块化编程的基石。用好了，代码干净利落；用不好，全局变量满天飞。

4.1 static的两种用法

用法一：修饰函数内部的局部变量

void counter_init(void) {
    static uint32_t count = 0;  /* 只初始化一次 */
    count++;
    printf("count = %d\n", count);
}

这个count变量在函数退出后不会销毁，下次调用时保留上次的值。我在做按键消抖时经常用这个特性——记录上次按键状态，不用全局变量。

用法二：修饰函数或全局变量（文件作用域）

/* led.c */
static void delay_us(uint32_t us) {
    /* 内部辅助函数，外部不可见 */
    for(; us > 0; us--) {
        __NOP();
    }
}

static uint8_t led_state = 0;  /* 内部状态，外部不可见 */

void led_on(void) {
    led_state = 1;
    delay_us(100);
    /* 实际点亮LED的代码 */
}

加了static的函数和变量，只在当前.c文件内可见。这就是「信息隐藏」——模块内部怎么实现，外部不需要知道。

4.2 extern的正确用法

extern用于声明「这个变量或函数在其他.c文件里定义了」。它通常出现在头文件中：

/* led.h */
extern uint8_t led_brightness;  /* 声明，不是定义 */
extern void led_init(void);     /* 函数声明默认就是extern，可省略 */

然后在led.c里定义：

/* led.c */
uint8_t led_brightness = 50;    /* 定义，分配内存 */
void led_init(void) {
    /* 初始化代码 */
}

注意：extern只是声明，不分配内存。真正的定义只能有一处，否则链接器会报重复定义错误。

4.3 全局变量的「度」

很多人问：到底能不能用全局变量？我的答案是：能用，但要控制。

• 模块内部共享——用static全局变量，只在当前.c内可见
• 模块间共享——用extern声明在头文件里，但尽量少用
• 替代方案——用函数接口传递参数，或者用回调函数

举个例子，与其这样：

/* 不好的做法 */
extern uint32_t system_tick;  /* 到处都能改 */

/* 好的做法 */
static uint32_t system_tick;  /* 只有timer.c能改 */
uint32_t get_system_tick(void) {
    return system_tick;
}

这样即使别人想改system_tick，也只能通过你提供的接口。你可以在接口里加保护、加日志，出了问题也好排查。

五、知识体系总览

下面这张图，把模块化编程的核心逻辑串起来了：

六、避坑指南

最后，分享几个我踩过的坑：

• 头文件循环包含——A.h包含B.h，B.h又包含A.h。编译直接报错。解决办法：用前置声明代替#include，或者重新设计模块依赖关系。
• static函数无法测试——单元测试时，static函数没法直接调用。我的做法：在测试文件中用 #define static 临时去掉static，但正式代码里一定要加回来。
• extern数组大小不一致——在头文件里声明 extern uint8_t buf[]，但定义时是 uint8_t buf[64]。其他文件不知道大小，容易越界。建议在头文件里同时暴露大小宏。
• 全局变量初始化顺序——多个模块的全局变量在main之前初始化，但顺序不确定。如果模块A的初始化依赖模块B的变量，可能出问题。解决办法：用函数显式初始化，不要依赖静态初始化。

模块化编程，说白了就是「管好你自己的事，别管别人的闲事」。头文件是门面，源文件是内脏，static是围墙，extern是门牌号。把这四样用好，你的代码就能从「能跑」进化到「好维护、好扩展、好复用」。

嗯，今天就聊到这儿。下次你写代码时，不妨先问问自己：这个函数真的需要暴露出去吗？这个变量真的需要全局可见吗？答案往往是否定的。