第09篇｜zlib 类基础库适配 HarmonyOS：压缩能力要先验证边界输入

图 1：zlib 基础库适配封面图，用来概括本文主题和适配边界。

zlib 这种基础库看起来稳定，但适配时最容易在缓冲区长度、返回码判断和异常输入上出错。只验证一段正常字符串，不足以支撑业务缓存或网络包压缩。

本文用最小压缩/解压闭环来验证 zlib 类库：同一段数据压缩后再解压，结果必须和原始输入一致，异常输入也要能给出明确错误。

图 2：zlib 基础库适配流程图，用来串起从接入到验收的关键步骤。

图 3：zlib 基础库适配结构图，用来说明代码分层、运行角色和职责边界。

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 版本差异、包版本差异，还是本机工具链问题。这里的版本不一定要和读者完全一致，但要说明本文的验证假设。

环境项	建议版本/范围	说明
zlib	1.2.x/1.3.x 按项目选择	文章关注适配方法
OHOS clang	NDK 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 不应该直接散落在页面中。封装层的职责是把外部能力转换成项目自己的输入输出结构，同时处理空值、错误码、异常文本和资源释放。

#include <zlib.h>
#include <vector>
#include <string>

std::vector<unsigned char> CompressText(const std::string &text)
{
    if (text.empty()) {
        return {};
    }
    uLongf outLen = compressBound(text.size());
    std::vector<unsigned char> output(outLen);
    int ret = compress(output.data(), &outLen,
        reinterpret_cast<const Bytef *>(text.data()), text.size());
    if (ret != Z_OK) {
        return {};
    }
    output.resize(outLen);
    return output;
}

这段代码的边界很明确：它只接收业务允许的输入，只返回页面能够理解的结果。这样后面替换包、改 Native 实现或补异常逻辑时，页面不需要跟着重写。

6. 页面只展示状态，不理解底层细节

页面层最重要的是状态清楚。它应该知道什么时候触发、展示什么结果、异常时给用户什么反馈，但不应该理解三方库内部的构建方式、二进制目录或底层返回码。

export interface ZipPreview {
  rawBytes: number;
  zippedBytes: number;
  reversible: boolean;
}

export class ZipPreviewService {
  preview(text: string): ZipPreview {
    const raw = text.trim();
    if (raw.length === 0) {
      return { rawBytes: 0, zippedBytes: 0, reversible: false };
    }
    const zipped = Math.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: string = 'HarmonyOS compressed cache payload';
  @State result: string = '';
  private service = new ZipPreviewService();

  build() {
    Column({ space: 12 }) {
      TextInput({ text: this.text }).onChange((value: string) => this.text = value)
      Button('预览压缩结果').onClick(() => {
        const output = this.service.preview(this.text);
        this.result = `${output.rawBytes} -> ${output.zippedBytes}, reversible=${output.reversible}`;
      })
      Text(this.result)
    }.padding(20)
  }
}

命令行步骤的重点不是多，而是能定位问题。依赖树、动态库信息、符号表、构建输出、锁定文件，这些信息比泛泛描述更有价值。出现问题时，先看这些固定证据，再进入代码层排查。

8. 运行链路按流程图回放

上面的流程图可以作为一次完整回放：先确认输入来源，再看配置入口，然后进入封装层，最后到页面或服务层验收。每一步都应该有明确产物，比如配置文件、库文件、导出函数、页面结果或验收记录。

实际项目里建议把流程拆成两次走。第一次只跑最小示例，确认库能进工程；第二次再接业务场景，确认异常路径、生命周期和资源释放不会影响主流程。这样能避免一开始就把库、页面和业务都混在一起。

9. 常见问题排查

适配类文章的价值，很大一部分来自排错路径。读者遇到失败时，最需要的是先看哪里、怎么判断、改哪一层。

现象	常见原因	排查和修复方式
压缩后长度为 0	返回码没有判断或输入为空	先处理空输入，再判断 Z_OK
解压偶发失败	输出 buffer 估算不稳定	记录原始长度或使用分段扩容
链接找不到 compress	libz 没有链接进目标	检查 target_link_libraries 和产物路径

排查顺序建议固定：先看版本和路径，再看构建产物，然后看封装层输入输出，最后看页面状态。这个顺序能减少盲目改代码的时间。

10. 验收清单

验收清单不是文章末尾的装饰，它要能反推前面的源码地图、配置入口、封装层和页面示例是否真的闭合。下面这段断言可以放进示例工程的 smoke 逻辑里，用来约束最核心的返回结果。

export function assertZipAcceptance(output: ZipPreview): void {
  if (output.rawBytes === 0 && output.reversible) {
    throw new Error('空输入不能标记为可恢复压缩');
  }
  if (output.zippedBytes > output.rawBytes * 2) {
    throw new Error('压缩结果异常膨胀，需要回看 buffer 策略');
  }
}

• 依赖来源、许可证和版本已经记录清楚。
• 配置入口集中，没有让页面直接承担依赖管理。
• 至少有一个最小 Demo 页面能触发核心能力。
• 正常输入、空输入和异常输入都有明确结果。
• Native 或外部资源有释放策略，不依赖页面偶然销毁。
• 命令行步骤能复现构建或排查过程。
• 常见失败现象有对应定位方法。
• 参考资料能继续追到官方说明或项目来源。

11. 小结

zlib 类基础库适配 HarmonyOS：压缩能力要先验证边界输入 的核心不是“把库接进来”，而是把来源、配置、封装、页面和验收结果连成闭环。只要边界清楚，后续升级三方库、替换实现或迁移到新的 HarmonyOS API 版本，都不会变成一次全项目搜索和猜测。

参考资料

下面这些资料用于继续核对 API、构建工具链和三方库来源。正式接入项目时，建议把本文里的路径和版本替换成自己工程里的实际信息，再保留同样的验收结构。

• HarmonyOS NDK C/C++ 开发概述
• 使用 Configure 配置 HarmonyOS 构建工具链