从 Demo 到本地 HAR 包：把 HarmonyOS JSBridge 运行时做成可复用库

项目地址：github.com/lichenyang5...

本文是 MiniAppRuntime-Harmony 系列第六篇，讲本地 HAR 包和 MyASCFRuntime 门面类。

说明：本文只讨论个人开源项目工程设计，基于公开 HarmonyOS 工程能力实现。

1. 为什么要抽成 HAR

项目早期，runtime 代码放在 entry 里是可以的：

text 复制代码

entry/src/main/ets/runtime/
  bridge/
  dispatcher/
  registry/
  biz/
  imp/
  error/
  logger/

这样能跑 Demo，但问题是：它更像一个应用内部实现，而不是一个可复用框架。

如果新建一个 HarmonyOS Demo 想复用这套能力，就不方便。

所以项目把 runtime 抽成了本地 HAR 模块：

text 复制代码

myascf_runtime/
  src/main/ets/
    bridge/
    dispatcher/
    registry/
    api/
    biz/
    imp/
    error/
    logger/
    Index.ets

entry 变成示例应用：

text 复制代码

entry/
  src/main/ets/pages/Index.ets
  src/main/resources/rawfile/web/

2. 抽取前后有什么区别

抽取前：

text 复制代码

entry 既负责 Demo 页面
entry 也负责 runtime 核心

抽取后：

text 复制代码

entry
→ 示例应用，负责 ArkWeb 页面和 H5 Demo

myascf_runtime
→ 本地 HAR 包，负责 JSBridge 运行时核心

这一步的意义很大。它说明项目不只是"某个页面能跑"，而是具备库化复用的可能。

3. 本地 HAR 怎么被 entry 依赖

entry 通过本地路径依赖 HAR：

json5 复制代码

// entry/oh-package.json5
{
  "dependencies": {
    "myascf_runtime": "file:../myascf_runtime"
  }
}

然后在 entry 的 ArkTS 页面中导入：

ts 复制代码

import { MyASCFRuntime } from 'myascf_runtime'

这样它不是远程包，而是项目内的本地 HAR 模块。本地开发时更方便调试，也更适合作为开源项目示例。

4. 为什么还要封装 MyASCFRuntime

如果外部 Demo 需要这样接入：

ts 复制代码

import {
  BridgeController,
  BridgeDispatcher,
  HandlerRegistry,
  RuntimeBootstrap,
  JavaScriptProxy
} from 'myascf_runtime'

那外部还是需要理解太多内部细节。

所以项目又封装了一个门面类：

text 复制代码

MyASCFRuntime

外部只需要：

ts 复制代码

private controller: webview.WebviewController = new webview.WebviewController()
private runtime: MyASCFRuntime = new MyASCFRuntime(this.controller)

然后注册到 ArkWeb：

ts 复制代码

Web({
  src: $rawfile('web/index.html'),
  controller: this.controller
})
.javaScriptProxy({
  object: this.runtime.getNativeProxy(),
  name: this.runtime.getProxyName(),
  methodList: this.runtime.getMethodList(),
  controller: this.controller
})

这样外部不需要直接组装 BridgeController、BridgeDispatcher、HandlerRegistry、RuntimeBootstrap 和 BridgeCallbackExecutor。

5. MyASCFRuntime 内部做了什么

门面类内部大致负责：

text 复制代码

创建 HandlerRegistry
创建 BridgeDispatcher
创建 BridgeCallbackExecutor
创建 BridgeController
创建 JavaScriptProxy
调用 RuntimeBootstrap 注册内置 API
提供 getNativeProxy()
提供 getProxyName()
提供 getMethodList()

它把"框架启动流程"收敛到一个类里。外部只关心怎么挂到 ArkWeb，内部负责怎么把 Bridge 链路组装起来。

6. 为什么这是一个重要分水岭

在此之前，项目可以说是一个 Demo。完成 HAR 和门面类之后，项目更像一个 SDK。

因为它开始具备这些特征：

text 复制代码

核心能力独立模块化
外部通过包名导入
对外入口收敛
内部实现隐藏
entry 变成示例应用
新建 Demo 可以复用 HAR

你可以这样讲：

我先在 entry 里跑通了 ArkWeb + JSBridge 的完整链路，然后把 runtime 核心抽成了本地 HAR 包，并通过 MyASCFRuntime 门面类收敛对外 API，让新建 HarmonyOS Demo 可以直接依赖这个 HAR 包接入运行时能力。

这句话比"我写了一个 WebView Demo"有分量得多。

7. HAR 模块应该导出什么

HAR 不应该把所有内部类都暴露出去。理想情况下，对外主要暴露：

ts 复制代码

export { MyASCFRuntime } from './MyASCFRuntime'

必要时再导出少量类型：

ts 复制代码

export { BridgeRequest, BridgeResponse } from './api/BridgeTypes'

内部这些可以不直接暴露：

text 复制代码

ToastBiz
ClipboardBiz
ToastImp
ClipboardImp
BridgeDispatcher
HandlerRegistry
RuntimeBootstrap

如果开发者不需要直接接触，就不要暴露。这叫对外 API 收敛。

8. 下一步可以怎么做

HAR 化之后，后续可以继续做 Storage API、Network API、Web 容器白名单、错误页、加载进度、更完善的 API 文档、DebugPanel 日志导出和独立示例工程。

但在继续加 API 前，最好先完善 README、HAR 使用文档、架构图、接入示例、截图和博客文章。因为这会直接提升项目的展示价值。