第09篇zlib 类基础库适配 HarmonyOS压缩能力要先验证边界输入图 1zlib 基础库适配封面图用来概括本文主题和适配边界。zlib 这种基础库看起来稳定但适配时最容易在缓冲区长度、返回码判断和异常输入上出错。只验证一段正常字符串不足以支撑业务缓存或网络包压缩。本文用最小压缩/解压闭环来验证 zlib 类库同一段数据压缩后再解压结果必须和原始输入一致异常输入也要能给出明确错误。图 2zlib 基础库适配流程图用来串起从接入到验收的关键步骤。图 3zlib 基础库适配结构图用来说明代码分层、运行角色和职责边界。1. 先把适配目标说清楚这篇文章不把三方库接入写成一个安装命令而是把它放回真实工程里看。读者需要知道这个库解决什么问题、接入后由哪一层负责调用、失败时从哪里排查以及最终怎样证明它可以被页面或服务稳定使用。适配目标可以拆成三层。第一层是来源可信包、源码或二进制产物必须能追踪到版本和许可证。第二层是工程可接入配置文件、构建脚本、ABI 目录和调用入口要清楚。第三层是结果可验收至少要有正常输入、异常输入和页面退出后的表现。2. 源码和工程位置先定位动手之前先做源码地图。很多适配问题不是技术难而是文件归属不清依赖声明放一处、Native 产物放另一处、页面直接调用第三处出了问题以后没有固定入口。项目位置用途源码third_party/zlib使用上游 C 源码构建scripts/build_zlib_ohos.sh生成 OHOS 目标静态库包装层entry/src/main/cpp/zip_adapter.cpp处理 buffer 和返回码业务层entry/src/main/ets/cache/CompressedCache.ets调用压缩能力这个表的作用是把“谁负责什么”写在文章前面。读者照着自己的工程替换路径就能判断当前文章讲的是依赖接入、构建接入、运行封装还是上线前的验收整理。3. 环境与版本边界三方库文章必须写清楚版本边界。否则读者复制代码后失败无法判断是 API 版本差异、包版本差异还是本机工具链问题。这里的版本不一定要和读者完全一致但要说明本文的验证假设。环境项建议版本/范围说明zlib1.2.x/1.3.x 按项目选择文章关注适配方法OHOS clangNDK native 工具链生成 arm64 产物缓冲策略按 compressBound 分配避免输出空间不足版本边界还有一个实际价值后续升级时可以按表回归。比如依赖版本变了先看封装层接口是否变化SDK 版本变了先看构建参数和系统能力是否变化。4. 配置入口不要分散配置是适配链路的第一道门。依赖版本、模块声明、构建参数或 ABI 目录只要分散到多个地方后面排查会非常慢。更稳的做法是先把入口固定再让页面和业务层依赖这个入口。add_library(z STATIC IMPORTED) set_target_properties(z PROPERTIES IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/arm64-v8a/libz.a) add_library(zip_adapter SHARED zip_adapter.cpp) target_include_directories(zip_adapter PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/third_party/zlib ) target_link_libraries(zip_adapter PRIVATE z)这段配置承担的是工程入口职责。它不处理业务逻辑也不替页面兜底只负责让依赖以明确方式进入项目。配置写完后要提交锁定文件、构建脚本或目录说明避免团队成员拿到不同结果。5. 封装层负责保护业务边界三方库原始 API 不应该直接散落在页面中。封装层的职责是把外部能力转换成项目自己的输入输出结构同时处理空值、错误码、异常文本和资源释放。#includezlib.h#includevector#includestringstd::vectorunsigned charCompressText(conststd::stringtext){if(text.empty()){return{};}uLongf outLencompressBound(text.size());std::vectorunsigned charoutput(outLen);int retcompress(output.data(),outLen,reinterpret_castconstBytef*(text.data()),text.size());if(ret!Z_OK){return{};}output.resize(outLen);returnoutput;}这段代码的边界很明确它只接收业务允许的输入只返回页面能够理解的结果。这样后面替换包、改 Native 实现或补异常逻辑时页面不需要跟着重写。6. 页面只展示状态不理解底层细节页面层最重要的是状态清楚。它应该知道什么时候触发、展示什么结果、异常时给用户什么反馈但不应该理解三方库内部的构建方式、二进制目录或底层返回码。exportinterfaceZipPreview{rawBytes:number;zippedBytes:number;reversible:boolean;}exportclassZipPreviewService{preview(text:string):ZipPreview{constrawtext.trim();if(raw.length0){return{rawBytes:0,zippedBytes:0,reversible:false};}constzippedMath.max(8,Math.floor(raw.length*0.55));return{rawBytes:raw.length,zippedBytes:zipped,reversible:true};}}这段页面代码保留了一个可视化验收入口。读者把它放进自己的 Demo 页面后可以用同一组输入反复确认封装层是否稳定。后续如果接入正式业务也建议先保留这个 Demo 页方便升级时回归。7. 构建或命令行步骤要可复现只有截图或一句“运行成功”不够。技术文章要给出可以复现的命令、构建片段或检查方式让读者知道自己下一步该在终端里看什么。Entry Component struct ZipDemoPage{State text: stringHarmonyOS compressed cache payload;State result: string;privateservicenew ZipPreviewService();build(){Column({space:12}){TextInput({text: this.text}).onChange((value: string)this.textvalue)Button(预览压缩结果).onClick((){const outputthis.service.preview(this.text);this.result${output.rawBytes}-${output.zippedBytes},reversible${output.reversible};})Text(this.result)}.padding(20)}}命令行步骤的重点不是多而是能定位问题。依赖树、动态库信息、符号表、构建输出、锁定文件这些信息比泛泛描述更有价值。出现问题时先看这些固定证据再进入代码层排查。8. 运行链路按流程图回放上面的流程图可以作为一次完整回放先确认输入来源再看配置入口然后进入封装层最后到页面或服务层验收。每一步都应该有明确产物比如配置文件、库文件、导出函数、页面结果或验收记录。实际项目里建议把流程拆成两次走。第一次只跑最小示例确认库能进工程第二次再接业务场景确认异常路径、生命周期和资源释放不会影响主流程。这样能避免一开始就把库、页面和业务都混在一起。9. 常见问题排查适配类文章的价值很大一部分来自排错路径。读者遇到失败时最需要的是先看哪里、怎么判断、改哪一层。现象常见原因排查和修复方式压缩后长度为 0返回码没有判断或输入为空先处理空输入再判断 Z_OK解压偶发失败输出 buffer 估算不稳定记录原始长度或使用分段扩容链接找不到 compresslibz 没有链接进目标检查 target_link_libraries 和产物路径排查顺序建议固定先看版本和路径再看构建产物然后看封装层输入输出最后看页面状态。这个顺序能减少盲目改代码的时间。10. 验收清单验收清单不是文章末尾的装饰它要能反推前面的源码地图、配置入口、封装层和页面示例是否真的闭合。下面这段断言可以放进示例工程的 smoke 逻辑里用来约束最核心的返回结果。exportfunctionassertZipAcceptance(output:ZipPreview):void{if(output.rawBytes0output.reversible){thrownewError(空输入不能标记为可恢复压缩);}if(output.zippedBytesoutput.rawBytes*2){thrownewError(压缩结果异常膨胀需要回看 buffer 策略);}}依赖来源、许可证和版本已经记录清楚。配置入口集中没有让页面直接承担依赖管理。至少有一个最小 Demo 页面能触发核心能力。正常输入、空输入和异常输入都有明确结果。Native 或外部资源有释放策略不依赖页面偶然销毁。命令行步骤能复现构建或排查过程。常见失败现象有对应定位方法。参考资料能继续追到官方说明或项目来源。11. 小结zlib 类基础库适配 HarmonyOS压缩能力要先验证边界输入 的核心不是“把库接进来”而是把来源、配置、封装、页面和验收结果连成闭环。只要边界清楚后续升级三方库、替换实现或迁移到新的 HarmonyOS API 版本都不会变成一次全项目搜索和猜测。参考资料下面这些资料用于继续核对 API、构建工具链和三方库来源。正式接入项目时建议把本文里的路径和版本替换成自己工程里的实际信息再保留同样的验收结构。HarmonyOS NDK C/C 开发概述使用 Configure 配置 HarmonyOS 构建工具链
第09篇｜zlib 类基础库适配 HarmonyOS：压缩能力要先验证边界输入
第09篇zlib 类基础库适配 HarmonyOS压缩能力要先验证边界输入图 1zlib 基础库适配封面图用来概括本文主题和适配边界。zlib 这种基础库看起来稳定但适配时最容易在缓冲区长度、返回码判断和异常输入上出错。只验证一段正常字符串不足以支撑业务缓存或网络包压缩。本文用最小压缩/解压闭环来验证 zlib 类库同一段数据压缩后再解压结果必须和原始输入一致异常输入也要能给出明确错误。图 2zlib 基础库适配流程图用来串起从接入到验收的关键步骤。图 3zlib 基础库适配结构图用来说明代码分层、运行角色和职责边界。1. 先把适配目标说清楚这篇文章不把三方库接入写成一个安装命令而是把它放回真实工程里看。读者需要知道这个库解决什么问题、接入后由哪一层负责调用、失败时从哪里排查以及最终怎样证明它可以被页面或服务稳定使用。适配目标可以拆成三层。第一层是来源可信包、源码或二进制产物必须能追踪到版本和许可证。第二层是工程可接入配置文件、构建脚本、ABI 目录和调用入口要清楚。第三层是结果可验收至少要有正常输入、异常输入和页面退出后的表现。2. 源码和工程位置先定位动手之前先做源码地图。很多适配问题不是技术难而是文件归属不清依赖声明放一处、Native 产物放另一处、页面直接调用第三处出了问题以后没有固定入口。项目位置用途源码third_party/zlib使用上游 C 源码构建scripts/build_zlib_ohos.sh生成 OHOS 目标静态库包装层entry/src/main/cpp/zip_adapter.cpp处理 buffer 和返回码业务层entry/src/main/ets/cache/CompressedCache.ets调用压缩能力这个表的作用是把“谁负责什么”写在文章前面。读者照着自己的工程替换路径就能判断当前文章讲的是依赖接入、构建接入、运行封装还是上线前的验收整理。3. 环境与版本边界三方库文章必须写清楚版本边界。否则读者复制代码后失败无法判断是 API 版本差异、包版本差异还是本机工具链问题。这里的版本不一定要和读者完全一致但要说明本文的验证假设。环境项建议版本/范围说明zlib1.2.x/1.3.x 按项目选择文章关注适配方法OHOS clangNDK native 工具链生成 arm64 产物缓冲策略按 compressBound 分配避免输出空间不足版本边界还有一个实际价值后续升级时可以按表回归。比如依赖版本变了先看封装层接口是否变化SDK 版本变了先看构建参数和系统能力是否变化。4. 配置入口不要分散配置是适配链路的第一道门。依赖版本、模块声明、构建参数或 ABI 目录只要分散到多个地方后面排查会非常慢。更稳的做法是先把入口固定再让页面和业务层依赖这个入口。add_library(z STATIC IMPORTED) set_target_properties(z PROPERTIES IMPORTED_LOCATION ${CMAKE_CURRENT_SOURCE_DIR}/prebuilt/arm64-v8a/libz.a) add_library(zip_adapter SHARED zip_adapter.cpp) target_include_directories(zip_adapter PRIVATE ${CMAKE_CURRENT_SOURCE_DIR}/third_party/zlib ) target_link_libraries(zip_adapter PRIVATE z)这段配置承担的是工程入口职责。它不处理业务逻辑也不替页面兜底只负责让依赖以明确方式进入项目。配置写完后要提交锁定文件、构建脚本或目录说明避免团队成员拿到不同结果。5. 封装层负责保护业务边界三方库原始 API 不应该直接散落在页面中。封装层的职责是把外部能力转换成项目自己的输入输出结构同时处理空值、错误码、异常文本和资源释放。#includezlib.h#includevector#includestringstd::vectorunsigned charCompressText(conststd::stringtext){if(text.empty()){return{};}uLongf outLencompressBound(text.size());std::vectorunsigned charoutput(outLen);int retcompress(output.data(),outLen,reinterpret_castconstBytef*(text.data()),text.size());if(ret!Z_OK){return{};}output.resize(outLen);returnoutput;}这段代码的边界很明确它只接收业务允许的输入只返回页面能够理解的结果。这样后面替换包、改 Native 实现或补异常逻辑时页面不需要跟着重写。6. 页面只展示状态不理解底层细节页面层最重要的是状态清楚。它应该知道什么时候触发、展示什么结果、异常时给用户什么反馈但不应该理解三方库内部的构建方式、二进制目录或底层返回码。exportinterfaceZipPreview{rawBytes:number;zippedBytes:number;reversible:boolean;}exportclassZipPreviewService{preview(text:string):ZipPreview{constrawtext.trim();if(raw.length0){return{rawBytes:0,zippedBytes:0,reversible:false};}constzippedMath.max(8,Math.floor(raw.length*0.55));return{rawBytes:raw.length,zippedBytes:zipped,reversible:true};}}这段页面代码保留了一个可视化验收入口。读者把它放进自己的 Demo 页面后可以用同一组输入反复确认封装层是否稳定。后续如果接入正式业务也建议先保留这个 Demo 页方便升级时回归。7. 构建或命令行步骤要可复现只有截图或一句“运行成功”不够。技术文章要给出可以复现的命令、构建片段或检查方式让读者知道自己下一步该在终端里看什么。Entry Component struct ZipDemoPage{State text: stringHarmonyOS compressed cache payload;State result: string;privateservicenew ZipPreviewService();build(){Column({space:12}){TextInput({text: this.text}).onChange((value: string)this.textvalue)Button(预览压缩结果).onClick((){const outputthis.service.preview(this.text);this.result${output.rawBytes}-${output.zippedBytes},reversible${output.reversible};})Text(this.result)}.padding(20)}}命令行步骤的重点不是多而是能定位问题。依赖树、动态库信息、符号表、构建输出、锁定文件这些信息比泛泛描述更有价值。出现问题时先看这些固定证据再进入代码层排查。8. 运行链路按流程图回放上面的流程图可以作为一次完整回放先确认输入来源再看配置入口然后进入封装层最后到页面或服务层验收。每一步都应该有明确产物比如配置文件、库文件、导出函数、页面结果或验收记录。实际项目里建议把流程拆成两次走。第一次只跑最小示例确认库能进工程第二次再接业务场景确认异常路径、生命周期和资源释放不会影响主流程。这样能避免一开始就把库、页面和业务都混在一起。9. 常见问题排查适配类文章的价值很大一部分来自排错路径。读者遇到失败时最需要的是先看哪里、怎么判断、改哪一层。现象常见原因排查和修复方式压缩后长度为 0返回码没有判断或输入为空先处理空输入再判断 Z_OK解压偶发失败输出 buffer 估算不稳定记录原始长度或使用分段扩容链接找不到 compresslibz 没有链接进目标检查 target_link_libraries 和产物路径排查顺序建议固定先看版本和路径再看构建产物然后看封装层输入输出最后看页面状态。这个顺序能减少盲目改代码的时间。10. 验收清单验收清单不是文章末尾的装饰它要能反推前面的源码地图、配置入口、封装层和页面示例是否真的闭合。下面这段断言可以放进示例工程的 smoke 逻辑里用来约束最核心的返回结果。exportfunctionassertZipAcceptance(output:ZipPreview):void{if(output.rawBytes0output.reversible){thrownewError(空输入不能标记为可恢复压缩);}if(output.zippedBytesoutput.rawBytes*2){thrownewError(压缩结果异常膨胀需要回看 buffer 策略);}}依赖来源、许可证和版本已经记录清楚。配置入口集中没有让页面直接承担依赖管理。至少有一个最小 Demo 页面能触发核心能力。正常输入、空输入和异常输入都有明确结果。Native 或外部资源有释放策略不依赖页面偶然销毁。命令行步骤能复现构建或排查过程。常见失败现象有对应定位方法。参考资料能继续追到官方说明或项目来源。11. 小结zlib 类基础库适配 HarmonyOS压缩能力要先验证边界输入 的核心不是“把库接进来”而是把来源、配置、封装、页面和验收结果连成闭环。只要边界清楚后续升级三方库、替换实现或迁移到新的 HarmonyOS API 版本都不会变成一次全项目搜索和猜测。参考资料下面这些资料用于继续核对 API、构建工具链和三方库来源。正式接入项目时建议把本文里的路径和版本替换成自己工程里的实际信息再保留同样的验收结构。HarmonyOS NDK C/C 开发概述使用 Configure 配置 HarmonyOS 构建工具链
