平台宏、系统调用与缺失能力：建立可维护的 Native 抽象层

专栏：HarmonyOS 三方库适配实战（20/30） 核心问题：线程、时间、文件和网络调用不兼容时，怎样避免在上游源码里散落平台判断？

摘要

Native 适配最难维护的写法，是在几十个源文件中追加平台宏。更好的方法是先识别能力端口，再把 HarmonyOS 实现集中在适配层，核心只依赖小接口。本文用教学 text_core 展示“纯核心 + Node-API 边界”的最小形态，并给出文件、时间、日志和线程的抽象模板。当前纯核心与桥接已经双 ABI 编译；真实系统调用和设备行为未执行。

宏应该出现在哪里

允许出现的平台差异位置：

• 外层 CMake 选择源码和编译选项；
• 单独的 platform/harmony/ 实现文件；
• 极少数无法抽象的类型或编译器兼容点。

不应出现：

• 算法循环的每个分支；
• 公共头文件到处暴露平台类型；
• 上游测试中改变预期来迎合平台；
• 用宏直接吞掉错误。

图 1：核心依赖能力接口，HarmonyOS 实现集中在外层。

一个能力端口模板

class ClockPort {
public:
virtual ~ClockPort() = default;
virtual std::int64_t NowMillis() const = 0;
};

class FilePort {
public:
virtual ~FilePort() = default;
virtual Result<std::vector<std::uint8_t>> ReadAll(
const std::string& logicalId) = 0;
};

核心只看到 ClockPort 和 FilePort，不看到 ArkTS 对象、URI、权限或平台文件描述符。实际接口应按库需求收窄，不能为了“通用”一次抽象整个操作系统。

教学核心为什么没有平台宏

std::string NormalizeAscii(const std::string& input, bool lowercase)
{
std::string output;
output.reserve(input.size());
bool pendingSpace = false;
for (unsigned char ch : input) {
if (std::isspace(ch) != 0) {
if (!output.empty()) pendingSpace = true;
continue;
}
if (pendingSpace) {
output.push_back(' ');
pendingSpace = false;
}
output.push_back(lowercase
? static_cast<char>(std::tolower(ch))
: static_cast<char>(ch));
}
return output;
}

它没有文件、日志、线程或 Node-API 依赖，因此同一核心可在不同桥接层复用。注意：std::tolower 的区域和非 ASCII 语义有限，公开接口明确命名为 NormalizeAscii，不能宣传为完整 Unicode 归一化。

图 2：上游核心保持可比较，平台补丁集中、可审计、可在升级时重放。

缺失能力有四种诚实处理

“返回空值继续运行”通常最危险，因为调用方会把无能力误判为成功。

把平台端口接进 CMake，而不是散落进核心

平台目录应由构建层一次选择，核心目标不感知 __OHOS__：

add_library(text_core STATIC
core/normalize_ascii.cpp
core/text_service.cpp
)

add_library(text_platform STATIC
platform/harmony/harmony_clock.cpp
platform/harmony/harmony_file.cpp
)

target_link_libraries(textnative PRIVATE
text_core
text_platform
libace_napi.z.so
)

为了证明抽象没有改变核心语义，测试分两层：纯核心使用 fake 端口断言确定输出；HarmonyOS 端口使用目标环境检查权限、URI、时钟和错误映射。一个最小 fake 可以把时间固定为 1000，让超时测试不依赖真实时钟。

如果端口暂未实现，应在能力表中标成 unsupported，并让公共 API 返回稳定错误；不要链接一个永远返回空值的占位实现。

用 FakeClock 证明核心不依赖系统时间

把时间注入后，超时逻辑可以用确定输入测试，不必真的等待：

class FakeClock final : public ClockPort {
public:
explicit FakeClock(std::int64_t now) : now_(now) {}
std::int64_t NowMillis() const override { return now_; }
void Set(std::int64_t now) { now_ = now; }
private:
std::int64_t now_;
};

FakeClock clock(999);
assert(!HasExpired(clock, 1000));
clock.Set(1000);
assert(HasExpired(clock, 1000));

这个测试能证明核心使用了端口，并且截止时间边界采用 now >= deadline；它不能证明 HarmonyOS 端口选择了正确的单调时钟。平台实现仍要在目标环境检查时钟来源、单位、溢出和休眠行为。

如果核心测试仍必须包含 #ifdef __OHOS__ 才能通过，说明平台差异没有真正被隔离，应先调整依赖方向，再增加更多宏。

文件、线程和网络的额外问题

文件

路径格式、权限、URI、沙箱、编码和大文件读取都可能不同。不要把桌面绝对路径写入公共 API。

线程

核心线程安全不代表桥接线程安全。Node-API 的 env 和 ArkTS 对象只能按官方线程模型使用。

网络

代理、证书、超时、取消和后台限制都属于平台语义。仅替换函数名无法证明一致。

时间

墙上时间与单调时间用途不同。性能测量、超时和业务时间不能共用一个模糊 now()。

当前验证

教学核心没有平台宏与 HarmonyOS 头文件；Node-API 仅存在于 napi_init.cpp。text_core 静态库和 textnative 共享库为两种 ABI 构建成功。文件、网络、线程和真实时钟适配器没有实现，因此对应能力状态为 not implemented，不是“已兼容”。

常见失败：宏让所有平台都能编译，却改变行为

例如在不支持的分支里返回 0、空字符串或 true，可能让编译通过，但破坏错误契约。平台分支必须有测试向量和明确错误；无法实现时应阻止该功能进入支持列表。

本篇产物与下一篇门槛

本篇产物是一张平台抽象图和补丁边界规则。进入第 21 篇前，应能从 CMake 目标追到最终 .so，并用 ELF/归档工具检查 ABI、依赖链和包内路径。

官方来源

• 三方库适配：用于 HarmonyOS NDK 与三方库集成方式。访问日期：2026-10-18。
• Node-API 使用指导：用于桥接层与 ArkTS 对象边界。访问日期：2026-10-18。
• 使用 Node-API 接口进行异步任务开发：用于工作线程与 env 的边界。访问日期：2026-10-18。

验证声明

纯 C++ 核心、外层 CMake 与 Node-API 桥接已通过双 ABI 目标编译。本文没有实现或验证真实文件、网络、线程和设备系统调用；这些能力被明确留在平台适配层之外。