ArkWeb 手记 10｜把 ArkWeb 收成业务容器

HarmonyOS 7 · ArkWeb 混合应用开发手记 10

前九篇我们一直在修一个个问题：加载、生命周期、Bridge、返回、文件、登录、缓存、性能、安全。

最后一篇不再加新API。我们做一件更重要的事：把这些能力收成一个团队能复用的 ArkWeb业务容器。

1. 容器不是一个超大组件

最差的封装是 BusinessWeb.ets 两千行，什么都在里面。

我更喜欢拆成：

WebContainer
 ├─ WebStateManager
 ├─ BridgeManager
 ├─ NavigationPolicy
 ├─ AuthSync
 ├─ UploadHandler
 ├─ SecurityPolicy
 └─ WebLogger

2. 页面只传配置

interface WebPageConfig {
  url: string
  title?: string
  enableBridge: boolean
  allowedHosts: string[]
}

业务页面不应该重新写一遍生命周期和错误页。

3. 状态统一

enum WebState {
  Idle,
  Loading,
  Ready,
  Error
}

Loading、错误、重试都由容器管理。

4. Bridge 作为插件能力

不同页面声明自己需要的方法：

bridgeMethods: [
  'getAuthInfo',
  'openShare'
]

容器按配置注册，不给所有页面全量权限。

5. 返回策略也配置化

backMode: 'webFirst'

特殊页面可以用 nativeOnly 或业务自定义策略，但默认规则只有一套。

6. 登录变化统一广播

账号模块只通知容器层一次，各 Web实例再根据自己的状态接收，不要每个页面都监听账号中心。

7. 观测能力放进底座

至少记录：URL（脱敏）、加载耗时、错误码、Bridge method、requestId、资源版本。线上出了问题，容器日志应该能还原大部分路径。

8. 性能策略不要默认全开

预取、预连接、缓存、容器复用都应该有场景开关。优化能力越强，错误使用时副作用也越明显。

9. 安全策略不能被业务随便关

域名校验、敏感日志脱敏、Bridge白名单属于底线能力。业务配置可以变严格，不应该随手变宽松。

10. 一个最小使用方式

最后业务页面最好只剩：

BusinessWeb({
  config: {
    url: 'https://m.example.com/order',
    enableBridge: true,
    allowedHosts: ['m.example.com']
  }
})

剩下的 Loading、错误、返回、Bridge、认证同步和日志都由容器负责。

结尾

做到这里，这个系列其实走完了一条完整路线。

01 先把 Web 加载和生命周期管住；02 打通 ArkTS 与 H5；03 把 Bridge变成协议；04 解决返回栈；05 接文件；06 同步登录态；07 做缓存和离线；08用数据做性能；09 把安全边界补齐；10 再把这些能力收回一个可复用容器。

真正成熟的混合开发，不是会调多少 ArkWeb API，而是页面出了问题以后，你知道它现在在哪个阶段、谁拥有状态、消息从哪里来、权限到哪里结束。

如果你准备把这一套放进真实项目，最后一个练习不是再加功能，而是删代码：新建第二个Web 业务页面，看看还有多少加载、Bridge、返回和错误处理需要复制。

复制得越少，这个容器才越接近真正能用。