从一个 WebView Demo 开始，理解 ASCF 小程序底座到底在做什么

最近在做一个 HarmonyOS 练习 Demo，仓库地址是：

github.com/lichenyang5...

一开始我对这个项目的理解很简单：

在鸿蒙里嵌入一个 Web 页面，然后让 H5 调用 ArkTS 方法。

但继续往下做之后，我发现这个理解太浅了。

如果只是把网页放进鸿蒙的 Web 组件里，那它只是一个普通 WebView Demo。真正有价值的地方，不在于"页面能不能加载出来"，而在于：

Web 页面运行在一个受控的 Native 容器里，它如何安全、稳定、可观测地调用鸿蒙侧能力。

这也是我现在理解的 ASCF / 小程序底座的核心：

它不是一个页面技术，而是一套运行时容器能力。

一、先从一个真实场景说起

假设现在有一个 H5 服务页面，里面有一个支付按钮。

用户点击以后，H5 希望完成几件事：

调起鸿蒙侧支付能力；
支付完成以后，拿到支付结果；
支付成功后返回服务页面；
如果支付失败，要给用户提示；
如果 Native 没有响应，H5 不能一直 loading。

如果是普通前端页面，这个流程可能只是调用一个后端接口。

但在小程序 / ASCF 这类场景下，H5 自己没有直接调用系统能力的权限。它不能直接支付，不能直接扫码，不能直接调设备能力。

所以就出现了一个问题：

H5 想使用 Native 能力，但 H5 不能直接碰 Native，怎么办？

答案就是 JSBridge。

二、JSBridge 不是一个函数，而是一套协议

刚开始接触 JSBridge，很容易把它理解成：

H5 调用了 ArkTS 暴露出来的一个方法。

这个理解不能说错，但它只看到了表面。

更准确地说：

JSBridge 是 Web 和 Native 之间的一套通信协议。

也就是说，H5 不是随便调用一个方法，而是按照约定的数据格式，把自己想做的事情告诉 Native。

比如 H5 想发起支付，它可以发送这样一份数据：

json 复制代码

{
  "id": "req_001",
  "action": "pay",
  "params": {
    "orderId": "123456",
    "amount": "99.00"
  },
  "timeout": 5000
}

这里面几个字段很关键：

id：这次请求的唯一标识，用来匹配请求和响应；
action：告诉 Native 要调用什么能力；
params：传给 Native 的业务参数；
timeout：这次调用最多等待多久。

鸿蒙侧收到这段数据后，并不是直接写死执行某一个方法，而是先解析协议，再根据 action 做能力分发。

如果 action = pay，就走支付逻辑。

如果 action = getDeviceInfo，就走设备信息逻辑。

如果 action 不存在，就返回未知能力错误。

这就是 JSBridge 的价值：

H5 不需要知道 Native 具体怎么实现，只需要按照协议发送 action 和 params。

三、为什么不能让 H5 直接调用各种 Native 方法？

如果项目很小，可能会写成这样：

text 复制代码

H5 调 getDeviceInfo → ArkTS 直接处理
H5 调 pay → ArkTS 直接处理
H5 调 scan → ArkTS 直接处理

这种方式短期能跑，但问题也很明显。

当能力越来越多以后，代码会变得很乱：

text 复制代码

getDeviceInfo()
pay()
scan()
openLocation()
chooseImage()
setClipboard()
openToast()
navigateTo()

每一个能力都散落在不同地方，H5 调了什么、Native 做了什么、失败在哪里，都不好追踪。

所以更合理的方式应该是分层：

text 复制代码

H5 页面
  ↓
JSBridge 协议
  ↓
BridgeDispatcher
  ↓
NativeAbilityRegistry
  ↓
具体 Native 能力处理器

简单说：

H5 只负责发请求；
Bridge 协议负责规定数据格式；
Dispatcher 负责解析和分发；
Registry 负责管理可调用能力；
Handler 负责具体能力实现。

这样设计以后，新增能力时就不是到处写 if else，而是把能力注册进去。

比如：

text 复制代码

action: getDeviceInfo → getDeviceInfoHandler
action: openToast → openToastHandler
action: pay → payHandler

这时候，JSBridge 就不只是"调一个函数"了，而是变成了一个能力调用系统。

四、这个 Demo 真正在模拟什么？

我现在对这个 Demo 的定位是：

它不是一个普通 WebView Demo，而是一个简化版的小程序运行时实验台。

它主要验证的是这条链路：

text 复制代码

HarmonyOS Web 容器
  ↓ 注入 bridge 对象
H5 页面拿到可调用方法
  ↓ 按 JSBridge 协议组装请求
H5 调用 ArkTS 注入的方法
  ↓
ArkTS 收到请求
  ↓
BridgeDispatcher 根据 action 分发
  ↓
NativeAbilityRegistry 找到对应能力
  ↓
ArkTS 执行模拟 Native 能力
  ↓
返回统一 response 给 H5
  ↓
H5 根据 response 更新页面

也就是说，Web 页面只是业务层。

真正需要理解的是鸿蒙侧做了什么：

text 复制代码

Web 容器负责承载页面；
JSBridge 负责通信协议；
BridgeDispatcher 负责 action 分发；
NativeAbilityRegistry 负责能力注册；
WebGuard 负责 URL 白名单和访问控制；
BridgeLog / BridgeTrace 负责调用链路记录。

这些东西加起来，才像一个小程序底座。

五、Web 容器的重点不是加载，而是治理

普通 WebView 关注的是：

text 复制代码

能不能打开网页？
页面有没有显示？

但小程序底座关注的不只是加载，还包括治理。

比如：

text 复制代码

这个 URL 能不能打开？
外部链接是否允许跳转？
本地 rawfile 是否允许加载？
未知域名是否要拦截？
Web 页面报错了怎么兜底？
页面白屏了如何提示？

所以 Web 容器不只是一个显示页面的组件，它更像一个运行环境。

它要决定：

哪些页面可以运行；
哪些页面不能运行；
页面加载失败怎么处理；
页面跳转是否安全；
是否需要白名单拦截；
是否需要错误页兜底。

这就是"容器思维"。

如果只是写：

text 复制代码

Web({ src: xxx })

那只是用到了 Web 组件。

但如果能考虑白名单、错误处理、加载状态、返回控制、日志追踪，才是在做运行时容器。

六、统一 response 为什么重要？

H5 调 Native 以后，Native 一定要返回结果。

如果每个能力返回格式都不一样，H5 就会很难处理。

比如一个能力返回：

json 复制代码

{
  "success": true
}

另一个能力返回：

json 复制代码

{
  "code": 0,
  "data": {}
}

还有一个能力返回：

json 复制代码

{
  "status": "ok"
}

这样前端就会越来越乱。

所以更好的方式是统一 response 格式：

json 复制代码

{
  "id": "req_001",
  "code": 0,
  "message": "success",
  "data": {
    "payStatus": "success"
  }
}

这里最重要的是：

id：对应 H5 发起的那一次请求；
code：表示成功还是失败；
message：给出可读提示；
data：返回真正的数据。

这样 H5 只需要按一种方式处理响应。

成功时处理 data。

失败时处理 code 和 message。

这也是协议设计的意义。

七、错误也必须返回给 H5

真实项目里，最麻烦的不是功能成功，而是功能失败。

比如：

text 复制代码

H5 传来的 JSON 格式错了；
H5 少传了 action；
H5 调用了一个不存在的 action；
Native handler 执行时报错；
Native 处理超时了；

这些错误不能只在鸿蒙侧打印日志。

因为 H5 也需要知道发生了什么。

所以错误也应该走统一 response：

json 复制代码

{
  "id": "req_001",
  "code": 1003,
  "message": "UNKNOWN_ACTION",
  "data": {}
}

至少应该区分这些错误类型：

text 复制代码

JSON_PARSE_ERROR：H5 传来的不是合法 JSON
BAD_REQUEST：缺少必要字段
UNKNOWN_ACTION：调用了不存在的能力
TIMEOUT：调用超时
INTERNAL_ERROR：Native 内部异常

这一步很重要。

因为它说明 JSBridge 不是只处理成功路径，而是要把失败路径也工程化。

八、为什么要记录耗时和日志？

真实联调时，经常会遇到这种问题：

text 复制代码

H5 说没有收到返回；
Native 说已经返回了；
接口说支付成功了；
用户页面还停在 loading；

这种问题如果没有日志，就很难排查。

所以每一次 Bridge 调用，都应该记录：

text 复制代码

requestId
action
request params
response data
code
message
startTime
endTime
cost
errorStack

有了这些信息，就可以知道：

text 复制代码

这次调用从哪里来？
调用了哪个 action？
参数是什么？
是否成功？
失败原因是什么？
耗时多久？
最终返回给 H5 的内容是什么？

这就是链路可观测性。

也就是说，BridgeLog / BridgeTrace 不是锦上添花，而是 JSBridge 体系的一部分。

一个只会成功调用的 Demo，价值有限。

一个能记录成功、失败、耗时、错误原因的 Demo，才更接近真实工程。

九、支付、扫码、定位其实不是重点

很多时候我们会想：

要不要继续加支付？要不要继续加扫码？要不要继续加定位？要不要继续加分享？

这些功能当然可以加，但它们不是这个 Demo 最核心的价值。

因为这些只是能力项。

真正重要的是：

text 复制代码

H5 如何发起能力调用？
Native 如何识别能力？
能力如何注册？
权限如何控制？
错误如何返回？
调用如何追踪？

如果这套体系设计好了，支付只是一个 action，扫码也是一个 action，定位也是一个 action。

比如：

text 复制代码

pay
scanCode
getLocation
chooseImage
setClipboard
openToast

它们都可以挂到同一个能力分发系统里。

所以我现在更倾向于先把底座链路做好，而不是继续堆业务能力。

十、这个 Demo 最值得沉淀的设计思想

最后总结一下。

这个 Demo 最值得沉淀的不是代码细节，而是下面这套思路：

text 复制代码

把 H5 当作业务层；
把鸿蒙 ArkTS 当作底座层；
用 JSBridge 协议连接两边；
用 Dispatcher 做能力分发；
用 Registry 管理 Native 能力；
用 WebGuard 做容器治理；
用 BridgeLog 记录调用链路。

这套结构可以概括成一句话：

H5 不直接依赖 Native 实现，Native 也不直接写死业务逻辑，双方通过一套统一协议通信。

这就是小程序运行时的基本思想。

普通 WebView Demo 只解决"页面显示"的问题。

而 ASCF / 小程序底座要解决的是：

text 复制代码

页面在哪里运行？
页面能调用什么？
页面不能调用什么？
调用失败怎么办？
调用耗时怎么查？
Native 能力如何扩展？
H5 和 Native 如何解耦？

这些问题，才是这个 Demo 继续优化时最应该关注的方向。

十一、如果以后继续优化，我会优先做什么？

如果继续完善这个项目，我不会优先加支付、扫码这种具体能力，而会优先补这几块：

完善 BridgeTrace，记录每次调用的请求、响应、耗时和错误；
把 NativeAbilityRegistry 做成能力注册表；
给每个 action 增加描述、权限和是否 mock 的元信息；
完善 WebGuard，明确哪些 URL 可以访问，哪些必须拦截；
做一个轻量 DevTools 面板，方便查看 Bridge 调用链路；
在 README 里补充架构图和 3 分钟演示路径。

因为这些内容更能体现：

我理解的不只是 Web 组件，而是 Web 页面如何运行在鸿蒙侧提供的受控容器里。

结语

刚开始我以为这个 Demo 只是：

鸿蒙里嵌一个 H5 页面，然后互相调方法。

现在我更愿意把它理解成：

一个简化版的小程序运行时容器实验。

它的重点不是"WebView 怎么写"，而是：

如何让 Web 业务层通过统一协议、安全、稳定、可观测地调用鸿蒙 Native 能力。

这也是我觉得这个 Demo 最有价值的地方。