4、SDK目录结构设计：标准SDK目录布局、include/lib/bin目录规划、配置文件管理、版本号管理
好，咱们来聊聊SDK的目录结构。说实话，我见过太多SDK，一打开压缩包，文件散落一地，连个README都没有。这种SDK，开发者拿到手第一反应就是——这玩意儿靠谱吗？
目录结构，说白了就是SDK的脸面。它直接决定了开发者对你的第一印象。更重要的是，一个清晰的结构能帮开发者省下大量时间。我自己做SDK这么多年，踩过不少坑，今天就把这些经验掰开揉碎了讲给你听。
4.1 标准SDK目录布局
先说说我个人的习惯。一个标准的SDK，目录结构应该长这样：
my_sdk/
├── include/ # 头文件
├── lib/ # 库文件
├── bin/ # 工具和可执行文件
├── config/ # 配置文件
├── docs/ # 文档
├── examples/ # 示例代码
├── tools/ # 辅助工具
├── CMakeLists.txt # 构建文件
├── README.md # 说明文档
└── VERSION # 版本号文件
嗯，这里要注意：顶层目录不要超过10个。我在项目中遇到过有人把目录拆得特别细，结果开发者找个头文件要翻三层目录。你想想看，这得多浪费时间？
核心原则：目录结构要扁平化，每个目录只放一类文件。别把头文件和库文件混在一起，那是新手才会犯的错。
4.2 include/lib/bin目录规划
这三个目录是SDK的核心。我分别说说我的做法。
include目录
头文件的组织，我建议按模块分目录。比如：
include/
├── core/ # 核心API
│ ├── sdk_core.h
│ └── sdk_types.h
├── network/ # 网络模块
│ ├── sdk_http.h
│ └── sdk_websocket.h
└── utils/ # 工具函数
└── sdk_logger.h
为什么要这么分？因为开发者通常只关心某个模块。你想想看，如果所有头文件都堆在一个目录里，他找个函数声明都得翻半天。我曾经见过一个SDK，include目录下放了200多个.h文件，开发者直接崩溃了。
小技巧：每个模块的头文件，最好只暴露必要的API。内部使用的结构体和宏定义，放到内部头文件里，别让开发者看到。这叫做「接口最小化原则」。
lib目录
库文件的组织，要按平台和架构来分。我习惯这样：
lib/
├── linux/
│ ├── x86_64/
│ │ ├── libsdk.a # 静态库
│ │ └── libsdk.so # 动态库
│ └── arm64/
│ ├── libsdk.a
│ └── libsdk.so
├── windows/
│ ├── x86_64/
│ │ ├── sdk.lib
│ │ └── sdk.dll
│ └── arm64/
│ ├── sdk.lib
│ └── sdk.dll
└── macos/
└── x86_64/
├── libsdk.a
└── libsdk.dylib
这样做的好处是，开发者一眼就能找到自己需要的库。我曾经犯过一个错，把所有平台的库都放在同一个目录下，结果开发者链接错了库，折腾了两天才发现。从那以后，我再也不敢偷懒了。
注意：库文件的命名要统一。静态库用.a或.lib，动态库用.so、.dll或.dylib。别搞混了，否则开发者会骂娘的。
bin目录
bin目录放的是可执行文件和工具。比如：
bin/
├── sdk_config_tool # 配置工具
├── sdk_debug_tool # 调试工具
└── sdk_packager # 打包工具
这些工具要尽量轻量，别把整个SDK都编译进去。我见过有人把SDK的库文件也扔到bin目录里，结果开发者分不清哪个是工具，哪个是库。嗯，这其实是个很常见的坑。
4.3 配置文件管理
配置文件，我建议单独放一个config目录。为什么？因为配置文件经常需要修改，如果和代码混在一起，很容易误操作。
我的做法是这样的：
config/
├── sdk_config.json # 主配置文件
├── sdk_config.default.json # 默认配置
└── platform/
├── linux.json
├── windows.json
└── macos.json
这里有个关键点：默认配置和用户配置要分开。用户修改配置时，只改用户配置文件，别动默认配置。这样升级SDK时，用户的配置不会丢失。
避坑指南：我曾经遇到过用户升级SDK后，配置文件被覆盖了，结果整个系统跑不起来。后来我改成默认配置和用户配置分开存储，再也没出过问题。
配置文件的内容，我建议用JSON格式。为什么？因为JSON可读性好，解析也方便。当然，如果你对性能有要求，也可以用二进制格式。但说实话，对于大多数SDK来说，JSON完全够用了。
4.4 版本号管理
版本号，这是SDK的身份证。没有版本号的SDK，开发者根本不敢用。我见过有人把版本号写在代码里，结果每次发布都要改代码，麻烦得要死。
我的做法是：单独一个VERSION文件，只放版本号。
VERSION
1.2.3
版本号的格式，我推荐用语义化版本号：主版本.次版本.修订号。比如：
- 主版本：API发生不兼容的变更时增加
- 次版本：新增功能，但向后兼容时增加
- 修订号：修复bug时增加
举个例子：
| 版本号 | 含义 |
|---|---|
| 1.0.0 | 第一个正式版本 |
| 1.1.0 | 新增了网络模块，但API兼容 |
| 2.0.0 | API做了不兼容的修改 |
| 1.1.1 | 修复了一个内存泄漏的bug |
小技巧：版本号最好和Git标签对应起来。每次发布时，打一个Git标签，比如v1.2.3。这样开发者可以随时回溯到某个版本。
另外，版本号要写在头文件里，方便开发者程序化获取。比如：
#define SDK_VERSION_MAJOR 1
#define SDK_VERSION_MINOR 2
#define SDK_VERSION_PATCH 3
#define SDK_VERSION_STRING "1.2.3"
这样开发者就可以在代码里检查版本号，避免因为版本不匹配导致的问题。
4.5 知识体系结构图
说了这么多，我画个图帮你理清思路。这张图展示了SDK目录结构的核心逻辑：
这张图把SDK目录结构的核心逻辑串起来了。你看，从根目录出发，分出头文件、库文件、工具三大块，然后每块再按模块、平台、用途细分。最后，配置文件和版本号作为辅助，确保SDK的可维护性。
好了，关于SDK目录结构设计，我就讲这么多。记住，好的目录结构能让开发者爱不释手，坏的结构只会让人想骂娘。你想想看，你是想让开发者夸你，还是骂你？