二、多文件项目结构：头文件(.h)与源文件(.c)的职责划分、项目目录组织规范

好，咱们接着聊。上一章我们把单个 .c 文件怎么组织讲清楚了，但真实项目里，没人会把几千行代码塞进一个文件里。你想想看，一个文件里既有传感器驱动、又有通信协议、还有用户界面逻辑……那维护起来简直是噩梦。

我刚开始工作那会儿，就接过一个前辈留下的“超级单体”项目。一个 .c 文件，一万两千行。改一个全局变量，能崩三个功能模块。后来我花了整整两周，把它拆成了十几个文件。从那以后，我深刻明白了一个道理：模块化不是花架子，是保命符。

2.1 头文件(.h)与源文件(.c)的职责划分

说白了，这就是 C 语言的“接口与实现分离”思想。我习惯用一个简单的类比来解释：.h 文件是合同，.c 文件是干活的人。

举个例子，假设我们要写一个 LED 控制模块：

// led.h —— 合同
#ifndef __LED_H__
#define __LED_H__

#include <stdint.h>

// 定义 LED 编号，方便调用
typedef enum {
    LED_RED,
    LED_GREEN,
    LED_BLUE,
    LED_COUNT
} led_id_t;

// 初始化所有 LED 引脚
void led_init(void);

// 打开指定 LED
void led_on(led_id_t id);

// 关闭指定 LED
void led_off(led_id_t id);

// 翻转指定 LED 状态
void led_toggle(led_id_t id);

#endif /* __LED_H__ */

// led.c —— 干活的人
#include "led.h"
#include <avr/io.h>   // 假设是 AVR 平台

// 内部引脚映射表，对外不可见
static const uint8_t led_pins[LED_COUNT] = {PB0, PB1, PB2};

void led_init(void) {
    DDRB |= (1 << PB0) | (1 << PB1) | (1 << PB2);
    PORTB &= ~((1 << PB0) | (1 << PB1) | (1 << PB2));
}

void led_on(led_id_t id) {
    if (id < LED_COUNT) {
        PORTB |= (1 << led_pins[id]);
    }
}

void led_off(led_id_t id) {
    if (id < LED_COUNT) {
        PORTB &= ~(1 << led_pins[id]);
    }
}

void led_toggle(led_id_t id) {
    if (id < LED_COUNT) {
        PORTB ^= (1 << led_pins[id]);
    }
}

2.2 哪些东西该放 .h，哪些不该放？

这个问题，面试里经常有人答不全。我列个清单，你对照着看：

类别	放 .h	放 .c
函数声明	✅ 对外接口函数	✅ 内部静态函数
全局变量	✅ 用 extern 声明	✅ 实际定义
宏定义	✅ 需要给外部用的	✅ 模块内部使用的
类型定义	✅ 结构体、枚举、typedef	❌ 一般不放在这里
静态变量	❌ 绝对不要放	✅ 模块私有数据
函数实现	❌ 除非是 static inline	✅ 所有普通函数

2.3 项目目录组织规范

好了，单个模块怎么拆分我们清楚了。那一个完整的嵌入式项目，文件夹该怎么摆？我这些年换过好几家公司，每家风格略有不同，但核心骨架大同小异。下面这个是我个人比较推崇的结构：

project_root/
├── app/                  # 应用层代码
│   ├── main.c
│   ├── task_manager.c
│   └── task_manager.h
├── bsp/                  # 板级支持包
│   ├── led.c
│   ├── led.h
│   ├── uart.c
│   └── uart.h
├── lib/                  # 第三方库或通用算法
│   ├── ring_buffer.c
│   ├── ring_buffer.h
│   ├── crc16.c
│   └── crc16.h
├── hal/                  # 硬件抽象层（可选）
│   ├── hal_timer.c
│   └── hal_timer.h
├── config/               # 配置文件
│   ├── board_def.h       # 板级引脚定义
│   └── project_conf.h    # 项目宏开关
├── doc/                  # 文档
│   └── architecture.md
├── test/                 # 单元测试
│   └── test_led.c
├── build/                # 编译输出（通常 .gitignore）
├── Makefile              # 或 CMakeLists.txt
└── README.md

为什么这么分？我解释一下：

• app/：放业务逻辑。比如你的产品是智能灯，那灯光模式切换、定时开关这些代码就在这。它调用 bsp 和 lib 的接口。
• bsp/：板级支持包。直接跟硬件寄存器打交道的代码。LED、UART、I2C 这些驱动都放这里。换一块板子，主要改这个目录。
• lib/：纯算法或数据结构。不依赖具体硬件。环形缓冲区、CRC 校验、PID 算法……这些代码可以跨平台复用。
• hal/：硬件抽象层。如果你需要支持多款芯片，这里放统一接口。比如 hal_timer.h 定义 timer_start()，不同芯片的 bsp 去实现它。
• config/：集中管理所有宏开关。比如用 #define ENABLE_DEBUG_LOG 来控制是否打印调试信息。改配置不用翻遍整个项目。

2.4 模块间的依赖关系

模块化之后，最怕的就是“循环依赖”。A 模块的 .h 包含 B 模块的 .h，B 模块的 .h 又包含 A 模块的 .h——编译器直接报错，或者更糟，出现未定义行为。

我画了一张图，帮你理清依赖关系应该怎么走：

看到没？依赖方向是单向的：app → bsp → hal，以及 app/bsp → lib。config 被所有模块包含，但它不包含任何模块。这就是所谓的“分层架构”，每一层只依赖它下面的层。

2.5 头文件包含的黄金法则

最后，分享几个我多年总结出来的头文件包含规范：

1. 每个 .h 文件必须有头文件保护宏：#ifndef __XXX_H__ / #define __XXX_H__ / #endif。这是基本功，但总有人忘。
2. .h 文件里尽量少包含其他 .h。能用前置声明（struct xxx;）解决的，就不要 #include。这样可以减少编译依赖，加快编译速度。
3. .c 文件里按顺序包含头文件：先包含自己的 .h，再包含本项目其他模块的 .h，最后包含标准库和系统头文件。这样能尽早发现遗漏的依赖。
4. 不要通过相对路径“../”来包含头文件。应该在 Makefile 或 IDE 里设置好 -I 包含路径，然后用 #include "bsp/led.h" 这种带模块前缀的方式。可读性高，也不容易搞错。

好了，这一章的内容就这些。多文件项目结构说白了就是两件事：把接口和实现分开，把文件夹按层次组织好。做到这两点，你的项目就成功了一半。剩下的，就是写代码时保持自律，别让模块间的依赖关系乱掉。

---

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