1、SDK文件系统概述：什么是SDK文件系统、为什么需要定制、常见的SDK目录结构

各位好，我是老张。今天咱们开始聊SDK发布中的文件系统定制。说实话，这个主题我琢磨了挺久——因为很多开发者把SDK打包想得太简单了，觉得把头文件和库文件往那一扔就完事。嗯，我早年也这么干过，结果被客户骂得狗血淋头。

SDK文件系统，说白了就是你交付给客户的「开发工具包」的目录组织方式。它不只是文件堆砌，而是一套有逻辑、有层次的结构。你想想看，客户拿到你的SDK，第一眼看到的就是目录结构——这决定了他们对你们团队的第一印象。

1.1 什么是SDK文件系统

SDK文件系统，就是你把头文件、库文件、文档、示例代码、工具脚本等资源，按照一定规则组织起来的目录树。它定义了「什么东西该放哪」以及「客户该怎么用」。

我在项目中遇到过一家公司，他们的SDK把所有文件都塞在一个目录里，头文件和二进制混在一起，文档还是PDF格式散落在各处。客户每次集成都要花半天时间搞清楚「到底该引用哪个头文件」。这就是典型的反面教材。

一个规范的SDK文件系统，应该让客户拿到手就能猜到目录结构，不用看文档也能找到需要的东西。说白了，就是「约定优于配置」——目录结构本身就是一种文档。

1.2 为什么需要定制

你可能会问：「直接用开源项目的目录结构不行吗？」行，但不够。每个SDK都有自己的特点：

• 目标平台不同：Windows、Linux、macOS、嵌入式RTOS，目录组织方式完全不同
• 交付形态不同：有的只给二进制，有的给源码，有的两者都提供
• 客户群体不同：内部团队用和对外商业发布，要求天差地别
• 版本管理需求：多版本共存、增量更新、补丁机制，都需要目录结构支持

我记得有一次给一个物联网芯片厂商做SDK，他们的客户遍布全球，有的用Keil，有的用IAR，还有用GCC的。如果目录结构不做定制化设计，每个客户都得自己折腾一遍集成流程——那我们的技术支持团队就别想干别的了。

1.3 常见的SDK目录结构

下面这张图展示了SDK文件系统的核心骨架。我把它画出来，方便你有个整体印象。

下面我逐个说说每个目录的讲究。

include/ — 头文件目录

这是客户最先接触的地方。我个人习惯把头文件按模块分层组织：

include/
├── sdk_name/
│   ├── core.h          # 核心API
│   ├── config.h        # 配置选项
│   ├── types.h         # 数据类型定义
│   └── module/
│       ├── module_a.h
│       └── module_b.h
└── sdk_name.h          # 统一入口头文件

注意，头文件不要直接扔在include根目录下。加一层命名空间目录（比如sdk_name/），可以避免和其他SDK的头文件冲突。我曾经见过两个SDK都定义了types.h，客户一编译就报重定义——那场面，相当尴尬。

lib/ — 库文件目录

库文件要按平台、架构、编译选项分目录。我建议的层次结构：

lib/
├── windows/
│   ├── x86/
│   │   ├── debug/
│   │   │   └── sdk_name.lib
│   │   └── release/
│   │       └── sdk_name.lib
│   └── x64/
│       ├── debug/
│       └── release/
├── linux/
│   ├── x86_64/
│   └── arm64/
└── macos/
    └── universal/

bin/ — 工具与可执行文件

这个目录放的是SDK配套的工具链和辅助脚本。比如：

• 代码生成器（code generator）
• 配置文件校验工具
• 日志解析器
• 固件烧录工具
• 环境检测脚本

bin/目录也要按平台分，因为工具通常是平台相关的。另外，我建议把工具的版本号写在文件名里，方便客户在多个版本间切换。

doc/ — 文档目录

文档是SDK的「说明书」。我见过太多SDK把文档扔在一个PDF里，客户想查某个API的用法得翻半天。好的做法是：

doc/
├── api_reference/      # API参考文档（HTML或Markdown）
├── getting_started.md  # 快速入门
├── migration_guide.md  # 迁移指南（版本升级时特别重要）
├── release_notes.md    # 发布说明
└── license.txt         # 许可证文件

我个人强烈建议用HTML或Markdown格式，不要只给PDF。因为客户经常需要搜索特定关键词，PDF的搜索体验远不如HTML。

example/ — 示例工程

示例工程是客户学习SDK最快的方式。我建议每个示例都是一个独立的、可编译的工程：

example/
├── hello_world/        # 最简单的入门示例
│   ├── CMakeLists.txt
│   ├── main.c
│   └── README.md
├── basic_usage/        # 基本功能演示
└── advanced/           # 高级特性示例

每个示例都要有README，说明这个示例演示了什么功能、怎么编译、预期输出是什么。我曾经犯过一个错误——示例代码能编译，但跑起来就崩，原因是忘了更新示例里的API调用方式。从那以后，我要求每个示例在发布前必须经过完整的编译+运行测试。

1.4 目录结构设计原则

最后，我总结几条原则，供你参考：

原则	说明	我的经验
一致性	所有版本保持相同的目录结构	客户升级时不用重新学习
自描述	目录名和文件名能说明用途	避免用 src1、src2 这种命名
扁平化	目录层级不超过4层	太深了客户找文件很痛苦
可扩展	预留扩展点，方便后续加模块	比如 include/ 下按模块分目录