专栏：HarmonyOS 三方库适配实战（30/30）
核心问题：上游发布新版本后，怎样判断、合并并验证适配补丁，而不是重新手工移植一遍？
摘要
一次适配只是起点，真正的三方库工程要能跟随上游升级。本文把维护拆成八步：锁定旧基线、读取上游变更、生成影响表、重放平台补丁、编译与测试、对比质量、更新版本文档、分阶段发布。示例以教学库的"增加平台适配器、错误契约和 Native 夹具"作为维护演练，不声称发生了真实外部仓库升级，也没有执行 ohpm 发布。
维护闭环
图 1：升级不是合并结束，而是直到证据、版本和维护记录全部更新。
- 记录当前已发布/候选基线；
- 锁定新上游 tag 或 commit；
- 阅读变更日志和源码 diff；
- 生成影响表；
- 重放或重写最小平台补丁；
- 重跑测试与构建矩阵；
- 更新版本、CHANGELOG 和迁移说明；
- 先候选验证，再在单独授权下发布。
一张升级影响表
| 上游变化 | 公共 API | 平台补丁 | 测试 | 版本判断 |
|---|---|---|---|---|
| 修复空白处理 | 行为修复 | 无 | 重放文本向量 | patch 候选 |
| 新增可选参数 | 向后兼容 | 更新 ArkTS 模型 | 新增组合 | minor 候选 |
| 删除旧函数 | 破坏兼容 | 更新入口/声明 | 迁移测试 | major 候选 |
| 引入文件系统 | 新平台依赖 | 新增端口或拒绝 | 权限/设备 | 重新评估路线 |
| C++ ABI 变化 | Native 风险 | 重建所有 ABI | 加载/对象/异步 | 视公共契约决定 |
版本号是最终结论，不能只根据改动行数。
平台补丁要能重放
补丁按责任拆分：
text
0001-arkts-explicit-models.patch
0002-platform-text-source.patch
0003-public-entry.patch
0004-harmony-cmake-wrapper.patch
0005-node-api-contract.patch每个补丁说明：为什么需要、影响哪些上游文件、替代方案、验证动作和何时可以删除。不要把格式化、上游修复和平台改动混成一个大补丁。
为补丁集建立可比较的清单
补丁文件名只能说明顺序，不能证明它仍适用于当前上游。维护记录至少保存补丁哈希、触及区域、验证动作和淘汰条件：
yaml
upstream_old: "<old-tag-or-commit>"
upstream_new: "<new-tag-or-commit>"
patches:
- id: "0002-platform-text-source"
sha256: "<patch-sha256>"
touches: ["src/platform", "Index.ets"]
verify: ["ARKTS-COMPILE", "TEXT-SOURCE-001"]
remove_when: "上游提供可注入的文本来源接口"升级后依次检查：补丁能否干净应用、是否仍有必要、验证 ID 是否存在、产物哈希是否更新。上游若已经提供等价能力，删除补丁通常比"让旧补丁继续能套上"更安全。
冲突处理的正确顺序
- 先理解上游新实现是否已经解决原问题；
- 能删除旧补丁就删除；
- 需要保留时缩小到新结构的最小差异；
- 先跑上游行为向量，再跑 ArkTS/Native 契约；
- 失败时定位到单个补丁，不整批回滚。
回归证据清单
text
upstream identity and license
source and patch hashes
dependency tree and lock file
ArkTS static/compile results
HAR content and hash
Native ABIs, ELF and dependency chain
Local/Instrument/device test results
performance and size comparison
known limitations
README, CHANGELOG and migration guide
图 2：适配决策、补丁、产物、测试、质量与维护策略共同组成交付。
教学工程的维护演练
本轮以本地 1.0.0 夹具为基线，增加了：
- ArkTS 明确模型；
- 平台
TextSource； - 错误/异步公开契约；
- README、CHANGELOG、LICENSE；
- 双 ABI C++ 核心；
- Node-API 字符串、ArrayBuffer 和对象绑定；
- ArkTS 调用探针与测试向量。
2026-10-19 在 Node-API 参数边界、ArrayBuffer 上限、幂等关闭与异步工作项更新后，完成 clean debug 与 release 的 assembleHar、assembleHap，退出码均为 0；clean debug HAR/HAP SHA-256 为 50662C78D3E9944D45D8B67F03DF6681787173025202669949D124E3EF05B900、D8E2638E1DFC1E3B8C63BC02663AE8D588856A6A3C3FF59E9C29898C481DC688。这是一轮本地演练，不是外部上游 1.0.0→1.1.0 的真实升级；release 未签名、未混淆、未上设备。
什么时候决定不升级
出现以下情况可以暂缓：
- 新版本引入无法接受的平台依赖；
- 许可证或分发条件变化；
- 公共行为变化超过产品收益；
- 上游维护状态不清；
- 无法获得所需设备或安全验证；
- 补丁成本已高于替代库或重写成本。
维护决策应记录原因和复审日期，而不是让旧版本无声冻结。
发布与回滚
候选版本先在隔离消费者验证；发布后保留安装命令、版本、哈希和变更说明。发现问题时优先发布新修订或标记弃用，不能假设已发布版本号可以覆盖重用。任何远程发布、下架或删除都需要单独授权和平台回执。
毕业项目的完成定义不是"构建为绿色"，而是每个结论都能指向证据：
| 结论 | 最小证据 | 未满足时的写法 |
|---|---|---|
| 可编译 | 固定 SDK/工具链、命令、退出码 | 编译未验证 |
| 可被消费 | 清洁工程、准确包版本、导入与构建 | 仅源码工程可构建 |
| Native 可加载 | 目标 ABI 设备、候选哈希、加载日志 | 仅 ELF/归档已检查 |
| 行为兼容 | 可追溯向量与实际测试回执 | 测试已编写但未执行 |
| 性能可接受 | 固定设备、样本、统计与阈值 | 性能未测 |
| 可发布 | 全部门禁通过且获得单独授权 | No-Go，保留候选 |
这张表也构成回滚触发器：任何已声明结论在新候选上失去证据，就停止升级，而不是用旧版本的结果填补空白。
用一个可控变更演练升级判断
假设教学核心新增 lowercase 可选参数，同时保持默认值 false。这不是外部上游真实发布，而是一条用于验证流程的本地变更：
| 影响面 | 必须动作 | 通过条件 |
|---|---|---|
| ArkTS 模型 | 增加字段并保留默认值 | 旧调用无需修改即可编译 |
| 公共入口 | 导出新选项 | Index.ets 与 README 一致 |
| Native 声明 | 若同步暴露，更新 .d.ts 和参数校验 |
错误类型稳定、范围明确 |
| 测试 | 增加 false/true/省略 三组向量 |
旧向量全部重放 |
| 版本 | 公共能力向后兼容，评估 minor | 由实际发布契约最终确认 |
演练的停止条件也要明确：如果"省略参数"在旧入口中改变结果，就不能标成向后兼容；如果 ArkTS 与 Native 的默认值不同，先修契约，不能进入性能或发布阶段。
完成后保存旧/新源码哈希、补丁哈希、HAR/HAP 哈希和每条向量结果。由于本文没有真实外部 tag，这个演练只能证明维护步骤可执行，不能写成完成了某个上游版本升级。
常见失败：升级时顺手重构所有代码
上游升级、平台修复和内部重构同时发生，会让失败无法归因。先重放最小补丁并恢复基线，再单独提交重构；每一步都可回退、可测试。
专栏最终交付
完成 30 篇后，读者应拥有：适配决策记录、ArkTS/HAR 路线、Native/Node-API 路线、依赖与产物审计、测试/性能方案、许可证与发布门禁、升级维护流程。真正的模拟器、真机和远程发布仍必须在具备环境并获得授权后补齐。
官方来源
- oh-package.json5：用于版本、依赖和参数化维护。访问日期：2026-10-18。
- 构建 HAR：用于候选包重建与兼容边界。访问日期：2026-10-18。
- 发布共享包：用于版本发布准备和说明文件。访问日期：2026-10-18。
- HarmonyOS 开发者测试服务入门：用于升级后的测试矩阵与 CI/CD。访问日期：2026-10-18。
验证声明
本文的维护闭环已用本地教学夹具做结构化演练，并完成 ArkTS/HAR、双 ABI Native 与消费 HAP 的目标 SDK 构建。没有真实外部上游升级、Local/Instrument/设备测试、性能采样或 ohpm 发布；这些项目保持待验证。