📚 课程目录第3章 C语言中的模块化

模块化设计的基石：头文件、静态函数与全局变量控制

各位同学，今天我们来聊聊嵌入式C语言模块化里最基础、也最容易踩坑的三个东西：头文件设计、静态函数、全局变量控制。说实话，我见过太多项目因为这几个点没处理好，后期维护起来简直想哭。我自己早期做的一个车载项目，就因为头文件互相包含成死循环，编译都过不了，最后只能重写整个模块接口——那滋味，真不好受。

头文件设计原则：接口的契约

头文件是什么？说白了，就是模块对外的一张「名片」。它告诉别人：我这个模块能干什么，你需要给我什么，我会返回什么。一个好的头文件，应该像一份清晰的合同，而不是一本糊涂账。

核心原则：头文件只放接口声明，不放实现细节。

我总结了几条实战中必须遵守的头文件设计原则：

单一职责：一个头文件只对应一个模块。别把定时器、GPIO、UART全塞到一个头文件里。
自包含：头文件本身就能编译通过，不需要用户先包含其他头文件。也就是说，你在头文件里用到的类型，要么自己定义，要么显式包含对应的头文件。
最小暴露：只暴露模块外部需要使用的函数和类型。内部使用的宏、结构体、辅助函数，统统藏起来。
防止重复包含：每个头文件都必须有头文件保护宏（include guard）。

小技巧：我习惯在头文件开头用 #pragma once 代替传统的 #ifndef 方式。虽然它不是C标准，但主流编译器都支持，而且省事、不容易出错。

来看一个典型的头文件示例：

// timer_module.h
#ifndef TIMER_MODULE_H
#define TIMER_MODULE_H

#include <stdint.h>
#include <stdbool.h>

/* 模块对外可见的类型定义 */
typedef enum {
    TIMER_MODE_ONESHOT,
    TIMER_MODE_PERIODIC
} timer_mode_t;

typedef struct {
    uint32_t    period_ms;
    timer_mode_t mode;
    void (*callback)(void);
} timer_config_t;

/* 模块对外接口 */
bool timer_init(timer_config_t *config);
bool timer_start(uint32_t timer_id);
bool timer_stop(uint32_t timer_id);
uint32_t timer_get_remaining_ms(uint32_t timer_id);

#endif /* TIMER_MODULE_H */

注意看，这个头文件里没有出现任何全局变量声明，没有内部函数的声明，也没有实现代码。用户拿到这个头文件，就知道怎么用这个定时器模块了。

静态函数：把内部细节藏起来

静态函数（static function）是C语言里实现信息隐藏最直接的手段。它的作用域被限制在定义它的源文件内，外部模块根本看不到它。

为什么要用静态函数？我举个例子。你写了一个温度传感器驱动，内部需要做CRC校验、数据滤波、单位换算。这些函数外部模块不需要知道，也不应该知道。把它们声明为static，既减少了命名冲突的风险，也防止了外部模块误调用内部函数。

我曾经踩过的坑：在一个多线程的嵌入式系统里，有个同事把内部函数声明为全局函数，结果另一个模块不小心调用了它，还传了错误的参数，直接导致系统死机。从那以后，我要求团队所有内部函数必须加static，除非有充分的理由不这么做。

静态函数的使用模式：

// sensor_driver.c
#include "sensor_driver.h"

/* 内部辅助函数，外部不可见 */
static uint8_t calc_crc(uint8_t *data, uint8_t len) {
    uint8_t crc = 0;
    for (uint8_t i = 0; i < len; i++) {
        crc += data[i];
    }
    return crc;
}

static float apply_filter(float raw_value) {
    static float last_value = 0.0f;
    float filtered = 0.7f * raw_value + 0.3f * last_value;
    last_value = filtered;
    return filtered;
}

/* 对外接口 */
float sensor_read_temperature(void) {
    uint8_t raw_data[4];
    /* 读取传感器原始数据... */
    if (calc_crc(raw_data, 4) != 0) {
        return -1.0f;  // CRC校验失败
    }
    float value = convert_raw_to_temp(raw_data);
    return apply_filter(value);
}

你看，calc_crc 和 apply_filter 都是static，外部模块根本不知道它们的存在。这就是模块化的精髓——接口清晰，内部实现可以随时重构。

全局变量的控制：能不用就不用

说到全局变量，我的态度很明确：能不用就不用，实在要用，也要严格控制。

全局变量的问题在哪？它破坏了模块的独立性。任何模块都可以读写它，你根本不知道它什么时候被谁改了。调试起来，就像大海捞针。

我见过最夸张的一个项目，全局变量列表打印出来有3页A4纸。后来出bug，三个工程师查了两周，最后发现是一个中断服务程序意外修改了另一个模块的全局变量。

我的原则：模块内部的状态，用static全局变量（文件作用域）；模块间的共享数据，用接口函数访问，而不是直接暴露变量。

来看一个对比：

做法	示例	评价
❌ 直接暴露全局变量	`extern int system_state;`	任何模块都能随意修改，无法控制
✅ 通过接口访问	`int get_system_state(void);` `void set_system_state(int state);`	可以在接口函数中加入校验、日志、互斥保护
✅ 模块内部静态变量	`static int current_state;`	只在当前文件可见，外部无法直接访问

如果确实需要全局变量，我建议遵循以下规则：

加前缀：比如 g_ 表示全局，m_ 表示模块内部静态变量。一眼就能看出变量的作用域。
只读全局变量用const：比如系统配置参数，声明为 const，防止被意外修改。
多任务环境加保护：如果全局变量会被中断或任务访问，必须加临界区保护或互斥锁。

// system_config.h
/* 只读全局配置，外部可以访问但不能修改 */
extern const system_config_t g_system_config;

// system_config.c
const system_config_t g_system_config = {
    .cpu_freq_mhz = 80,
    .stack_size = 2048,
    .task_priority = 3
};

知识结构总览

下面这张图，把本章的核心知识点串起来了。你可以把它当作模块化设计的检查清单：

避坑指南：我踩过的那些坑

最后，分享几个我亲身经历过的教训，希望能帮你少走弯路：

头文件循环包含：A.h 包含 B.h，B.h 又包含 A.h。编译器直接报错。解决办法：用前置声明（forward declaration）代替包含，或者重新设计模块依赖关系。
静态函数测试困难：static函数无法直接单元测试。我的做法是：在测试文件中用 #define static 临时取消static，或者把测试代码写在同一个源文件里。
全局变量初始化顺序：不同源文件中的全局变量初始化顺序是未定义的。如果A模块的初始化依赖B模块的全局变量，很可能出问题。解决办法：用显式的初始化函数，而不是依赖静态初始化。

个人习惯：我每个模块都会写一个 xxx_init() 函数，在系统启动时按依赖顺序调用。这样初始化顺序完全可控，也方便做错误处理。

好了，关于头文件设计、静态函数和全局变量控制，就讲到这里。这些东西看起来简单，但真正做好，需要在实际项目中不断打磨。记住一句话：好的模块化设计，是让每个模块都成为「黑盒子」——接口清晰，内部随便折腾。