NAPI 桥接十要

NAPI 是 ArkTS 与 Native 之间的桥。桥接写得好，两层相安无事；写得糙，随机崩溃与性能黑洞都是它。这篇给十条要诀——Air 系列 90 个工程反复验证过的实战清单。

▍一，桥面要窄
接口数量控制住（一个屏幕能看全的量级），参数用简单可序列化类型，复杂结构走文本序列化。宽桥（大而全的接口面）迟早变成维护灾难。

▍二，线程纪律是铁律
Native 重活全在后台线程；跨线程回 ArkTS 一律走线程安全函数机制（TSFN）投递——在 native 后台线程直接调桥是崩溃高发区。回调的归属线程在设计时就写清楚。

▍三，主线程零阻塞
ArkTS 主线程绝不做重活（初始化、IO、长计算全挪 native 后台线程）——主线程卡顿触发系统看门狗，冻结与无响应的处置都在等着。

▍四，桥不链库
Native 编译侧：桥模块保持薄（只做转发与类型转换），不链接重库——重库走运行时动态加载（移植工程的百库规模全靠动态加载通道）。

▍五，生命周期对齐
桥持有的资源（回调、表面、线程）要跟应用生命周期对齐——后台释放、前台重建的节奏显式设计，悬挂回调是随机崩的暗雷。

▍六，错误要过桥
Native 的错误码与异常要翻译成 ArkTS 能理解的结果（失败原因可读）——吞错误的桥让上层变成瞎子。

▍七，数据序列化定契约
两层交换的数据格式（字段、类型、版本）写成文档——两边各自演进时的兼容依据。版本号带上。

▍八，热路径少过桥
每秒上千次的路径（渲染帧、事件流）不要频繁过桥调用——攒批（一次传一批）或共享缓冲（数据放共享区，桥只传信号）。过桥本身有成本，热路径放大它。

▍九，调试通道预留
桥接口留诊断面（版本查询、状态导出）——排查两层扯皮问题时的裁判。

▍十，接口演进向后兼容
桥接口加了参数别删旧的（或用版本化接口）——ArkTS 侧与 Native 侧不总是同步更新。

▍自测
你的桥有几个接口？回调都从哪个线程来？错误怎么传？三问答不上，先把这篇再读一遍。

更多桥接实战案例，欢迎到 apps 板块翻看 56 篇《鸿蒙PC适配全记录》系列实录。