2. SDK 简介：功能、组件与架构
做兼容性验证，说白了就是让同一套代码在不同操作系统上都能老老实实跑起来。而 SDK 就是我们手里最趁手的工具——它把那些繁琐的底层差异都封装好了，你只管调接口就行。
我记得刚接触兼容性验证那会儿，手头只有几个孤立的测试脚本，每次换系统都要手动改一堆路径和 API 调用。后来用上这套 SDK，才体会到什么叫“标准化”。今天咱就聊聊这个 SDK 到底能干啥、里面有哪些零件、整体架构怎么搭。
2.1 SDK 的核心功能
SDK 不是为了炫技，而是解决三类实际问题：
- 环境探测：自动识别当前操作系统的类型、版本、内核、补丁等级。我遇到过客户在 CentOS 7 上部署，系统版本号写了 7.9，但内核却是 3.10.0-1160，兼容性列表里没这个组合……幸亏 SDK 的环境探测模块做了动态检测，提前报了个告警。
- 兼容性检查：对系统调用、动态库依赖、文件系统权限、网络栈参数做逐项比对。说白了就是帮你回答：“这个软件在 Ubuntu 22.04 上能不能装？会不会报 GLIBC 版本冲突？”
- 结果报告：把检查项、通过/失败、风险等级汇总成结构化报告，方便后续跟踪。我习惯让 SDK 同时输出 JSON 和 HTML 两种格式，CI/CD 拿 JSON 做断言，人看 HTML 快速浏览。
一句话总结：SDK 让你把“手工逐项验证”变成“一行代码调用”。
2.2 SDK 的组件构成
拆开这个 SDK，里面主要有这几个模块：
| 组件 | 职责 | 我在实践中踩过的坑 |
|---|---|---|
| 探测器（Prober） | 采集系统信息（内核、发行版、架构、安装的软件包列表） | 之前没考虑到 macOS 的 sw_vers 输出格式会随版本变化，后来加了正则兜底 |
| 检查器（Checker） | 执行兼容性规则匹配（库版本、系统调用可用性、文件系统特性） | 检查器默认只检查动态库，结果漏了静态链接的 OpenSSL，有一次上线前才发现证书解析失败 |
| 报告器（Reporter） | 格式化输出（JSON / XML / HTML / Markdown） | 早期报告里把警告和错误混在一起，导致研发同事分不清哪些需要立即修复 |
| 规则引擎（Rule Engine） | 加载并执行用户自定义的兼容性规则 | 规则语法从 JSON 换成 YAML 后，团队迁移成本比我预想的高，以后得预留向后兼容 |
小经验：Prober 和 Checker 之间建议用管道模式——Prober 只负责数据采集，不解释结果；Checker 只负责比对，不关心数据来自哪种系统。解耦之后，你很容易扩展新的检查项。
2.3 SDK 的整体架构
下面这张图展示了 SDK 的工作流程和模块间的关系。嗯，你想想看，从你调用 SDK 到输出报告，中间发生了什么？
看上图，基本流程是这样的：
- 你调用 SDK 后，调度器先接手，根据入参决定要启哪些模块。
- 探测器负责跑腿，从系统里捞数据；检查器拿着这些数据和规则引擎里的规则作比对。
- 比对结果丢给报告器，最终生成你要的报告。
⚠️ 注意：探测器是独立进程跑的，我曾经在 AIX 上碰到过性能瓶颈——单次探测跑了 12 秒。后来改成按需懒加载，只查必要的字段，时间降到了 2 秒以内。别小看这一项，CI 流水线里每次调用都等你 12 秒，研发同事会骂人的。
2.4 架构设计原则
这套架构之所以这么搭，背后有几个原则——我个人的经验，也是 SDK 团队反复迭代后沉淀下来的：
- 插件化：Prober、Checker、Reporter 都允许你通过配置文件注册自定义实现。说白了，你想加一个检查 Windows 注册表的 Checker，不需要改 SDK 源码，写个类挂上去就行。
- 无状态：每次探测和检查都不依赖前一次的结果。这样的好处是你可以随便并发跑，不用担心状态污染。我刚开始设计时还保留了全局变量，结果多线程下数据串了，排查了整整一个下午……从那以后我再也不在模块内部存任何状态了。
- 可追踪：每个检查项都有唯一 ID，报告里记录版本号和运行时间戳。遇到问题可以精确回溯：当时用的是哪个规则文件、哪个版本的 SDK。
2.5 一个简单的调用示例
光说不练假把式。下面是一段最简单的使用代码——你只需要导入 SDK，传一个路径和平台参数就行。
from os_compat_sdk import CompatChecker
# 实例化检查器，指定目标软件包路径和待测系统
checker = CompatChecker(
package_path="./my_app_1.0.tar.gz",
target_os="ubuntu:22.04",
target_arch="x86_64"
)
# 执行全量检查
result = checker.run()
# 输出摘要
print(result.summary)
print(result.pass_rate) # 比如 0.87 表示 87% 检查通过运行后会输出类似这样的结果：
检查项总数: 32
通过: 28
失败: 3
警告: 1
通过率: 87.5%我的个人习惯：在 CI/CD 里我会加上 assert result.pass_rate >= 0.9，让管道在通过率低于 90% 时自动拦截。你想想看，生产环境出一次兼容性问题，损失可比误拦截一次大得多。
好了，这一章我们梳理了 SDK 的功能边界、组件分工、架构流向和设计原则。下一块内容会深入到每个组件的内部实现，到时候再聊细节。暂时先把这些大框架印在脑子里，后面用到的时候自然会串联起来。