3、头文件（include）组织技巧
头文件怎么放，说实话是 SDK 里最容易「翻车」的地方。我见过不少项目，功能写得挺好，结果用户一 include 就报重定义、找不到路径，体验直接归零。今天我把这几年踩过的坑和沉淀下来的套路，一次性说清楚。
核心原则：头文件组织不是「放哪儿都行」，而是 SDK 的「门面」。用户第一眼看到的就是 include 目录，乱不乱、好不好用，直接决定他对你 SDK 的第一印象。
3.1 按模块划分子目录
别把所有 .h 文件都塞到一个文件夹里。你想想看，一个 SDK 几十上百个头文件，全平铺开，找起来跟大海捞针一样。我个人的习惯是：一个模块一个子目录。
举个例子，一个网络通信 SDK 的头文件结构可以这样：
include/
├── core/ # 核心数据结构
│ ├── buffer.h
│ ├── packet.h
│ └── error.h
├── protocol/ # 协议层
│ ├── http.h
│ ├── websocket.h
│ └── tls.h
├── transport/ # 传输层
│ ├── tcp.h
│ ├── udp.h
│ └── quic.h
└── utils/ # 工具类
├── logger.h
├── timer.h
└── config.h这样做的好处很明显：
- 用户找文件快 —— 按功能模块定位，不用猜
- 编译依赖清晰 —— 模块间引用关系一目了然
- 方便裁剪 —— 不需要某个模块，直接删整个目录
小技巧：子目录名尽量用单数名词，比如 core 而不是 cores，protocol 而不是 protocols。保持命名风格统一，用户看着舒服，你也省心。
3.2 使用版本号子目录
这个习惯是我在一次惨痛教训后养成的。当时我们发布了一个 SDK，用户升级后接口变了，但头文件路径没变，结果一堆老代码编译不过。用户跑来骂街，我们还得一个个解释「你用的是旧版 API」。
后来我学乖了：在 include 根目录下加一层版本号子目录。
include/
├── v1/
│ ├── core/
│ ├── protocol/
│ └── utils/
├── v2/
│ ├── core/
│ ├── protocol/
│ └── utils/
└── v3/
├── core/
├── protocol/
└── utils/用户用哪个版本，就 include 哪个路径：
// 用户代码中
#include "v2/core/buffer.h" // 明确使用 v2 版本
#include "v3/protocol/http.h" // 新功能用 v3这样做的好处：
- 版本共存 —— 新旧版本可以同时存在，用户逐步迁移
- 回退方便 —— 出问题了切回旧版本，不用改代码
- 升级透明 —— 用户自己控制升级节奏
注意：版本号子目录只放「公开 API」的头文件。内部实现细节不要放进来，否则用户容易误用。我见过有人把内部结构体也塞进 v1/，结果用户直接访问私有字段，后面想改都改不了。
3.3 公共头文件与内部头文件分离
这是很多 SDK 容易忽略的点。我刚开始做 SDK 时，把所有头文件都扔到 include 目录下，结果用户能看到我们内部的一些宏定义、私有结构体。后来用户问「这个 XXX_INTERNAL_FLAG 是什么？我能不能用？」—— 尴尬了。
我的做法是：严格区分 public 和 private。
| 类型 | 存放位置 | 内容 | 用户能否使用 |
|---|---|---|---|
| 公共头文件 | include/ | API 声明、数据结构、错误码 | ✅ 可以 |
| 内部头文件 | src/internal/ 或 private/ | 内部宏、私有结构体、实现细节 | ❌ 不可以 |
| 平台相关 | include/platform/ | 平台抽象层 | ⚠️ 谨慎使用 |
具体实现上，我会在构建脚本里做限制：
# 安装 SDK 时，只复制公共头文件
install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
# 内部头文件不安装，只在编译时使用
target_include_directories(my_sdk PRIVATE src/internal/)这样用户拿到的 include 目录里，只有他该用的东西。内部细节？抱歉，看不到。
一个判断标准：如果你不确定某个头文件该不该公开，就问自己一个问题：「如果用户直接用了这个头文件里的东西，我以后还能不能改？」如果答案是不能，那就别公开。
3.4 防止头文件冲突的命名规范
头文件冲突这事儿，我遇到过太多次了。两个 SDK 都叫 config.h，用户一 include，编译器直接报重定义。用户一脸懵：「我啥都没干啊！」
解决方案其实很简单：加前缀。
我个人习惯用 SDK 名称的缩写作为前缀：
// 好的命名
my_sdk_config.h
my_sdk_buffer.h
my_sdk_error.h
// 不好的命名
config.h // 太通用，容易冲突
buffer.h // 同上
error.h // 同上如果 SDK 名称比较长，可以用缩写：
// 假设 SDK 叫 "FastNetworkEngine"
fne_config.h
fne_buffer.h
fne_error.h还有一种情况是子模块之间的冲突。比如 core 模块和 protocol 模块都有个 types.h，怎么办？
我的做法是：子模块名 + 文件名。
core_types.h
protocol_types.h
utils_types.h这样即使两个模块放在同一个 include 目录下，也不会冲突。
额外建议：在头文件开头加一段注释，标明这个文件属于哪个模块、什么版本、作者是谁。别小看这个习惯，三年后你自己回来看代码，会感谢当初写了注释的自己。
3.5 整体结构图
说了这么多，我画了一张图帮你理清思路。这张图展示了头文件组织的完整框架：
3.6 总结一下
头文件组织这件事，说白了就是让用户舒服，让自己省心。我这些年总结下来，就四个要点：
- 按模块划分子目录 —— 别平铺，分层放
- 使用版本号子目录 —— 多版本共存，升级不慌
- 公共头文件与内部头文件分离 —— 用户只看该看的
- 防止头文件冲突的命名规范 —— 加前缀，加模块名
嗯，这些技巧看起来简单，但真正做到位的项目其实不多。你如果现在去重构一下自己 SDK 的头文件结构，相信我，用户会感谢你的。