4. 头文件设计规范：.h 文件的职责，避免循环依赖，前置声明技巧
头文件，说白了就是嵌入式模块的“对外名片”。
我见过太多项目，头文件里塞满了全局变量、函数实现、甚至还有 #include 套娃。最后编译报错，谁也说不清到底谁依赖了谁。今天咱们就把这件事理清楚。
4.1 .h 文件的职责边界
一个 .h 文件只做三件事：
- 声明公共接口：函数原型、extern 变量、宏定义
- 定义数据类型：结构体、枚举、typedef
- 提供编译常量：#define 常量、条件编译开关
我个人习惯，每个 .h 文件只对应一个模块。比如 uart.h 只声明 UART 驱动接口，绝不把 SPI 的东西放进来。你想想看，如果 uart.h 里突然冒出一个 spi_send()，别人读代码得多困惑。
核心原则：.h 文件只暴露“别人需要知道的东西”，隐藏实现细节。
我在项目中遇到过这样的案例：一个 system.h 包含了所有外设的头文件，结果每个 .c 文件都 #include "system.h"。编译倒是能过，但改一个外设接口，整个项目都要重新编译。这就是典型的“接口膨胀”。
4.2 循环依赖：嵌入式项目的噩梦
循环依赖长什么样？看这个例子：
// module_a.h
#include "module_b.h"
typedef struct {
int id;
ModuleB_t *b_ptr; // 依赖 ModuleB_t
} ModuleA_t;
// module_b.h
#include "module_a.h"
typedef struct {
int type;
ModuleA_t *a_ptr; // 依赖 ModuleA_t
} ModuleB_t;编译时，预处理器会无限递归展开头文件。最后编译器报错：unknown type name 'ModuleB_t'。为什么会这样？因为 module_a.h 还没解析完，又去解析 module_b.h，而 module_b.h 又回头找 module_a.h……死循环了。
避坑指南：我曾经在一个电机控制项目里，因为循环依赖导致编译时间从 30 秒暴涨到 5 分钟。排查了两天才发现是 motor.h 和 encoder.h 互相包含。从那以后，我定了一条铁律：任何 .h 文件都不允许包含另一个模块的 .h 文件，除非绝对必要。
4.3 前置声明：打破循环依赖的利器
前置声明是什么？简单说就是告诉编译器：“这个类型存在，具体定义在后面。” 编译器只需要知道类型名字，就能处理指针，不需要完整的结构体定义。
上面的循环依赖，用前置声明改一下：
// module_a.h
// 前置声明 ModuleB_t，不包含 module_b.h
typedef struct ModuleB_s ModuleB_t;
typedef struct {
int id;
ModuleB_t *b_ptr; // 现在可以用了
} ModuleA_t;
// module_b.h
// 前置声明 ModuleA_t
typedef struct ModuleA_s ModuleA_t;
typedef struct {
int type;
ModuleA_t *a_ptr;
} ModuleB_t;注意看，typedef struct ModuleB_s ModuleB_t; 这行就是前置声明。它告诉编译器：ModuleB_t 是一个结构体类型，具体成员在别处定义。因为这里只用了指针 ModuleB_t *，编译器不需要知道结构体大小，所以没问题。
使用前置声明的场景：
- 只需要指针或引用类型时
- 函数参数或返回值中用到该类型
- 避免不必要的头文件包含
4.4 什么时候必须包含头文件？
前置声明不是万能的。下面这些情况，必须 #include：
| 场景 | 必须包含的原因 | 示例 |
|---|---|---|
| 使用结构体成员 | 编译器需要知道成员偏移量 | obj->field = 1; |
| 定义该类型的变量 | 需要分配完整内存 | ModuleA_t var; |
| 使用该类型作为函数参数（值传递） | 需要知道类型大小 | void func(ModuleA_t param); |
| 继承或包含该类型 | 需要完整布局 | struct Derived { ModuleA_t base; }; |
说白了，只要编译器需要知道类型的大小或内部布局，就必须包含头文件。如果只是指针或引用，前置声明就够了。
4.5 头文件设计的最佳实践
我总结了一套“头文件健康检查清单”，每次写新模块都对照一遍：
- 每个 .h 文件都有 Include Guard：用
#ifndef/#define或#pragma once。我个人偏好#pragma once，简洁且不会写错宏名。 - 最小包含原则：只包含真正需要的头文件。能用前置声明就别
#include。 - 头文件不自带实现：不要在 .h 里写函数体，除非是内联函数或静态函数。
- 避免 extern 全局变量：如果必须用，用
extern声明在 .h 里，定义放在对应的 .c 里。 - 模块接口要稳定：.h 文件一旦发布，尽量少改。改接口意味着所有依赖模块都要重新编译。
我的个人习惯：每个模块的 .h 文件开头，用注释写明模块职责、依赖关系、使用示例。这样别人接手代码时，不用翻遍整个项目就能上手。
4.6 知识结构图：头文件设计规范全景
下面这张图，把本章的核心知识点串起来了。你可以把它当作设计头文件时的“导航地图”。
4.7 实战案例：重构一个“坏味道”的头文件
假设你接手了一个项目，看到这样的头文件：
// messy_module.h
#ifndef MESSY_MODULE_H
#define MESSY_MODULE_H
#include "adc.h"
#include "dac.h"
#include "timer.h"
#include "gpio.h"
int global_counter; // 错误：在头文件中定义变量
typedef struct {
int x;
int y;
} Point_t;
void do_everything(void); // 职责不清晰
#endif问题很明显：
- 包含了四个不相关的头文件
- 定义了全局变量（应该在 .c 里定义）
- 函数名太泛，不知道这个模块到底干什么
重构后：
// sensor_manager.h
#ifndef SENSOR_MANAGER_H
#define SENSOR_MANAGER_H
// 前置声明，避免包含 adc.h
typedef struct AdcDevice_s AdcDevice_t;
typedef struct {
AdcDevice_t *adc;
uint8_t channel;
float scale;
} SensorConfig_t;
int SensorManager_Init(SensorConfig_t *config);
int SensorManager_Read(SensorConfig_t *config, float *value);
#endif你看，职责清晰了，依赖减少了，别人一看就知道这个模块是管理传感器的。
小技巧：重构头文件时，先问自己三个问题：
- 这个 .h 文件到底暴露了什么接口？
- 这些 #include 真的都需要吗？
- 能不能用前置声明替代？
嗯，头文件设计这件事，看似简单，但做不好就是项目的“慢性毒药”。每次编译多等几秒，每次改接口都要改一堆文件，积少成多，项目就烂了。从今天开始，给你的每个 .h 文件做一次“健康检查”吧。