📚 课程目录第4章核心API概览

4. 核心API概览：初始化、验证、报告接口

说到SDK的API设计，我向来信奉一个原则：入口要稳，过程要清，出口要明。今天要讲的这三个接口，正好对应了这三个阶段。我个人习惯把这三步叫做「三驾马车」——跑不跑得动，快不快，稳不稳，全看它们配合得好不好。

你想想看，一个SDK再强大，如果连初始化都做不好，后续所有调用都是白费力气。所以这一章，我们就把这三个核心接口拆开揉碎了讲。

4.1 初始化接口：从Hello World到生产可用

初始化接口是SDK的第一个关卡。说白了，就是让我们的验证引擎知道三个事：你要兼容哪个系统、用什么方式验证、要不要记日志。

来看一个典型的函数签名：

int sdk_init(const char *os_name, 
             const char *os_version, 
             sdk_config_t *config);

这个函数里，os_name 传的是系统标识符，比如 "Windows"、"CentOS"、"openEuler"。os_version 则要精确到小版本号，像 "10.0.19044" 这样。我在项目中遇到过一个问题——有人只传了大版本号 "10"，结果验证报告里连补丁信息都丢了。所以我的建议是：版本号能精确到什么程度，就直接传什么程度。

我的习惯：初始化时我会额外检查一次 sdk_config_t 里的 timeout 字段。默认值通常是 30 秒，但在国产系统上，建议设到 60 秒以上。鸿蒙的接口响应有时候会慢一点，别让超时把你坑了。

配置结构体 sdk_config_t 长这样：

字段名	类型	说明	我踩过的坑
log_level	int	日志级别，0-3	别设成0，否则出问题连日志都看不到
log_path	char*	日志文件路径	路径别用中文，有些环境会乱码
timeout	int	单次验证超时（秒）	我习惯设90秒，给慢速磁盘留裕量
os_arch	char*	架构类型，如x86_64	如果不填，默认走当前系统架构

初始化成功返回 SDK_OK，失败返回错误码。我曾经只关注了成功分支，没处理 SDK_ERR_INIT_AGAIN——这个错误的意思是「已经初始化过了，别重复调」。后来我才意识到，有些人会在多线程场景下不小心重复初始化。嗯，这里要注意：做好幂等性判断，永远别在初始化上摔跟头。

4.2 验证接口：真正干活的函数

搞定了初始化，就该让SDK真正干活了。验证接口的设计，我比较满意的一点是它把三个动作合成了一个调用：

跑一遍：执行兼容性检查
收数据：收集环境信息和运行时指标
出结论：生成一份带级别的结果

函数签名是这样的：

int sdk_verify(const char *target_app_path,
               sdk_verify_result_t *result);

这个函数的灵魂在 sdk_verify_result_t 结构体里。我见过不少同行只关注返回码是 SDK_OK 还是 SDK_FAIL，其实真正有价值的信息全藏在结构体里。

核心真相：验证接口的返回值只代表「有没有跑完」，不代表「有没有通过」。真正的通过/不通过，要看 result 里的 status 字段。

结构体的关键字段：

字段	说明	取值范围
status	最终结论	PASS / WARN / FAIL / ERROR
score	兼容性打分	0 - 100
summary	一句话总结	如"完全兼容"
details	指标明细数组	每一项是一个key-value对

有个细节你可能没注意：details 数组里的每个条目都带了一个 suggest 字段。如果某条检查没通过，SDK会自动给出修复建议。我记得有一次用户发现某国产数据库在银河麒麟上得了个WARN，点开一看，建议是「调整共享内存参数」。按照建议改了，WARN变PASS。所以我的建议是：无论你觉得多熟悉那个系统，都看一眼details，说不定有意外收获。

注意线程安全：初始化接口和验证接口可以分开在不同线程调用，但同一个 sdk_handle 同时只能有一个验证请求。我遇到过进程池里同时发多个请求导致崩溃的案例，后来加了互斥锁才解决。

4.3 报告接口：把结果变成行动指南

验证跑完了，拿到了结果，接下来呢？报告接口就是干这个的——把二进制结构体，变成人能看懂、机器能解析的文档。

int sdk_generate_report(sdk_verify_result_t *result,
                        const char *output_path,
                        sdk_report_format_t format);

format 参数支持三种格式：

REPORT_JSON：我最推荐的格式，结构化强，方便CI/CD集成
REPORT_HTML：适合直接拿给测试经理看，带图表和颜色标记
REPORT_CSV：适合批量处理，多份报告放在一起做对比分析

不同的场景，用不同的格式。我个人习惯在开发阶段用JSON，测试阶段用HTML，回归阶段用CSV。格式转换不会影响原始数据——这是一个设计上的好决策：数据层和展示层彻底分离。

来看看JSON格式的片段：

{
  "report_version": "2.1",
  "generated_at": "2025-03-15T10:30:00Z",
  "os_info": {
    "name": "openEuler",
    "version": "22.03 LTS",
    "arch": "aarch64"
  },
  "compatibility": {
    "status": "WARN",
    "score": 82,
    "summary": "大部分兼容，存在2个次要问题"
  },
  "details": [
    {
      "check_point": "kernel_module",
      "result": "PASS",
      "suggest": ""
    },
    {
      "check_point": "syscall_behavior",
      "result": "WARN",
      "suggest": "建议检查mmap的MAP_ANONYMOUS标志兼容性"
    }
  ]
}

报告生成成功后，会返回 SDK_OK。如果路径不可写或磁盘满了，会返回对应的错误码。嗯，这里要提一句：报告生成不依赖网络，所有数据和模板都内嵌在SDK里。这意味着你可以在完全离线的环境里放心用。

4.4 三个接口的协作流程

说了这么多，你可能觉得这三个接口是各自独立的。其实不然，它们形成了一个完整的工作流。下面这张图能帮你理清关系：

这个流程走下来，你可能会问：如果某一步失败了，后续步骤还能走吗？ 答案是明确的——不能。初始化失败，验证调用直接返回 SDK_ERR_NOT_INIT。验证失败或没跑完，报告接口返回 SDK_ERR_NO_RESULT。所以写代码的时候，中间的结果检查一个都不能省。

4.5 处理错误：那些年我们踩过的坑

错误处理是API使用中最容易忽略的部分。我刚才说了，三个接口都有返回码。但很多人只检查返回码是不是 SDK_OK，对其他错误码完全不管。我见过最典型的一个案例：某团队在内部测试环境里一直用管理员权限跑程序，没出过问题。上线后用户用的是普通用户，结果初始化接口返回了 SDK_ERR_PERMISSION——他们没有处理这个错误码，程序直接崩了。

常见的错误码及其含义，我用个表整理出来：

错误码	含义	处理方式
SDK_OK	成功	继续后续逻辑
SDK_ERR_INIT_AGAIN	重复初始化	忽略或释放再重新初始化
SDK_ERR_NOT_INIT	未初始化就调用验证	检查调用时序，必须先调sdk_init
SDK_ERR_INVALID_PARAM	参数非法（如空指针）	检查传入参数是否为NULL
SDK_ERR_TIMEOUT	验证超时	增大timeout或优化应用启动速度
SDK_ERR_PERMISSION	权限不足	检查运行时用户权限和文件权限
SDK_ERR_NO_RESULT	没有可用的验证结果	先调sdk_verify再生成报告

我的经验：每一个错误码，你都应该写一段对应的处理逻辑。哪怕只是打印一行日志，也比你什么都不做强。我曾经踩过雷，只做了「成功」「失败」两个分支，结果线上报了个超时错误，日志里全是「失败」，我们根本不知道是哪种失败。后来重构了一次，把错误码拆开处理，排查问题的速度快了不止一倍。

好了，初始化、验证、报告这三个接口讲完了。记住我说的三步法：初始化要稳，验证要透，报告要清。把这三步练熟了，这套SDK的用法你就掌握了八成。剩下的零头，无非是些参数调优和边角情况的处理，用的时候遇到了自然就会了。