混合开发与桥接

一句话定位

这一模块不把 MethodChannel / JSBridge / Flutter plugin / 多端职责划分 平铺成名词清单，而是先回答：一次跨端调用，到底是哪一层发起、哪一层承接、哪一层兜底、哪一层负责最终业务事实。

你会在这里解决什么判断

• Flutter 调原生，应该用一次调用、事件流还是双向消息？
  • 一句话答：一次调用用 MethodChannel，事件流用 EventChannel，复杂双向 / 多端统一用消息协议；按数据流向与实时性选。
• Flutter plugin 在系统里到底扮演什么职责？
  • 一句话答：plugin 是 Flutter 与原生能力之间的适配层：把原生 API 封装成 Dart 可调接口，并负责生命周期与线程归属。
• WebView / H5 / JSBridge 双向通信，哪些数据可以桥接，哪些不该桥接？
  • 一句话答：轻量结构化数据（JSON）适合桥接；大文件、敏感凭据、重计算不该走桥，应走原生通道或不下发。
• 登录态、支付、分享、权限、归因这种宿主能力，应该放哪层收口？
  • 一句话答：放宿主原生层统一收口，Flutter / H5 只做调用，避免各端重复实现与凭据分散。
• Android / iOS / Flutter / H5 同一业务如何避免双写、漂移和兜底冲突？
  • 一句话答：单一事实源 + 每端只做适配层；协议、版本与异常兜底统一由宿主层裁决，避免多端各写一套。

先建立哪一层心智

建议先把混合架构拆成三层：

1. 调用通道层：MethodChannel / EventChannel / BasicMessageChannel / JSBridge
2. 宿主能力层：登录、支付、分享、权限、设备信息、推送、归因
3. 业务编排层：Flutter 页面、H5 页面、原生容器到底谁做判断、谁做兜底

只要先分清这三层，后面遇到 bridge 问题就不会把“通道协议”和“业务归属”混为一谈。

模块成熟度与后续重点

当前模块可视为：L2.5 → L3 过渡中。

• 已有：通道模型、JSBridge、契约版本治理、双引擎 transport、超时分层、错误协议等“桥接工程学”内容
• 已缺：页面跳转、支付回流、分享/权限、归因透传等“真实业务桥接样板”还不够齐

因此，后续不应优先扩很多抽象教程，而应优先补“宿主能力桥”的真实业务例子。

一张图先看懂：桥接不止是通道问题

例子 1：支付为什么不能只看“JSBridge 调起来了没”？

• 错误理解：H5 调起收银台成功、原生支付 SDK 也拉起了，说明桥接已经完成
• 真实问题：真正难点在后半段——用户取消、支付成功但页面超时、支付结果回流晚于 Web 侧计时、重复提交幂等失控
• 正确抽象：
  1. 通道层：能不能把请求送到宿主
  2. 宿主能力层：是否正确拉起支付 SDK
  3. 业务编排层：结果由谁裁决、超时怎么分层、失败后页面如何恢复

例子 2：页面跳转为什么不是“传个 URL 就完了”？

• 表面需求：H5 点击卡片跳 App 页面
• 实际复杂度：
  • 登录态是否齐备
  • 参数是否合法
  • 低版本客户端是否支持该目标页
  • 跳不过去时降级 H5、旧 Native 页，还是提示升级

所以“页面跳转协议”本质是一个版本化、可降级、带宿主裁决的业务协议，不是一个简单路由字符串。

推荐阅读顺序

第 1 步：先看 Flutter ↔ 原生通道模型

• MethodChannel / EventChannel / BasicMessageChannel
  • 作用：先分清“一次调用 / 持续事件 / 任意双向消息”分别该落在哪种通道上。

第 2 步：再看 WebView / H5 / JSBridge

• WebView / H5 / JSBridge 双向通信
  • 作用：理解容器与 H5 间的桥接边界，以及登录态、支付、页面跳转协议如何穿过桥。
• 进阶工程化（在「通了」之后，补生产级加固）：
  • 桥接契约版本治理 —— 把 JSBridge 当版本化 API 表面，meta 注入 + CI 强校验
  • 双 WebView 引擎运输层抽象 —— 用 shim 屏蔽底层引擎差异
  • 桥接调用超时分层与就绪竞态 —— 四层超时语义分离
  • 桥接边界与错误协议 —— 大整数精度 / 返回栈协商 / 错误信封

第 3 步：最后收口多端职责划分

• 多端一致性设计：Android / iOS / Flutter / H5
  • 作用：决定哪层做状态判断、哪层做幂等、哪层做兜底，避免双写与漂移。

第 4 步：补当前缺口 —— 宿主协同与状态收口

• Vue 状态、路由与宿主协同
  • 作用：把 H5 状态层与宿主桥接层真正接起来，避免桥接只是“通了”，但状态归属依旧混乱。

第 5 步：动态化与热更新（按需下发与 OTA）

• 动态化与热更新：AAB、ClassLoader 与 CodePush
  • 作用：理解「不整包发版也能改逻辑/资源」的边界，以及它为什么必须先有 03 的模块化与 SPI 解耦（iOS 原生 OTA 红线也在此收口）。

模块知识树

01. Flutter 与原生桥接

总览

• MethodChannel / EventChannel / BasicMessageChannel

专题展开

• Flutter PlatformView：AndroidView / UIKitView / 触摸与线程
• 原生线程与 isolate 桥接：FFI / 原生回调回 Dart
• Flutter plugin 开发基础结构（未成文，待补）
• 原生 SDK 封装给 Flutter（未成文，待补）

这组重点解决：Flutter 调原生时，通道模型怎么选，plugin 在调用链里承担什么职责。

---

02. WebView 与 JSBridge

总览

• WebView / H5 / JSBridge 双向通信

专题展开

• H5 登录态与 SSO：Cookie / JWT / 免登互通
• 支付结果回流（待补，优先级高）
• 桥接契约版本治理：把 JSBridge 当作版本化 API 表面
• 双 WebView 引擎运输层抽象
• 桥接调用超时分层与就绪竞态
• 桥接边界与错误协议
• 页面跳转协议（未成文，待补）
• H5 与原生生命周期差异（未成文，待补）
• 分享 / 权限桥（未成文，待补）
• 归因参数透传（未成文，待补）

这组重点解决：H5 和宿主之间哪些能力需要桥，桥传的到底是命令、事件还是业务事实。

---

03. 模块化与架构解耦

• 大型 App 模块化架构、SPI 机制与组件间通信

05. 动态化与热更新（与模块化相邻）

• 动态化与热更新：AAB、ClassLoader 与 CodePush

这组重点解决：能热更/按需下发的，必须是清晰解耦、可被独立加载的模块——它的边界正是 03 模块化与 SPI 要建立的。

04. 多端职责划分

总览

• 多端一致性设计：Android / iOS / Flutter / H5

专题展开

• Android / iOS / Flutter / H5 职责边界（未成文，待补）
• 哪层做状态判断（未成文，待补）
• 哪层做幂等（未成文，待补）
• 哪层做兜底（未成文，待补）

这组重点解决：通道通了以后，真实业务到底由谁说了算，如何避免多个端各自补逻辑导致不一致。

---

04. 状态收口与宿主协同（新增补位）

总览

• Vue 状态、路由与宿主协同

这组重点解决：桥接拿到的宿主事实，最终如何落到 H5 / Vue 状态层，避免桥是通的、状态却还是乱的。

对应 labs 入口

当前已落地四个可运行实验，其余仍在计划补齐：

• platform-channel-demo —— MethodChannel / EventChannel（Flutter ↔ Android）
• platform-view-demo —— AndroidView 嵌入原生视图
• dart-ffi-demo —— dart:ffi 调 C 函数 + 零拷贝
• webview-jsbridge-demo —— WebView / JSBridge 双向通信 + 白名单校验
• h5-sso-cookie-demo —— Cookie 强注入 + 401 换票
• contract-consistency-simulation —— 契约升级向后兼容仿真 + 契约漂移 CI 强校验（支撑 09）
• dual-engine-transport-simulation —— 双引擎 shim 抽象仿真（支撑 10）
• bridge-timeout-layering-simulation —— 四层超时分离仿真（支撑 11）
• bridge-boundary-error-protocol-simulation —— 大整数精度 / 返回栈协商 / 错误信封仿真（支撑 12）
• labs/android/host/topics/bridge-hybrid/modularization-spi-demo/ —— CLOSURE：补 README / 源码锚点，接通已存在的 SpiArchitectureDemoActivity
• labs/vue/bridge-hybrid/ —— H5 状态与宿主协同实验
• labs/shared/bridge-hybrid/ —— 多端一致性样例

当前最值得优先补的业务桥接样板

0. modularization-spi-demo（CLOSURE）
   • 目标：低成本补齐 05 的模块化 / SPI 实验入口，证明本模块不是空地，可与 Batch 1 并行或略前置
1. 页面跳转协议
   • 解决：版本兼容、参数校验、登录前置、失败降级
2. 分享 / 权限桥
   • 解决：宿主能力统一收口，避免 H5 / Flutter 各写一套权限判断
3. 支付结果回流
   • 解决：用户取消、超时、回流晚到、幂等控制、页面恢复
4. 归因参数透传
   • 解决：活动页 / 落地页 / App 内页之间的参数保真与去重

备注

这个模块现在已经从“桥接名词清单”收口成“通道层 → 宿主能力层 → 业务职责层”的阅读路径。后续最值得补的是支付结果回流、页面跳转协议、分享/权限桥、归因参数透传这类真实项目样例——先补业务桥，再回头抽象成 plugin / SDK 封装模式。