鴻蒙化適配實(shí)戰(zhàn)：以fast_base為例的遷移指南)
最近剛把項(xiàng)目里一直在用的 Flutter 三方庫(kù) fast_base 移植到了鴻蒙平臺(tái)整個(gè)過程比我想象中要順但也不像改普通插件那樣改個(gè) pubspec 就完事。fast_base 本身是一套幫團(tuán)隊(duì)快速搭建基礎(chǔ)架構(gòu)的腳手架庫(kù)支持響應(yīng)式 Repository 封裝、業(yè)務(wù)模型注入、狀態(tài)管理模板化這些能力。這篇文章把我鴻蒙化過程中踩過的坑、做過的取舍、驗(yàn)證過的方案都記錄下來如果你也在做 Flutter 庫(kù)的鴻蒙適配或者想了解 fast_base 這類基礎(chǔ)庫(kù)在“非標(biāo)準(zhǔn) Flutter 平臺(tái)”上怎么落地應(yīng)該能省不少時(shí)間。先說結(jié)論fast_base 這類“純 Dart 少量平臺(tái)能力”的基礎(chǔ)庫(kù)鴻蒙化難度主要集中在三層——插件通道的注冊(cè)與橋接、響應(yīng)式數(shù)據(jù)流從原生側(cè)到 Dart 側(cè)的貫通、以及業(yè)務(wù)模型注入的初始化時(shí)機(jī)。只要把這三層想清楚剩下的基本都是體力活。1. 鴻蒙化適配前的整體思路1.1 fast_base 到底解決什么問題fast_base 不是業(yè)務(wù)庫(kù)是“架構(gòu)底座”。它會(huì)把一個(gè)業(yè)務(wù)模塊需要的 BaseViewModel、BaseRepository、依賴注入容器、模型注冊(cè)中心先鋪好開發(fā)者只需要繼承對(duì)應(yīng)的基類然后把業(yè)務(wù)寫進(jìn)模板方法里。比如我團(tuán)隊(duì)做一個(gè)列表頁正常流程是先建頁面、建ViewModel、建Repository、寫網(wǎng)絡(luò)請(qǐng)求、寫模型解析、寫依賴注入這一套下來少說半天。用 fast_base 之后新模塊五分鐘內(nèi)就能把數(shù)據(jù)鏈路跑通。它內(nèi)部核心就三件事提供一個(gè) BaseViewModel 基類內(nèi)部封裝了加載狀態(tài)、錯(cuò)誤狀態(tài)、dispose 生命周期管理。提供一個(gè) BaseRepository 抽象內(nèi)置 fetch、cache、retry 的基礎(chǔ)響應(yīng)式數(shù)據(jù)管道。提供一個(gè)輕量 Injector可以按類型注冊(cè)單例或工廠函數(shù)業(yè)務(wù)層不關(guān)心對(duì)象是怎么拼出來的。這三件事看起來簡(jiǎn)單但在團(tuán)隊(duì)協(xié)作里價(jià)值很高每個(gè)新頁面都有一致的數(shù)據(jù)流新人不會(huì)把代碼寫成“一個(gè)頁面一個(gè)樣”。鴻蒙化的時(shí)候這三件事也正是風(fēng)險(xiǎn)最高的地方因?yàn)樗鼈兊倪\(yùn)行基礎(chǔ)是 Dart 的 isolate、Stream、泛型系統(tǒng)到了鴻蒙引擎上未必和 Android 上一致。1.2 為什么需要“鴻蒙化適配”而不是“重新開發(fā)”很多人會(huì)問鴻蒙已經(jīng)有原生開發(fā)體系了為什么還要把 Flutter 三方庫(kù)搬過去我的觀點(diǎn)是如果你的團(tuán)隊(duì)已經(jīng)有一套成熟的 Flutter 代碼資產(chǎn)沒必要因?yàn)閾Q平臺(tái)就全部推倒重來。fast_base 沉淀了業(yè)務(wù)開發(fā)規(guī)范如果重新用 ArkTS 寫一套后續(xù)雙端邏輯維護(hù)成本翻倍而且兩個(gè)平臺(tái)的“基礎(chǔ)架構(gòu)”很難保持一致。但“直接跑”也不現(xiàn)實(shí)。Flutter 在鴻蒙平臺(tái)上的運(yùn)行依賴特定的引擎實(shí)現(xiàn)fast_base 里只要有一處插件調(diào)用沒有鴻蒙側(cè)實(shí)現(xiàn)整個(gè)包就編不過。適配的核心思路是把 fast_base 的抽象層全部保留把底層平臺(tái)實(shí)現(xiàn)替換成鴻蒙能識(shí)別的橋接模塊。抽象層不碰業(yè)務(wù)底層換成鴻蒙原生能力之后業(yè)務(wù)代碼幾乎不用動(dòng)。實(shí)際做下來我把 fast_base 的適配拆成四個(gè)層次編譯適配讓 fast_base 在鴻蒙工程的依賴圖里能通過靜態(tài)檢查。通道適配MethodChannel / EventChannel 在鴻蒙側(cè)注冊(cè)原生實(shí)現(xiàn)。數(shù)據(jù)流適配響應(yīng)式 Repository 里的 Stream 能與鴻蒙側(cè)事件互通。注入適配業(yè)務(wù)模型注入在鴻蒙啟動(dòng)鏈路上能正確初始化。這個(gè)拆法也可以反向當(dāng)排錯(cuò)清單先看能不能編過再看通不通再看流不流最后看對(duì)象能不能注進(jìn)去。1.3 適配目標(biāo)拆解我給自己定的目標(biāo)不是“把所有能力都搬到鴻蒙”而是“讓現(xiàn)有 Flutter 業(yè)務(wù)模塊在鴻蒙上能無差別運(yùn)行”。具體拆成幾項(xiàng)編譯目標(biāo)從 Android/iOS 切到 Husky 的 ohos 平臺(tái)能產(chǎn)出 HAP 包。fast_base 依賴的三方庫(kù)至少要在鴻蒙上能加載不能加載的就找純 Dart 替代。BaseRepository 默認(rèn)的網(wǎng)絡(luò)實(shí)現(xiàn)換成鴻蒙平臺(tái)可用的網(wǎng)絡(luò)棧。響應(yīng)式 Stream 在鴻蒙原生頁面和 Flutter 頁面混編場(chǎng)景下也能收到數(shù)據(jù)。業(yè)務(wù)模型注冊(cè)表的初始化不會(huì)因?yàn)槠脚_(tái)差異導(dǎo)致找不到解析器。這些目標(biāo)看起來偏“基礎(chǔ)”但恰恰是基礎(chǔ)架構(gòu)庫(kù)的生死線?；A(chǔ)庫(kù)一旦有個(gè)隱蔽的平臺(tái)差異業(yè)務(wù)層是很晚才暴露問題的。2. 工程改造與環(huán)境準(zhǔn)備2.1 搭建鴻蒙化的 Flutter 工程骨架鴻蒙化適配不是“改一個(gè)包”就行要把整個(gè) Flutter 工程切換到鴻蒙構(gòu)建鏈路。第一步當(dāng)然是準(zhǔn)備好支持 ohos 平臺(tái)的 Flutter SDK 和環(huán)境這一步不同版本差異很大建議直接用團(tuán)隊(duì)的 CI 鏡像鎖版本不要每個(gè)人本地各裝一套。工程初始化我建議單獨(dú)建一個(gè)新工程來做適配驗(yàn)證別直接在業(yè)務(wù)主工程里改。原因是鴻蒙構(gòu)建出的工程結(jié)構(gòu)、簽名配置和 Gradle 差異很大先用最小工程把 fast_base 跑通再回主工程合并排錯(cuò)成本低很多。創(chuàng)建一個(gè)支持 ohos 的 Flutter 工程可以用flutter create --platformsohos fast_base_ohos_demo創(chuàng)建后目錄里會(huì)出現(xiàn)ohos目錄這是鴻蒙原生工程殼用 DevEco 工具打開就能編輯。相比 Android 的android目錄這里多了一個(gè)AppScope目錄里面放應(yīng)用級(jí)的配置比如 app.json5權(quán)限聲明等。如果這個(gè)命令不認(rèn)識(shí)--platformsohos說明你的 Flutter SDK 沒有啟用鴻蒙支持需要先升級(jí)到對(duì)應(yīng)分支。適配 fast_base 這種三方庫(kù)最怕 SDK 版本浮動(dòng)建議拿一個(gè)經(jīng)過驗(yàn)證的 SDK 版本固定下來后續(xù)適配都基于它。2.2 依賴替換與兼容層設(shè)計(jì)fast_base 的 pubspec 里可能引了一些三方庫(kù)首先要逐個(gè)確認(rèn)它們?cè)邙櫭缮嫌袥]有原生端實(shí)現(xiàn)。我在適配時(shí)把依賴分成三類類型示例鴻蒙處理純 Dart 庫(kù)dio、rxdart、collection一般直接可用無需改動(dòng)Flutter 插件有原生代碼shared_preferences、path_provider需要確認(rèn)是否支持 ohos不支持則替換有平臺(tái)通道但 hybird 方案自定義插件需要為插件增加 ohos 目錄實(shí)現(xiàn)最省事的辦法是把 fast_base 中用到的不兼容插件替換成純 Dart 實(shí)現(xiàn)。比如本地存儲(chǔ)如果原來用 shared_preferences鴻蒙上可以直接用 dart:io 寫入應(yīng)用沙箱或者用鴻蒙提供的 Preferences 接口走 MethodChannel 封裝。替換時(shí)注意不要改 fast_base 對(duì)外暴露的 API 形態(tài)否則業(yè)務(wù)層代碼就得跟著改。兼容層的做法是定義一個(gè) PlatformAdapter 接口內(nèi)部用 Dart 的條件導(dǎo)入來區(qū)分平臺(tái)實(shí)現(xiàn)import platform_adapter_stub.dart if (dart.library.ohos) platform_adapter_ohos.dart if (dart.library.io) platform_adapter_io.dart;這樣 fast_base 所有用到平臺(tái)能力的地方都走 PlatformAdapter鴻蒙實(shí)現(xiàn)只在 ohos 目錄里存在。條件導(dǎo)入是 Dart 編譯期特性不會(huì)把不用的代碼打進(jìn)包非常合適。2.3 構(gòu)建產(chǎn)物與簽名配置鴻蒙工程能不能跑起來簽名是第一個(gè)攔路虎。和 Android 的 jks 類似鴻蒙需要 p12 證書文件和 profile 文件。本地調(diào)試時(shí)可以用自動(dòng)簽名但 CI 或真機(jī)分發(fā)就必須有正式的簽名配置。在ohos目錄下build-profile.json5是關(guān)鍵文件。簽名相關(guān)的配置長(zhǎng)這樣{ app: { signingConfigs: [ { name: default, type: HarmonyOS, material: { certpath: /path/to/debug.p12, storePassword: 123456, keyAlias: debugKey, keyPassword: 123456, profile: /path/to/profile.p7b, signAlg: SHA256withECDSA } } ] } }注意這里面的密碼和證書路徑別提交到 Git。我建議本地開發(fā)用一個(gè) debug 配置CI 里用單獨(dú)的 release 配置。fast_base 本身不涉及簽名但缺少簽名會(huì)導(dǎo)致 HAP 裝不到真機(jī)上適配工作根本沒法驗(yàn)證。構(gòu)建命令用flutter build hap --debug構(gòu)建完成后會(huì)在build/ohos/outputs/default下生成.hap文件。為了讓日志更詳細(xì)可以加-v參數(shù)能直接看到是哪個(gè)插件缺了 ohos 實(shí)現(xiàn)后面排錯(cuò)非常有用。3. 核心模塊改造響應(yīng)式 Repository 封裝3.1 原生 Repository 在鴻蒙上的差異點(diǎn)fast_base 里的 BaseRepository 通常長(zhǎng)這樣對(duì)外暴露一個(gè) Stream 或 ValueListenable業(yè)務(wù)層監(jiān)聽它拿到數(shù)據(jù)底層封裝網(wǎng)絡(luò)請(qǐng)求、緩存、重試。在 Android/iOS 上這個(gè) Stream 完全跑在 Flutter 引擎的 isolate 里網(wǎng)絡(luò)請(qǐng)求也走 Dart 側(cè)的 HttpClient。到了鴻蒙平臺(tái)網(wǎng)絡(luò)棧和存儲(chǔ)行為不一定和 Android 一致最大差異是“線程模型”。Dart 的 isolate 是單線程模型所有網(wǎng)絡(luò)回調(diào)最后都會(huì)回到這個(gè)線程上。鴻蒙的原生側(cè)是 Actor 并發(fā)模型有自己的一套事件隊(duì)列。如果網(wǎng)絡(luò)請(qǐng)求在原生鴻蒙側(cè)發(fā)起通過橋接把結(jié)果傳回 Dart就涉及到兩個(gè)事件循環(huán)的對(duì)接。這里最容易出問題的是回調(diào)時(shí)機(jī)Dart 側(cè)已經(jīng) await 了一個(gè) Future但原生側(cè)遲遲不回調(diào)或者回調(diào)后沒有切回主線程導(dǎo)致 UI 更新異常。fast_base 本身不綁定網(wǎng)絡(luò)庫(kù)它只規(guī)定 Repository 要返回 Stream。所以鴻蒙化時(shí)我建議網(wǎng)絡(luò)層還是留在 Dart 側(cè)用純 Dart 網(wǎng)絡(luò)庫(kù)避免跨線程問題。真正需要鴻蒙原生能力的地方比如獲取設(shè)備唯一標(biāo)識(shí)、讀取系統(tǒng)設(shè)置再走通道。3.2 響應(yīng)式數(shù)據(jù)流在鴻蒙側(cè)的兩種實(shí)現(xiàn)方案如果 fast_base 只是 Flutter 內(nèi)部數(shù)據(jù)流轉(zhuǎn)那完全沒有必要驚動(dòng)鴻蒙原生側(cè)Dart 的 StreamController 就能解決。但如果業(yè)務(wù)場(chǎng)景里鴻蒙原生頁面和 Flutter 頁面需要共享一份數(shù)據(jù)變化那就得在兩邊架一座橋。方案 A純 Dart 側(cè)響應(yīng)式。BaseRepository 內(nèi)部用自己的 StreamController數(shù)據(jù)變化只發(fā)生在 Flutter 引擎內(nèi)部。這個(gè)方案最簡(jiǎn)單鴻蒙側(cè)完全不感知。適用場(chǎng)景Flutter 頁面間共享狀態(tài)。方案 B原生事件橋接。鴻蒙側(cè)通過 EventChannel 往 Flutter 推送事件。實(shí)現(xiàn)上分兩步。Dart 側(cè)做一個(gè)封裝class OhosEventBridge { static const _eventChannel EventChannel(fast_base/ohos_events); static Streamdynamic connect(String eventName) { return _eventChannel.receiveBroadcastStream({name: eventName}); } }鴻蒙原生側(cè)則要注冊(cè)對(duì)應(yīng)的 EventChannel并實(shí)現(xiàn) sendEvent。偽代碼如下// ArkTS 側(cè)偽代碼 const eventChannel this.getEventChannel(fast_base/ohos_events); eventChannel.onReceive((call) { const eventName call.arguments[name] as string; // 注冊(cè)一個(gè)內(nèi)部事件源后續(xù)把原生事件 send 給 Flutter eventChannel.send({ tag: eventName, data: data }); });我在適配 fast_base 時(shí)把 BaseRepository 默認(rèn)采用方案 A只有在混編場(chǎng)景才顯式啟用方案 B。這樣大部分業(yè)務(wù)代碼不需要感知原生側(cè)。3.3 業(yè)務(wù)模型注入的改造實(shí)操fast_base 的業(yè)務(wù)模型注入本質(zhì)上是一個(gè)“類型 - 工廠函數(shù)”的注冊(cè)表。Dart 沒有運(yùn)行時(shí)反射所以不能用注解自動(dòng)注冊(cè)必須顯式調(diào)用注冊(cè)方法。它在 Android 上跑得好好的到了鴻蒙上卻容易出問題原因在于初始化順序。鴻蒙的 Flutter 啟動(dòng)流程從 App 入口到 Flutter 頁面渲染中間的初始化順序和 Android 有差異。fast_base 如果在初始化模型注冊(cè)表之前就嘗試解析某個(gè) Model會(huì)直接拋“ModelFactory not found”的異常。我的做法是把模型注冊(cè)提前到 main 函數(shù)的最前面在所有依賴注入之前完成。void main() { WidgetsFlutterBinding.ensureInitialized(); // fast_base 模型注入 ModelRegistry.registerUserModel(UserModel.fromJson); ModelRegistry.registerOrderModel(OrderModel.fromJson); // 依賴注入容器 Injector.instance.registerSingletonUserApi(UserApi()); runApp(const FastBaseApp()); }還有一個(gè)小點(diǎn)fast_base 的模型解析器默認(rèn)期望MapString, dynamic入?yún)?。鴻蒙?cè)如果通過橋接返回的數(shù)據(jù)是 JSON 字符串需要先統(tǒng)一轉(zhuǎn)成 Map再交給 ModelRegistry。這一步我建議放在 Repository 層完成不要放到 UI 層。4. 關(guān)鍵實(shí)現(xiàn)細(xì)節(jié)與代碼示例4.1 fast_base 核心抽象層適配fast_base 的 BaseViewModel 基類在鴻蒙上要適配的點(diǎn)是生命周期。Flutter 的 Widget 生命周期和鴻蒙頁面的生命周期不完全同步尤其是頁面切后臺(tái)、銷毀這兩個(gè)動(dòng)作觸發(fā)時(shí)機(jī)可能差幾百毫秒。BaseViewModel 內(nèi)部一般會(huì)持有 StreamSubscription頁面銷毀時(shí)要取消訂閱。原來的做法是在 dispose 里統(tǒng)一處理class BaseViewModelT extends ChangeNotifier { final BaseRepositoryT _repository; final ListStreamSubscription _subscriptions []; void onInit() { _subscriptions.add(_repository.dataStream.listen(_onData)); } void _onData(T data) { state LoadState.success; notifyListeners(); } override void dispose() { for (final sub in _subscriptions) { sub.cancel(); } _repository.close(); super.dispose(); } }在鴻蒙上我改成在 onPause/onResume 時(shí)同步暫停 Stream 監(jiān)聽避免頁面在后臺(tái)還高頻更新 UI。實(shí)現(xiàn)方式是在 fast_base 里增加一個(gè)paused標(biāo)記listen 回調(diào)里先判斷void _onData(T data) { if (paused) { pendingData data; return; } _emit(data); }這個(gè)改動(dòng)對(duì) Android 無影響對(duì)鴻蒙的頁面能耗控制很有幫助。4.2 平臺(tái)通道與鴻蒙 ArkTS 橋接fast_base 中有些能力繞不開原生比如獲取設(shè)備信息、寫入剪貼板。這些都需要用 MethodChannel并且在鴻蒙側(cè)實(shí)現(xiàn)。Dart 側(cè)和 Android 側(cè)幾乎一樣const platformChannel MethodChannel(fast_base/ohos_bridge); FutureString getDeviceId() async { final result await platformChannel.invokeMethod(getDeviceId); return result as String; }鴻蒙原生側(cè)的插件結(jié)構(gòu)和 Android 的 FlutterPlugin 不一樣。需要在ohos/entry/src/main/ets/下新建一個(gè)插件類實(shí)現(xiàn) fast_base 約定的通道名和方法名。這里的代碼非常依賴具體 SDK 版本我就寫一個(gè)相對(duì)通用的偽代碼框架import { MethodChannel } from ohos/flutter_ohos; // 注意實(shí)際導(dǎo)入路徑以當(dāng)前 SDK 為準(zhǔn) export class FastBasePlugin { static register(context: any): void { const channel new MethodChannel(context, fast_base/ohos_bridge); channel.onMethod(getDeviceId, (call) { const deviceId getSystemDeviceId(); call.success(deviceId); }); } }適配過程中最容易被坑的是方法名大小寫。鴻蒙橋接層方法名必須和 Dart 側(cè)完全一致否則 invokeMethod 返回的永遠(yuǎn)是企業(yè)級(jí)錯(cuò)誤碼。建議把方法名單獨(dú)抽成一個(gè)常量類Dart 和 ArkTS 共用同一份文檔。4.3 依賴注入容器適配fast_base 的 Injector 實(shí)現(xiàn)是一個(gè)自己維護(hù)的 Map注冊(cè)和獲取都發(fā)生在一個(gè) Isolate 里所以不需要加鎖。鴻蒙化時(shí)唯一需要注意的是循環(huán)依賴。例如UserRepository 依賴 UserApiUserApi 又依賴一個(gè) TokenProvider如果 TokenProvider 恰好需要 UserRepository 提供用戶信息就會(huì)出現(xiàn)循環(huán)。原來的代碼在 Android 上可能因?yàn)槌跏蓟樞騼e幸跑通鴻蒙上啟動(dòng)鏈路一變化就容易炸。我在 fast_base 里給 Injector 加了一個(gè)“構(gòu)造中標(biāo)記”當(dāng)發(fā)現(xiàn)正在構(gòu)造同一個(gè)類型時(shí)直接拋錯(cuò)而不是死循環(huán)。class Injector { final MapType, dynamic _singletons {}; final SetType _building {}; T getT() { final type T; if (_building.contains(type)) { throw StateError(Circular dependency detected: $type); } _building.add(type); final instance _createInstance(type); _building.remove(type); return instance; } }這個(gè)改動(dòng)很小但能讓鴻蒙適配階段的問題提前暴露而不是等到運(yùn)行到某個(gè)頁面才閃退。5. 常見問題與排查技巧5.1 編譯期出現(xiàn)符號(hào)未定義鴻蒙化最常見的編譯錯(cuò)誤之一是某個(gè) Flutter 插件找不到鴻蒙實(shí)現(xiàn)報(bào)出一堆“symbol not found”的 error。比如 path_providerAndroid 上有 android 目錄iOS 有 ios 目錄但鴻蒙上沒有 ohos 目錄編 HAP 時(shí)就會(huì)炸。排查思路很直接用flutter build hap --debug -v看日志里第一個(gè)報(bào)錯(cuò)的插件名然后去它的 pub 倉(cāng)庫(kù)看有沒有 ohos 支持。如果插件倉(cāng)庫(kù)本身沒有就把 fast_base 里對(duì)該插件的調(diào)用抽到 PlatformAdapter 層替換成純 Dart 實(shí)現(xiàn)。不要試圖給一個(gè)大型插件臨時(shí)補(bǔ) ohos 目錄工作量太大。優(yōu)先替換實(shí)在替換不了再寫一個(gè)精簡(jiǎn)橋接層只實(shí)現(xiàn) fast_base 用到的幾個(gè)方法。5.2 響應(yīng)式流在鴻蒙上收不到數(shù)據(jù)我在適配過程中遇到最詭異的問題是 Repository 的 Stream 在 Android 上能正常收到數(shù)據(jù)在鴻蒙上第一次監(jiān)聽能收到第二次就不行了。后來定位到是 EventChannel 的 receiveBroadcastStream 背后是一個(gè)共享 Stream原生側(cè)發(fā)送事件時(shí)如果 Flutter 側(cè)還沒有 addListener事件就直接丟了。處理技巧是在鴻蒙原生側(cè)做一個(gè)“最近事件緩存”每次發(fā)送時(shí)保存一條最近記錄Flutter 側(cè)監(jiān)聽后先重放緩存再接收增量事件。這個(gè)邏輯在 fast_base 的 Repository 層封裝業(yè)務(wù)層無感知。class CachedEventStream { StreamControllerdynamic _controller StreamController.broadcast(); dynamic _lastEvent; void push(dynamic event) { _lastEvent event; _controller.add(event); } Streamdynamic get stream { return Stream.multi((sub) { if (_lastEvent ! null) sub.add(_lastEvent); _controller.stream.listen(sub.add, onError: sub.addError); }); } }5.3 內(nèi)存泄漏與生命周期綁定fast_base 的基類里所有監(jiān)聽器都掛在 DisposeBag 上頁面銷毀時(shí)統(tǒng)一釋放。鴻蒙上的內(nèi)存回收機(jī)制和 Android 不一樣如果 ArkTS 側(cè)注冊(cè)了 Listener 沒有反注冊(cè)頁面關(guān)掉后這些對(duì)象并不會(huì)立刻釋放內(nèi)存曲線會(huì)一直往上漲。我在鴻蒙橋接層里增加了一個(gè)unregister方法Dart 側(cè)每次注冊(cè)時(shí)都拿到一個(gè) token析構(gòu)時(shí)用 token 手動(dòng)反注冊(cè)。同時(shí)FastBaseViewModel 的 dispose 里必須保證順序先取消原生側(cè)監(jiān)聽再關(guān)閉 Dart 側(cè) StreamController最后 notify/removeListener。順序如果反了會(huì)出現(xiàn)“UI 已經(jīng)銷毀事件還在往下發(fā)”的空指針問題鴻蒙的崩潰棧有時(shí)候不會(huì)直接指向你的 Dart 代碼而是指向引擎層排查成本很高。6. 實(shí)操心得與性能驗(yàn)證6.1 性能對(duì)比與體驗(yàn)適配完成之后我用同一個(gè)業(yè)務(wù)模塊分別在 Android 模擬器和鴻蒙真機(jī)上跑了一遍主要看三個(gè)指標(biāo)冷啟動(dòng)時(shí)間、列表頁滑動(dòng)幀率、以及頁面銷毀后的內(nèi)存回落。指標(biāo)Android模擬器鴻蒙真機(jī)冷啟動(dòng)到首頁可交互約 1.8s約 2.1s列表滑動(dòng)流暢度60幀占比96%93%銷毀 50 個(gè)頁面后內(nèi)存回落正常正常鴻蒙冷啟動(dòng)多了幾百毫秒主要花在原生側(cè)插件注冊(cè)和 Flutter 引擎初始化上業(yè)務(wù)代碼的額外耗時(shí)很少。滑動(dòng)幀率略低但體感不明顯。這個(gè)結(jié)果在我的預(yù)期之內(nèi)fast_base 是純 Dart 封裝只要引擎跑得穩(wěn)性能差異不大。6.2 適配過程中最值得保留的設(shè)計(jì)如果讓我重新做一次適配我會(huì)把 fast_base 的鴻蒙化代碼從業(yè)務(wù)主工程里徹底抽出來做成獨(dú)立的fast_base_ohos_adapter包。這樣業(yè)務(wù)工程只需要依賴適配包后續(xù) fast_base 上游升級(jí)只需要重新編譯適配包不必把橋接代碼散落在各個(gè)業(yè)務(wù)模塊里。另外橋接層的錯(cuò)誤碼一定要設(shè)計(jì)成可讀的字符串不要用 0、1、2 這種魔法數(shù)字。我在鴻蒙側(cè)排錯(cuò)時(shí)好幾次都是靠錯(cuò)誤碼里的方法名快速定位到具體通道。如果只是拋個(gè)-1日志再多也看不出問題。最后一點(diǎn)所有涉及原生側(cè)代碼的文件無論 Dart 還是 ArkTS都要加注釋說明對(duì)應(yīng)的 SDK 版本。我踩過最虧的坑就是“照著最新 API 寫的橋接代碼跑到真機(jī)上報(bào)版本不匹配”后來才發(fā)現(xiàn)項(xiàng)目的鴻蒙 SDK 和 Flutter SDK 之間有個(gè)潛在兼容范圍必須鎖版本。7. 后續(xù)可以怎么擴(kuò)展fast_base 的鴻蒙化適配并不是一錘子買賣。鴻蒙版本更新很快Flutter 引擎也在持續(xù)完善適配層需要跟著升級(jí)。我的計(jì)劃是把橋接層做成自動(dòng)注冊(cè)新建一個(gè)插件掃描邏輯避免每次新增原生方法都手動(dòng)改兩個(gè)文件。如果你只是想在鴻蒙上跑通 fast_base照著上面 4 個(gè)層次排查就夠了。如果你打算長(zhǎng)期維護(hù)建議從一開始就把 ohos 目錄、平臺(tái)通道、ArkTS 插件三塊代碼拆開各自管理別混在一個(gè)大文件里。我個(gè)人在實(shí)際操作中的體會(huì)是flutter 三方庫(kù)鴻蒙化的核心不在于你會(huì)不會(huì)鴻蒙 API而在于你有沒有把“抽象層”和“平臺(tái)層”徹底分離。分離得好適配是體力活分離不好適配就是無底洞。先把 fast_base 的邊界畫清楚剩下的工作都是時(shí)間問題。 Flutter庫(kù)鴻蒙化適配實(shí)戰(zhàn)：以fast_base為例的遷移指南
最近剛把項(xiàng)目里一直在用的 Flutter 三方庫(kù) fast_base 移植到了鴻蒙平臺(tái)整個(gè)過程比我想象中要順但也不像改普通插件那樣改個(gè) pubspec 就完事。fast_base 本身是一套幫團(tuán)隊(duì)快速搭建基礎(chǔ)架構(gòu)的腳手架庫(kù)支持響應(yīng)式 Repository 封裝、業(yè)務(wù)模型注入、狀態(tài)管理模板化這些能力。這篇文章把我鴻蒙化過程中踩過的坑、做過的取舍、驗(yàn)證過的方案都記錄下來如果你也在做 Flutter 庫(kù)的鴻蒙適配或者想了解 fast_base 這類基礎(chǔ)庫(kù)在“非標(biāo)準(zhǔn) Flutter 平臺(tái)”上怎么落地應(yīng)該能省不少時(shí)間。先說結(jié)論fast_base 這類“純 Dart 少量平臺(tái)能力”的基礎(chǔ)庫(kù)鴻蒙化難度主要集中在三層——插件通道的注冊(cè)與橋接、響應(yīng)式數(shù)據(jù)流從原生側(cè)到 Dart 側(cè)的貫通、以及業(yè)務(wù)模型注入的初始化時(shí)機(jī)。只要把這三層想清楚剩下的基本都是體力活。1. 鴻蒙化適配前的整體思路1.1 fast_base 到底解決什么問題fast_base 不是業(yè)務(wù)庫(kù)是“架構(gòu)底座”。它會(huì)把一個(gè)業(yè)務(wù)模塊需要的 BaseViewModel、BaseRepository、依賴注入容器、模型注冊(cè)中心先鋪好開發(fā)者只需要繼承對(duì)應(yīng)的基類然后把業(yè)務(wù)寫進(jìn)模板方法里。比如我團(tuán)隊(duì)做一個(gè)列表頁正常流程是先建頁面、建ViewModel、建Repository、寫網(wǎng)絡(luò)請(qǐng)求、寫模型解析、寫依賴注入這一套下來少說半天。用 fast_base 之后新模塊五分鐘內(nèi)就能把數(shù)據(jù)鏈路跑通。它內(nèi)部核心就三件事提供一個(gè) BaseViewModel 基類內(nèi)部封裝了加載狀態(tài)、錯(cuò)誤狀態(tài)、dispose 生命周期管理。提供一個(gè) BaseRepository 抽象內(nèi)置 fetch、cache、retry 的基礎(chǔ)響應(yīng)式數(shù)據(jù)管道。提供一個(gè)輕量 Injector可以按類型注冊(cè)單例或工廠函數(shù)業(yè)務(wù)層不關(guān)心對(duì)象是怎么拼出來的。這三件事看起來簡(jiǎn)單但在團(tuán)隊(duì)協(xié)作里價(jià)值很高每個(gè)新頁面都有一致的數(shù)據(jù)流新人不會(huì)把代碼寫成“一個(gè)頁面一個(gè)樣”。鴻蒙化的時(shí)候這三件事也正是風(fēng)險(xiǎn)最高的地方因?yàn)樗鼈兊倪\(yùn)行基礎(chǔ)是 Dart 的 isolate、Stream、泛型系統(tǒng)到了鴻蒙引擎上未必和 Android 上一致。1.2 為什么需要“鴻蒙化適配”而不是“重新開發(fā)”很多人會(huì)問鴻蒙已經(jīng)有原生開發(fā)體系了為什么還要把 Flutter 三方庫(kù)搬過去我的觀點(diǎn)是如果你的團(tuán)隊(duì)已經(jīng)有一套成熟的 Flutter 代碼資產(chǎn)沒必要因?yàn)閾Q平臺(tái)就全部推倒重來。fast_base 沉淀了業(yè)務(wù)開發(fā)規(guī)范如果重新用 ArkTS 寫一套后續(xù)雙端邏輯維護(hù)成本翻倍而且兩個(gè)平臺(tái)的“基礎(chǔ)架構(gòu)”很難保持一致。但“直接跑”也不現(xiàn)實(shí)。Flutter 在鴻蒙平臺(tái)上的運(yùn)行依賴特定的引擎實(shí)現(xiàn)fast_base 里只要有一處插件調(diào)用沒有鴻蒙側(cè)實(shí)現(xiàn)整個(gè)包就編不過。適配的核心思路是把 fast_base 的抽象層全部保留把底層平臺(tái)實(shí)現(xiàn)替換成鴻蒙能識(shí)別的橋接模塊。抽象層不碰業(yè)務(wù)底層換成鴻蒙原生能力之后業(yè)務(wù)代碼幾乎不用動(dòng)。實(shí)際做下來我把 fast_base 的適配拆成四個(gè)層次編譯適配讓 fast_base 在鴻蒙工程的依賴圖里能通過靜態(tài)檢查。通道適配MethodChannel / EventChannel 在鴻蒙側(cè)注冊(cè)原生實(shí)現(xiàn)。數(shù)據(jù)流適配響應(yīng)式 Repository 里的 Stream 能與鴻蒙側(cè)事件互通。注入適配業(yè)務(wù)模型注入在鴻蒙啟動(dòng)鏈路上能正確初始化。這個(gè)拆法也可以反向當(dāng)排錯(cuò)清單先看能不能編過再看通不通再看流不流最后看對(duì)象能不能注進(jìn)去。1.3 適配目標(biāo)拆解我給自己定的目標(biāo)不是“把所有能力都搬到鴻蒙”而是“讓現(xiàn)有 Flutter 業(yè)務(wù)模塊在鴻蒙上能無差別運(yùn)行”。具體拆成幾項(xiàng)編譯目標(biāo)從 Android/iOS 切到 Husky 的 ohos 平臺(tái)能產(chǎn)出 HAP 包。fast_base 依賴的三方庫(kù)至少要在鴻蒙上能加載不能加載的就找純 Dart 替代。BaseRepository 默認(rèn)的網(wǎng)絡(luò)實(shí)現(xiàn)換成鴻蒙平臺(tái)可用的網(wǎng)絡(luò)棧。響應(yīng)式 Stream 在鴻蒙原生頁面和 Flutter 頁面混編場(chǎng)景下也能收到數(shù)據(jù)。業(yè)務(wù)模型注冊(cè)表的初始化不會(huì)因?yàn)槠脚_(tái)差異導(dǎo)致找不到解析器。這些目標(biāo)看起來偏“基礎(chǔ)”但恰恰是基礎(chǔ)架構(gòu)庫(kù)的生死線?；A(chǔ)庫(kù)一旦有個(gè)隱蔽的平臺(tái)差異業(yè)務(wù)層是很晚才暴露問題的。2. 工程改造與環(huán)境準(zhǔn)備2.1 搭建鴻蒙化的 Flutter 工程骨架鴻蒙化適配不是“改一個(gè)包”就行要把整個(gè) Flutter 工程切換到鴻蒙構(gòu)建鏈路。第一步當(dāng)然是準(zhǔn)備好支持 ohos 平臺(tái)的 Flutter SDK 和環(huán)境這一步不同版本差異很大建議直接用團(tuán)隊(duì)的 CI 鏡像鎖版本不要每個(gè)人本地各裝一套。工程初始化我建議單獨(dú)建一個(gè)新工程來做適配驗(yàn)證別直接在業(yè)務(wù)主工程里改。原因是鴻蒙構(gòu)建出的工程結(jié)構(gòu)、簽名配置和 Gradle 差異很大先用最小工程把 fast_base 跑通再回主工程合并排錯(cuò)成本低很多。創(chuàng)建一個(gè)支持 ohos 的 Flutter 工程可以用flutter create --platformsohos fast_base_ohos_demo創(chuàng)建后目錄里會(huì)出現(xiàn)ohos目錄這是鴻蒙原生工程殼用 DevEco 工具打開就能編輯。相比 Android 的android目錄這里多了一個(gè)AppScope目錄里面放應(yīng)用級(jí)的配置比如 app.json5權(quán)限聲明等。如果這個(gè)命令不認(rèn)識(shí)--platformsohos說明你的 Flutter SDK 沒有啟用鴻蒙支持需要先升級(jí)到對(duì)應(yīng)分支。適配 fast_base 這種三方庫(kù)最怕 SDK 版本浮動(dòng)建議拿一個(gè)經(jīng)過驗(yàn)證的 SDK 版本固定下來后續(xù)適配都基于它。2.2 依賴替換與兼容層設(shè)計(jì)fast_base 的 pubspec 里可能引了一些三方庫(kù)首先要逐個(gè)確認(rèn)它們?cè)邙櫭缮嫌袥]有原生端實(shí)現(xiàn)。我在適配時(shí)把依賴分成三類類型示例鴻蒙處理純 Dart 庫(kù)dio、rxdart、collection一般直接可用無需改動(dòng)Flutter 插件有原生代碼shared_preferences、path_provider需要確認(rèn)是否支持 ohos不支持則替換有平臺(tái)通道但 hybird 方案自定義插件需要為插件增加 ohos 目錄實(shí)現(xiàn)最省事的辦法是把 fast_base 中用到的不兼容插件替換成純 Dart 實(shí)現(xiàn)。比如本地存儲(chǔ)如果原來用 shared_preferences鴻蒙上可以直接用 dart:io 寫入應(yīng)用沙箱或者用鴻蒙提供的 Preferences 接口走 MethodChannel 封裝。替換時(shí)注意不要改 fast_base 對(duì)外暴露的 API 形態(tài)否則業(yè)務(wù)層代碼就得跟著改。兼容層的做法是定義一個(gè) PlatformAdapter 接口內(nèi)部用 Dart 的條件導(dǎo)入來區(qū)分平臺(tái)實(shí)現(xiàn)import platform_adapter_stub.dart if (dart.library.ohos) platform_adapter_ohos.dart if (dart.library.io) platform_adapter_io.dart;這樣 fast_base 所有用到平臺(tái)能力的地方都走 PlatformAdapter鴻蒙實(shí)現(xiàn)只在 ohos 目錄里存在。條件導(dǎo)入是 Dart 編譯期特性不會(huì)把不用的代碼打進(jìn)包非常合適。2.3 構(gòu)建產(chǎn)物與簽名配置鴻蒙工程能不能跑起來簽名是第一個(gè)攔路虎。和 Android 的 jks 類似鴻蒙需要 p12 證書文件和 profile 文件。本地調(diào)試時(shí)可以用自動(dòng)簽名但 CI 或真機(jī)分發(fā)就必須有正式的簽名配置。在ohos目錄下build-profile.json5是關(guān)鍵文件。簽名相關(guān)的配置長(zhǎng)這樣{ app: { signingConfigs: [ { name: default, type: HarmonyOS, material: { certpath: /path/to/debug.p12, storePassword: 123456, keyAlias: debugKey, keyPassword: 123456, profile: /path/to/profile.p7b, signAlg: SHA256withECDSA } } ] } }注意這里面的密碼和證書路徑別提交到 Git。我建議本地開發(fā)用一個(gè) debug 配置CI 里用單獨(dú)的 release 配置。fast_base 本身不涉及簽名但缺少簽名會(huì)導(dǎo)致 HAP 裝不到真機(jī)上適配工作根本沒法驗(yàn)證。構(gòu)建命令用flutter build hap --debug構(gòu)建完成后會(huì)在build/ohos/outputs/default下生成.hap文件。為了讓日志更詳細(xì)可以加-v參數(shù)能直接看到是哪個(gè)插件缺了 ohos 實(shí)現(xiàn)后面排錯(cuò)非常有用。3. 核心模塊改造響應(yīng)式 Repository 封裝3.1 原生 Repository 在鴻蒙上的差異點(diǎn)fast_base 里的 BaseRepository 通常長(zhǎng)這樣對(duì)外暴露一個(gè) Stream 或 ValueListenable業(yè)務(wù)層監(jiān)聽它拿到數(shù)據(jù)底層封裝網(wǎng)絡(luò)請(qǐng)求、緩存、重試。在 Android/iOS 上這個(gè) Stream 完全跑在 Flutter 引擎的 isolate 里網(wǎng)絡(luò)請(qǐng)求也走 Dart 側(cè)的 HttpClient。到了鴻蒙平臺(tái)網(wǎng)絡(luò)棧和存儲(chǔ)行為不一定和 Android 一致最大差異是“線程模型”。Dart 的 isolate 是單線程模型所有網(wǎng)絡(luò)回調(diào)最后都會(huì)回到這個(gè)線程上。鴻蒙的原生側(cè)是 Actor 并發(fā)模型有自己的一套事件隊(duì)列。如果網(wǎng)絡(luò)請(qǐng)求在原生鴻蒙側(cè)發(fā)起通過橋接把結(jié)果傳回 Dart就涉及到兩個(gè)事件循環(huán)的對(duì)接。這里最容易出問題的是回調(diào)時(shí)機(jī)Dart 側(cè)已經(jīng) await 了一個(gè) Future但原生側(cè)遲遲不回調(diào)或者回調(diào)后沒有切回主線程導(dǎo)致 UI 更新異常。fast_base 本身不綁定網(wǎng)絡(luò)庫(kù)它只規(guī)定 Repository 要返回 Stream。所以鴻蒙化時(shí)我建議網(wǎng)絡(luò)層還是留在 Dart 側(cè)用純 Dart 網(wǎng)絡(luò)庫(kù)避免跨線程問題。真正需要鴻蒙原生能力的地方比如獲取設(shè)備唯一標(biāo)識(shí)、讀取系統(tǒng)設(shè)置再走通道。3.2 響應(yīng)式數(shù)據(jù)流在鴻蒙側(cè)的兩種實(shí)現(xiàn)方案如果 fast_base 只是 Flutter 內(nèi)部數(shù)據(jù)流轉(zhuǎn)那完全沒有必要驚動(dòng)鴻蒙原生側(cè)Dart 的 StreamController 就能解決。但如果業(yè)務(wù)場(chǎng)景里鴻蒙原生頁面和 Flutter 頁面需要共享一份數(shù)據(jù)變化那就得在兩邊架一座橋。方案 A純 Dart 側(cè)響應(yīng)式。BaseRepository 內(nèi)部用自己的 StreamController數(shù)據(jù)變化只發(fā)生在 Flutter 引擎內(nèi)部。這個(gè)方案最簡(jiǎn)單鴻蒙側(cè)完全不感知。適用場(chǎng)景Flutter 頁面間共享狀態(tài)。方案 B原生事件橋接。鴻蒙側(cè)通過 EventChannel 往 Flutter 推送事件。實(shí)現(xiàn)上分兩步。Dart 側(cè)做一個(gè)封裝class OhosEventBridge { static const _eventChannel EventChannel(fast_base/ohos_events); static Streamdynamic connect(String eventName) { return _eventChannel.receiveBroadcastStream({name: eventName}); } }鴻蒙原生側(cè)則要注冊(cè)對(duì)應(yīng)的 EventChannel并實(shí)現(xiàn) sendEvent。偽代碼如下// ArkTS 側(cè)偽代碼 const eventChannel this.getEventChannel(fast_base/ohos_events); eventChannel.onReceive((call) { const eventName call.arguments[name] as string; // 注冊(cè)一個(gè)內(nèi)部事件源后續(xù)把原生事件 send 給 Flutter eventChannel.send({ tag: eventName, data: data }); });我在適配 fast_base 時(shí)把 BaseRepository 默認(rèn)采用方案 A只有在混編場(chǎng)景才顯式啟用方案 B。這樣大部分業(yè)務(wù)代碼不需要感知原生側(cè)。3.3 業(yè)務(wù)模型注入的改造實(shí)操fast_base 的業(yè)務(wù)模型注入本質(zhì)上是一個(gè)“類型 - 工廠函數(shù)”的注冊(cè)表。Dart 沒有運(yùn)行時(shí)反射所以不能用注解自動(dòng)注冊(cè)必須顯式調(diào)用注冊(cè)方法。它在 Android 上跑得好好的到了鴻蒙上卻容易出問題原因在于初始化順序。鴻蒙的 Flutter 啟動(dòng)流程從 App 入口到 Flutter 頁面渲染中間的初始化順序和 Android 有差異。fast_base 如果在初始化模型注冊(cè)表之前就嘗試解析某個(gè) Model會(huì)直接拋“ModelFactory not found”的異常。我的做法是把模型注冊(cè)提前到 main 函數(shù)的最前面在所有依賴注入之前完成。void main() { WidgetsFlutterBinding.ensureInitialized(); // fast_base 模型注入 ModelRegistry.registerUserModel(UserModel.fromJson); ModelRegistry.registerOrderModel(OrderModel.fromJson); // 依賴注入容器 Injector.instance.registerSingletonUserApi(UserApi()); runApp(const FastBaseApp()); }還有一個(gè)小點(diǎn)fast_base 的模型解析器默認(rèn)期望MapString, dynamic入?yún)?。鴻蒙?cè)如果通過橋接返回的數(shù)據(jù)是 JSON 字符串需要先統(tǒng)一轉(zhuǎn)成 Map再交給 ModelRegistry。這一步我建議放在 Repository 層完成不要放到 UI 層。4. 關(guān)鍵實(shí)現(xiàn)細(xì)節(jié)與代碼示例4.1 fast_base 核心抽象層適配fast_base 的 BaseViewModel 基類在鴻蒙上要適配的點(diǎn)是生命周期。Flutter 的 Widget 生命周期和鴻蒙頁面的生命周期不完全同步尤其是頁面切后臺(tái)、銷毀這兩個(gè)動(dòng)作觸發(fā)時(shí)機(jī)可能差幾百毫秒。BaseViewModel 內(nèi)部一般會(huì)持有 StreamSubscription頁面銷毀時(shí)要取消訂閱。原來的做法是在 dispose 里統(tǒng)一處理class BaseViewModelT extends ChangeNotifier { final BaseRepositoryT _repository; final ListStreamSubscription _subscriptions []; void onInit() { _subscriptions.add(_repository.dataStream.listen(_onData)); } void _onData(T data) { state LoadState.success; notifyListeners(); } override void dispose() { for (final sub in _subscriptions) { sub.cancel(); } _repository.close(); super.dispose(); } }在鴻蒙上我改成在 onPause/onResume 時(shí)同步暫停 Stream 監(jiān)聽避免頁面在后臺(tái)還高頻更新 UI。實(shí)現(xiàn)方式是在 fast_base 里增加一個(gè)paused標(biāo)記listen 回調(diào)里先判斷void _onData(T data) { if (paused) { pendingData data; return; } _emit(data); }這個(gè)改動(dòng)對(duì) Android 無影響對(duì)鴻蒙的頁面能耗控制很有幫助。4.2 平臺(tái)通道與鴻蒙 ArkTS 橋接fast_base 中有些能力繞不開原生比如獲取設(shè)備信息、寫入剪貼板。這些都需要用 MethodChannel并且在鴻蒙側(cè)實(shí)現(xiàn)。Dart 側(cè)和 Android 側(cè)幾乎一樣const platformChannel MethodChannel(fast_base/ohos_bridge); FutureString getDeviceId() async { final result await platformChannel.invokeMethod(getDeviceId); return result as String; }鴻蒙原生側(cè)的插件結(jié)構(gòu)和 Android 的 FlutterPlugin 不一樣。需要在ohos/entry/src/main/ets/下新建一個(gè)插件類實(shí)現(xiàn) fast_base 約定的通道名和方法名。這里的代碼非常依賴具體 SDK 版本我就寫一個(gè)相對(duì)通用的偽代碼框架import { MethodChannel } from ohos/flutter_ohos; // 注意實(shí)際導(dǎo)入路徑以當(dāng)前 SDK 為準(zhǔn) export class FastBasePlugin { static register(context: any): void { const channel new MethodChannel(context, fast_base/ohos_bridge); channel.onMethod(getDeviceId, (call) { const deviceId getSystemDeviceId(); call.success(deviceId); }); } }適配過程中最容易被坑的是方法名大小寫。鴻蒙橋接層方法名必須和 Dart 側(cè)完全一致否則 invokeMethod 返回的永遠(yuǎn)是企業(yè)級(jí)錯(cuò)誤碼。建議把方法名單獨(dú)抽成一個(gè)常量類Dart 和 ArkTS 共用同一份文檔。4.3 依賴注入容器適配fast_base 的 Injector 實(shí)現(xiàn)是一個(gè)自己維護(hù)的 Map注冊(cè)和獲取都發(fā)生在一個(gè) Isolate 里所以不需要加鎖。鴻蒙化時(shí)唯一需要注意的是循環(huán)依賴。例如UserRepository 依賴 UserApiUserApi 又依賴一個(gè) TokenProvider如果 TokenProvider 恰好需要 UserRepository 提供用戶信息就會(huì)出現(xiàn)循環(huán)。原來的代碼在 Android 上可能因?yàn)槌跏蓟樞騼e幸跑通鴻蒙上啟動(dòng)鏈路一變化就容易炸。我在 fast_base 里給 Injector 加了一個(gè)“構(gòu)造中標(biāo)記”當(dāng)發(fā)現(xiàn)正在構(gòu)造同一個(gè)類型時(shí)直接拋錯(cuò)而不是死循環(huán)。class Injector { final MapType, dynamic _singletons {}; final SetType _building {}; T getT() { final type T; if (_building.contains(type)) { throw StateError(Circular dependency detected: $type); } _building.add(type); final instance _createInstance(type); _building.remove(type); return instance; } }這個(gè)改動(dòng)很小但能讓鴻蒙適配階段的問題提前暴露而不是等到運(yùn)行到某個(gè)頁面才閃退。5. 常見問題與排查技巧5.1 編譯期出現(xiàn)符號(hào)未定義鴻蒙化最常見的編譯錯(cuò)誤之一是某個(gè) Flutter 插件找不到鴻蒙實(shí)現(xiàn)報(bào)出一堆“symbol not found”的 error。比如 path_providerAndroid 上有 android 目錄iOS 有 ios 目錄但鴻蒙上沒有 ohos 目錄編 HAP 時(shí)就會(huì)炸。排查思路很直接用flutter build hap --debug -v看日志里第一個(gè)報(bào)錯(cuò)的插件名然后去它的 pub 倉(cāng)庫(kù)看有沒有 ohos 支持。如果插件倉(cāng)庫(kù)本身沒有就把 fast_base 里對(duì)該插件的調(diào)用抽到 PlatformAdapter 層替換成純 Dart 實(shí)現(xiàn)。不要試圖給一個(gè)大型插件臨時(shí)補(bǔ) ohos 目錄工作量太大。優(yōu)先替換實(shí)在替換不了再寫一個(gè)精簡(jiǎn)橋接層只實(shí)現(xiàn) fast_base 用到的幾個(gè)方法。5.2 響應(yīng)式流在鴻蒙上收不到數(shù)據(jù)我在適配過程中遇到最詭異的問題是 Repository 的 Stream 在 Android 上能正常收到數(shù)據(jù)在鴻蒙上第一次監(jiān)聽能收到第二次就不行了。后來定位到是 EventChannel 的 receiveBroadcastStream 背后是一個(gè)共享 Stream原生側(cè)發(fā)送事件時(shí)如果 Flutter 側(cè)還沒有 addListener事件就直接丟了。處理技巧是在鴻蒙原生側(cè)做一個(gè)“最近事件緩存”每次發(fā)送時(shí)保存一條最近記錄Flutter 側(cè)監(jiān)聽后先重放緩存再接收增量事件。這個(gè)邏輯在 fast_base 的 Repository 層封裝業(yè)務(wù)層無感知。class CachedEventStream { StreamControllerdynamic _controller StreamController.broadcast(); dynamic _lastEvent; void push(dynamic event) { _lastEvent event; _controller.add(event); } Streamdynamic get stream { return Stream.multi((sub) { if (_lastEvent ! null) sub.add(_lastEvent); _controller.stream.listen(sub.add, onError: sub.addError); }); } }5.3 內(nèi)存泄漏與生命周期綁定fast_base 的基類里所有監(jiān)聽器都掛在 DisposeBag 上頁面銷毀時(shí)統(tǒng)一釋放。鴻蒙上的內(nèi)存回收機(jī)制和 Android 不一樣如果 ArkTS 側(cè)注冊(cè)了 Listener 沒有反注冊(cè)頁面關(guān)掉后這些對(duì)象并不會(huì)立刻釋放內(nèi)存曲線會(huì)一直往上漲。我在鴻蒙橋接層里增加了一個(gè)unregister方法Dart 側(cè)每次注冊(cè)時(shí)都拿到一個(gè) token析構(gòu)時(shí)用 token 手動(dòng)反注冊(cè)。同時(shí)FastBaseViewModel 的 dispose 里必須保證順序先取消原生側(cè)監(jiān)聽再關(guān)閉 Dart 側(cè) StreamController最后 notify/removeListener。順序如果反了會(huì)出現(xiàn)“UI 已經(jīng)銷毀事件還在往下發(fā)”的空指針問題鴻蒙的崩潰棧有時(shí)候不會(huì)直接指向你的 Dart 代碼而是指向引擎層排查成本很高。6. 實(shí)操心得與性能驗(yàn)證6.1 性能對(duì)比與體驗(yàn)適配完成之后我用同一個(gè)業(yè)務(wù)模塊分別在 Android 模擬器和鴻蒙真機(jī)上跑了一遍主要看三個(gè)指標(biāo)冷啟動(dòng)時(shí)間、列表頁滑動(dòng)幀率、以及頁面銷毀后的內(nèi)存回落。指標(biāo)Android模擬器鴻蒙真機(jī)冷啟動(dòng)到首頁可交互約 1.8s約 2.1s列表滑動(dòng)流暢度60幀占比96%93%銷毀 50 個(gè)頁面后內(nèi)存回落正常正常鴻蒙冷啟動(dòng)多了幾百毫秒主要花在原生側(cè)插件注冊(cè)和 Flutter 引擎初始化上業(yè)務(wù)代碼的額外耗時(shí)很少。滑動(dòng)幀率略低但體感不明顯。這個(gè)結(jié)果在我的預(yù)期之內(nèi)fast_base 是純 Dart 封裝只要引擎跑得穩(wěn)性能差異不大。6.2 適配過程中最值得保留的設(shè)計(jì)如果讓我重新做一次適配我會(huì)把 fast_base 的鴻蒙化代碼從業(yè)務(wù)主工程里徹底抽出來做成獨(dú)立的fast_base_ohos_adapter包。這樣業(yè)務(wù)工程只需要依賴適配包后續(xù) fast_base 上游升級(jí)只需要重新編譯適配包不必把橋接代碼散落在各個(gè)業(yè)務(wù)模塊里。另外橋接層的錯(cuò)誤碼一定要設(shè)計(jì)成可讀的字符串不要用 0、1、2 這種魔法數(shù)字。我在鴻蒙側(cè)排錯(cuò)時(shí)好幾次都是靠錯(cuò)誤碼里的方法名快速定位到具體通道。如果只是拋個(gè)-1日志再多也看不出問題。最后一點(diǎn)所有涉及原生側(cè)代碼的文件無論 Dart 還是 ArkTS都要加注釋說明對(duì)應(yīng)的 SDK 版本。我踩過最虧的坑就是“照著最新 API 寫的橋接代碼跑到真機(jī)上報(bào)版本不匹配”后來才發(fā)現(xiàn)項(xiàng)目的鴻蒙 SDK 和 Flutter SDK 之間有個(gè)潛在兼容范圍必須鎖版本。7. 后續(xù)可以怎么擴(kuò)展fast_base 的鴻蒙化適配并不是一錘子買賣。鴻蒙版本更新很快Flutter 引擎也在持續(xù)完善適配層需要跟著升級(jí)。我的計(jì)劃是把橋接層做成自動(dòng)注冊(cè)新建一個(gè)插件掃描邏輯避免每次新增原生方法都手動(dòng)改兩個(gè)文件。如果你只是想在鴻蒙上跑通 fast_base照著上面 4 個(gè)層次排查就夠了。如果你打算長(zhǎng)期維護(hù)建議從一開始就把 ohos 目錄、平臺(tái)通道、ArkTS 插件三塊代碼拆開各自管理別混在一個(gè)大文件里。我個(gè)人在實(shí)際操作中的體會(huì)是flutter 三方庫(kù)鴻蒙化的核心不在于你會(huì)不會(huì)鴻蒙 API而在于你有沒有把“抽象層”和“平臺(tái)層”徹底分離。分離得好適配是體力活分離不好適配就是無底洞。先把 fast_base 的邊界畫清楚剩下的工作都是時(shí)間問題。