戰(zhàn)：servicestack強(qiáng)類型JSON與消息管道改造)
做 Flutter 時(shí)間稍微長(zhǎng)一點(diǎn)的人遲早會(huì)碰到鴻蒙適配。我這次接到的任務(wù)不算復(fù)雜一個(gè)已經(jīng)在 Android 和 iOS 跑得很穩(wěn)的 Flutter 工程要往鴻蒙設(shè)備上搬。業(yè)務(wù)層所有服務(wù)調(diào)用走的都是 servicestack它負(fù)責(zé)把 Dart 里的強(qiáng)類型請(qǐng)求對(duì)象變成 JSON再通過(guò) HTTP 發(fā)給服務(wù)端響應(yīng)也自動(dòng)反序列化回 DTO。問(wèn)題在于這個(gè)庫(kù)在設(shè)計(jì)時(shí)并沒有把鴻蒙 Flutter 運(yùn)行時(shí)納入考量導(dǎo)致真正適配時(shí)有幾個(gè)坎需要繞。這篇文章想把適配路徑寫清楚重點(diǎn)放在 Message-based 架構(gòu)集成、強(qiáng)類型 JSON 序列化這塊還有跨端服務(wù)調(diào)用同步的一點(diǎn)經(jīng)驗(yàn)。適合正在做 Flutter 鴻蒙化的同行參考也適合剛接手這類改造、心里沒底的同學(xué)。1. 適配前的背景與整體拆解1.1 先搞清楚 servicestack 到底做了什么servicestack 不是一個(gè)普通的 HTTP 請(qǐng)求庫(kù)它是一整套 Message-based 服務(wù)調(diào)用框架。使用方先定義強(qiáng)類型 DTO比如GetUserRequest、GetUserResponse然后通過(guò)客戶端把請(qǐng)求對(duì)象發(fā)出去框架負(fù)責(zé)把對(duì)象序列化成 JSON 報(bào)文發(fā)給服務(wù)端再把返回的 JSON 包裝成對(duì)應(yīng)的響應(yīng) DTO。整個(gè)鏈路對(duì)業(yè)務(wù)層來(lái)說(shuō)像是“調(diào)用本地方法”一樣。這套設(shè)計(jì)在企業(yè)級(jí)項(xiàng)目里很有優(yōu)勢(shì)因?yàn)榉?wù)端和客戶端的接口契約是明確的DTO 字段變化會(huì)直接影響編譯結(jié)果比維護(hù)一堆散落的MapString, dynamic要安全得多。再加上 servicestack 自帶服務(wù)端元數(shù)據(jù)支持可以生成 Dart 客戶端代碼兩端 DTO 的同步成本會(huì)低很多。但代價(jià)也很明顯它不是一個(gè)“零配置”的庫(kù)實(shí)際請(qǐng)求時(shí)需要處理 URL 拼接、Headers 注入、查詢參數(shù)、JSON 編解碼、超時(shí)、異常映射等一組邏輯這些邏輯背后依賴的是 Flutter 常規(guī)環(huán)境下的 HTTP 能力。如果這個(gè)庫(kù)只跑在 Android 和 iOS 上基本上不需要關(guān)心底層網(wǎng)絡(luò)實(shí)現(xiàn)。要移植到鴻蒙 Flutter 運(yùn)行時(shí)就得先確認(rèn)兩件事第一庫(kù)用到的純 Dart 能力在鴻蒙環(huán)境里是否完整第二它默認(rèn)走的網(wǎng)絡(luò)棧、平臺(tái)通道、簽名校驗(yàn)這些能力鴻蒙平臺(tái)是否完全兼容。我這次踩的坑其實(shí)都集中在這兩個(gè)問(wèn)題上。1.2 鴻蒙 Flutter 運(yùn)行時(shí)和常規(guī) Flutter 的三點(diǎn)差異不是說(shuō)同樣的 Dart 代碼復(fù)制過(guò)去就能跑。鴻蒙版 Flutter 在工程結(jié)構(gòu)、插件機(jī)制、平臺(tái)通道幾個(gè)維度上和 Android/iOS 是有實(shí)質(zhì)性差異的。工程結(jié)構(gòu)上鴻蒙側(cè)會(huì)多出一個(gè)ohos平臺(tái)目錄原生代碼是用 ArkTS 這類語(yǔ)言組織而不是原來(lái)的 Java/Kotlin/ObjC。Flutter 插件如果只實(shí)現(xiàn)了 Android/iOS 原生端在鴻蒙設(shè)備上就無(wú)法工作必須額外實(shí)現(xiàn)鴻蒙平臺(tái)的插件代碼。純 Dart 寫的包通常不受影響但前提是它沒有隱式依賴原生能力。平臺(tái)通道上Flutter 的 MethodChannel 機(jī)制在鴻蒙上同樣存在但通道的“另一端”需要鴻蒙側(cè)原生代碼實(shí)現(xiàn)。如果三方庫(kù)內(nèi)部依賴某個(gè)插件提供的通道而該插件沒有鴻蒙實(shí)現(xiàn)就只能在適配時(shí)自己補(bǔ)齊。最容易被忽略的是網(wǎng)絡(luò)能力。雖然 Dart 的dart:io在鴻蒙 Flutter 上基本可用但證書校驗(yàn)、代理設(shè)置、DNS 解析這類操作系統(tǒng)底層的網(wǎng)絡(luò)策略和 Android/iOS 并不完全一致。尤其在企業(yè)內(nèi)網(wǎng)環(huán)境中常常需要走自建證書或特殊代理直接用默認(rèn) HTTP 棧容易出現(xiàn)“代碼沒報(bào)錯(cuò)請(qǐng)求卻超時(shí)”的詭異現(xiàn)象。servicestack 屬于偏純 Dart 實(shí)現(xiàn)的三方庫(kù)所以第一關(guān)其實(shí)是網(wǎng)絡(luò)層然后才是 JSON 序列化和平臺(tái)通道。如果一開始就把它當(dāng)成一個(gè)“純 Dart 包直接引入”后面會(huì)被各種運(yùn)行期問(wèn)題抓瞎。1.3 為什么我選擇“替換底層、保留業(yè)務(wù)層”的方案當(dāng)時(shí)擺在我面前的有三條路。第一條路是直接升級(jí)到 servicestack 官方最新版本看它是否已經(jīng)支持鴻蒙。這個(gè)方法最省事但我查了一下當(dāng)時(shí)的版本并沒有針對(duì)鴻蒙做專門適配而且新版本升級(jí)可能會(huì)帶來(lái) DTO 生成邏輯的變化風(fēng)險(xiǎn)不可控。第二條路是在業(yè)務(wù)層包一層全新客戶端重新封裝一套 RestClient。這個(gè)方案的隔離效果很好但業(yè)務(wù)代碼改動(dòng)量太大幾十個(gè)請(qǐng)求 DTO 都要處理而且相當(dāng)于把 servicestack 的價(jià)值全部丟掉維護(hù)成本不降反升。第三條路也是我實(shí)際采用的思路復(fù)制一份 servicestack 源碼到工程里作為本地包維護(hù)然后把它的網(wǎng)絡(luò)傳輸層替換成鴻蒙可用的實(shí)現(xiàn)。業(yè)務(wù)層照常調(diào)用JsonServiceClient照常使用強(qiáng)類型 DTO框架內(nèi)部負(fù)責(zé)把請(qǐng)求投遞到鴻蒙原生的網(wǎng)絡(luò)能力上。選用第三條路的核心原因是兼容性風(fēng)險(xiǎn)最小。本地包和業(yè)務(wù)層之間保持原有接口業(yè)務(wù)層不需要感知鴻蒙適配的存在。替換點(diǎn)集中在請(qǐng)求發(fā)送、響應(yīng)接收、錯(cuò)誤處理這幾個(gè)關(guān)鍵函數(shù)中出現(xiàn)問(wèn)題時(shí)只需要對(duì)著一個(gè)適配層排查不需要全局翻代碼。提示不是所有三方庫(kù)都適合“復(fù)制源碼”這個(gè)方案。servicestack 的源碼體量適中、依賴邊界清晰網(wǎng)絡(luò)層相對(duì)獨(dú)立所以 fork 成本可控。如果你的庫(kù)是幾千個(gè)文件、依賴鏈極深最好先評(píng)估一下維護(hù)負(fù)擔(dān)。2. 環(huán)境準(zhǔn)備與工程改造實(shí)操2.1 先搭一個(gè)鴻蒙 Flutter 工程把現(xiàn)有 lib 遷進(jìn)去所謂鴻蒙化適配前提是有一個(gè)能跑通的鴻蒙 Flutter 工程。如果你已經(jīng)有鴻蒙版本的 Flutter SDK可以在項(xiàng)目目錄下創(chuàng)建ohos平臺(tái)代碼。大致流程是先用鴻蒙版 Flutter 工具創(chuàng)建一個(gè)支持ohos平臺(tái)的新工程再把原來(lái)項(xiàng)目里的lib/目錄、資源文件、pubspec 依賴整體遷移過(guò)來(lái)。新工程會(huì)生成一個(gè)ohos目錄里面是鴻蒙原生工程的入口文件包括entry/src/main/module.json5、entry/src/main/ets等。業(yè)務(wù) Dart 代碼基本不需要改重點(diǎn)是把pubspec.yaml里的依賴關(guān)系理清楚。遷移完成后我建議第一件事就是跑一次鴻蒙模擬器上的“Hello App”確認(rèn) Flutter 引擎和鴻蒙平臺(tái)的基礎(chǔ)通道是通的再做后續(xù)適配。這一步聽起來(lái)簡(jiǎn)單但容易被忽略的是包名和 Bundle 名。鴻蒙工程對(duì)包名規(guī)范有自己的要求如果你的 Flutter 項(xiàng)目用了 Android 的 applicationId 或 iOS 的 bundleId遷移到鴻蒙時(shí)需要映射好。否則后面在做平臺(tái)通道或拉起系統(tǒng)能力時(shí)會(huì)報(bào)“能力未配置”一類的錯(cuò)誤。2.2 用 dependency_overrides 把本地包替換進(jìn)去為了讓業(yè)務(wù)層無(wú)感我建議不要把修改后的 servicestack 代碼直接提交到全局 SDK 目錄里而是放到自己的工程內(nèi)做一個(gè)本地包。在pubspec.yaml中通過(guò)dependency_overrides指定本地路徑dependencies: flutter: sdk: flutter servicestack: ^4.1.0 http: ^1.1.0 json_annotation: ^4.8.0 dev_dependencies: build_runner: ^2.4.0 json_serializable: ^6.7.0 dependency_overrides: servicestack: path: packages/servicestack_harmony這樣服務(wù)端和本地包在邏輯上是兩份代碼但最終 Flutter 工程解析依賴時(shí)會(huì)強(qiáng)制使用本地包。這個(gè)方式的靈活之處在于如果你需要對(duì)比官方版本和鴻蒙改動(dòng)版本的行為直接改dependency_overrides的路徑即可業(yè)務(wù)代碼零改動(dòng)。本地包目錄里除了源碼還需要把pubspec.yaml一并復(fù)制保證它的依賴解析和主工程一致。我第一次做的時(shí)候就漏了這一步結(jié)果本地包的依賴只能用相對(duì)路徑硬編碼非常痛苦。2.3 配置鴻蒙網(wǎng)絡(luò)權(quán)限和明文流量如果服務(wù)端是 HTTPS且證書正常那么只需在鴻蒙工程里聲明 INTERNET 權(quán)限。找到ohos/entry/src/main/module.json5在requestPermissions里加入{ name: ohos.permission.INTERNET, }如果內(nèi)網(wǎng)環(huán)境調(diào)試時(shí)用到 HTTP 明文請(qǐng)求鴻蒙默認(rèn)會(huì)攔截必須在網(wǎng)絡(luò)安全配置里允許明文流量。不同版本的鴻蒙工程目錄結(jié)構(gòu)略有差異通常是在resources/base/profile/network_config.json中配置{ network-security-config: { base-config: { cleartext-traffic-permitted: true }, domain-config: [] } }注意千萬(wàn)不要把cleartext-traffic-permitted直接設(shè)置成全局 true 然后發(fā)布到生產(chǎn)環(huán)境。正確做法是給指定的內(nèi)網(wǎng)測(cè)試域名配置單獨(dú)的白名單比如domain-config里寫cleartext-traffic-permitted為 true其他域名仍然強(qiáng)制 HTTPS。這不僅是安全要求也避免被應(yīng)用市場(chǎng)或合規(guī)審查卡住。另外一個(gè)容易踩的坑是自簽名證書。如果服務(wù)端使用的是自建 CA鴻蒙原生網(wǎng)絡(luò)棧默認(rèn)可能不信任。常見做法是把 CA 證書放到鴻蒙工程的安全配置中或者在適配層臨時(shí)關(guān)閉證書校驗(yàn)。后者只適合聯(lián)調(diào)不適合生產(chǎn)。我的建議是盡量走正規(guī)的證書信任配置否則后面運(yùn)維會(huì)被證書問(wèn)題反復(fù)折騰。3. 核心模塊適配強(qiáng)類型 JSON 與 Message-based 管道3.1 強(qiáng)類型 JSON 序列化的鴻蒙兼容改造servicestack 的強(qiáng)類型能力本質(zhì)上依賴于“DTO 到 JSON 字段”的雙向映射。在 Dart 里通常每個(gè)請(qǐng)求 DTO 都需要有toJson()方法每個(gè)響應(yīng) DTO 需要有fromJson()方法。在鴻蒙適配時(shí)這部分代碼可以繼續(xù)使用 json_serializable 生成也可以手寫。我建議大數(shù)據(jù)量大團(tuán)隊(duì)用 json_serializable因?yàn)樗鼫p少手寫出錯(cuò)的概率。比如import package:json_annotation/json_annotation.dart; part create_order_request.g.dart; JsonSerializable() class CreateOrderRequest { final String orderNo; final double amount; JsonKey(name: createdAt) final DateTime createdAt; CreateOrderRequest({ required this.orderNo, required this.amount, required this.createdAt, }); factory CreateOrderRequest.fromJson(MapString, dynamic json) _$CreateOrderRequestFromJson(json); MapString, dynamic toJson() _$CreateOrderRequestToJson(this); }使用 json_serializable 后序列化邏輯是編譯期生成的不依賴運(yùn)行時(shí)反射這在鴻蒙 Flutter 上運(yùn)行沒有兼容問(wèn)題。需要小心的反而是服務(wù)端字段風(fēng)格。比如服務(wù)端返回user_name而 DTO 里定義的是userName就必須用JsonKey(name: user_name)做映射。我遇到過(guò)團(tuán)隊(duì)里兩個(gè)平臺(tái)字段命名風(fēng)格不一致導(dǎo)致 Windows 端正常、鴻蒙端拿不到值的情況。建議把命名策略統(tǒng)一放進(jìn) CI 校驗(yàn)?zāi)_本里每次生成 DTO 后自動(dòng)比對(duì)服務(wù)端契約。從實(shí)踐角度看JSON 適配還涉及兩個(gè)細(xì)節(jié)。第一個(gè)是編碼問(wèn)題。鴻蒙原生網(wǎng)絡(luò)層拿到的字符串如果按默認(rèn)編碼處理中文字符容易亂碼。HTTP 響應(yīng)體必須明確使用 UTF-8 解碼并且在構(gòu)造請(qǐng)求體時(shí)也把 body 轉(zhuǎn)成 UTF-8 字節(jié)流。很多運(yùn)行期“能連上但是數(shù)據(jù)是亂碼”的問(wèn)題都是這里沒有處理干凈。第二個(gè)是數(shù)字類型。Dart 的int和double在 JSON 里沒有嚴(yán)格區(qū)分服務(wù)端返回100.0時(shí)Dart 端可能解析成int或double這取決于解析器的行為。如果 DTO 字段聲明為double但 JSON 里寫成100某些嚴(yán)格反序列化器會(huì)直接拋類型錯(cuò)誤。處理辦法是給反序列化邏輯加一個(gè)可配置的num到目標(biāo)類型的轉(zhuǎn)換或者統(tǒng)一要求服務(wù)端輸出規(guī)范。3.2 Message-based 請(qǐng)求管道的替換如果只是改 DTO 的序列化業(yè)務(wù)層也許還能正常跑。但真正的問(wèn)題在發(fā)送環(huán)節(jié)。servicestack 的請(qǐng)求流程是把 DTO 對(duì)象交給一個(gè)“消息管道”這個(gè)管道負(fù)責(zé)合并 query 參數(shù)、填充 headers、發(fā)送 HTTP 請(qǐng)求、接收響應(yīng)并反序列化。在鴻蒙適配中我把它替換成了一個(gè)HarmonyHttpClient。思路不復(fù)雜業(yè)務(wù)層不直接看到網(wǎng)絡(luò)實(shí)現(xiàn)它只負(fù)責(zé)傳CreateOrderRequest進(jìn)來(lái)框架內(nèi)部將請(qǐng)求變成 JSON然后調(diào)用鴻蒙原生網(wǎng)絡(luò)能力。偽代碼大概是這樣的class HarmonyHttpClient { static const MethodChannel _channel MethodChannel(com.example.harmony_http); FutureResponseData postJson({ required String url, required MapString, String headers, required String body, }) async { try { final result await _channel.invokeMethod(request, { method: POST, url: url, headers: headers, body: body, }); return ResponseData.fromNative(result); } on PlatformException catch (e) { throw ServiceStackException(e.message ?? harmony http error); } } }鴻蒙側(cè)則用原生網(wǎng)絡(luò)能力接收請(qǐng)求參數(shù)執(zhí)行真正的 HTTP 調(diào)用再把狀態(tài)碼、響應(yīng)頭、響應(yīng)體原樣返回。這樣做的目的是讓 Flutter 層只做“報(bào)文處理”不碰底層的網(wǎng)絡(luò)策略保證和企業(yè)內(nèi)網(wǎng)網(wǎng)關(guān)、代理、證書配置保持一致。你不需要照抄這段代碼因?yàn)椴煌姹镜?servicestack 內(nèi)部類名可能不同。關(guān)鍵是要找到負(fù)責(zé)“發(fā)請(qǐng)求”的那個(gè)方法把它替換成走鴻蒙原生網(wǎng)絡(luò)的實(shí)現(xiàn)。替換完成后服務(wù)端收到的請(qǐng)求頭、請(qǐng)求體不能發(fā)生變化否則會(huì)破壞既有契約。我在實(shí)現(xiàn)時(shí)額外加了一個(gè)開關(guān)線上走原生網(wǎng)絡(luò)通道本地單測(cè)走 mocked 通道。這個(gè)開關(guān)對(duì)調(diào)試非常有幫助因?yàn)?Dart 側(cè)可以模擬各類異常響應(yīng)不需要每次都啟動(dòng)鴻蒙設(shè)備。3.3 跨端服務(wù)調(diào)用同步與并發(fā)控制所謂“跨端服務(wù)調(diào)用同步”我理解包含兩層意思。一層是語(yǔ)義同步在 Android、iOS、鴻蒙三端調(diào)用同一個(gè)服務(wù)接口行為應(yīng)該一致。另一層是并發(fā)同步多個(gè)請(qǐng)求同時(shí)進(jìn)來(lái)時(shí)token 刷新、排隊(duì)順序不能亂。第一層相對(duì)容易。只要保證管道實(shí)現(xiàn)遵循同一個(gè)請(qǐng)求體構(gòu)造規(guī)則三端發(fā)出去的報(bào)文一致服務(wù)端返回的結(jié)果就不應(yīng)該有差異。真正麻煩的是第二層典型場(chǎng)景是 token 過(guò)期。很多團(tuán)隊(duì)的做法是在客戶端攔截器里處理 401收到 401 后先去后臺(tái)刷新 token刷新成功再重放原請(qǐng)求。這個(gè)過(guò)程在純 Dart 里寫沒問(wèn)題但放到鴻蒙適配后如果請(qǐng)求走的是原生通道刷新 token 的請(qǐng)求本身可能也走了同一個(gè)通道就會(huì)形成“所有請(qǐng)求都在等待一個(gè)刷新請(qǐng)求完成”的死鎖。我當(dāng)時(shí)的處理方式是加一個(gè)全局的刷新鎖FutureT _synchronizedRefreshT(FutureT Function() action) { if (_refreshFuture ! null) { return _refreshFuture!.then((_) action()); } final future action(); _refreshFuture future; return future.whenComplete(() _refreshFuture null); }第一次請(qǐng)求遇到 401 時(shí)會(huì)創(chuàng)建刷新任務(wù)其他并發(fā)請(qǐng)求則直接等待同一個(gè)_refreshFuture完成后重放。這樣能保證同時(shí)只有一個(gè)刷新請(qǐng)求在跑避免 token 互相覆蓋。還有一個(gè)容易忽略的點(diǎn)是請(qǐng)求超時(shí)。鴻蒙原生網(wǎng)絡(luò)棧默認(rèn)的超時(shí)策略和dart:io不一定相同。如果服務(wù)端接口本身就要跑幾分鐘直接在客戶端設(shè)置一個(gè)固定超時(shí)時(shí)間可能誤殺長(zhǎng)任務(wù)。我的建議是把超時(shí)參數(shù)做成可配置項(xiàng)并且區(qū)分“連接超時(shí)”和“讀取超時(shí)”不要一刀切。3.4 鑒權(quán)、錯(cuò)誤碼與重試策略企業(yè)級(jí)服務(wù)調(diào)用不可能只有 happy path。我的適配層里有一個(gè)專門處理錯(cuò)誤碼的組件會(huì)統(tǒng)一捕獲三類錯(cuò)誤第一類是網(wǎng)絡(luò)層錯(cuò)誤比如 DNS 解析失敗、連接被拒絕、讀取超時(shí)。這類錯(cuò)誤一般可以重試但要有次數(shù)上限和退避策略。第二類是 HTTP 狀態(tài)碼錯(cuò)誤比如 401、403、500。401 走 token 刷新邏輯403 直接拒絕重試500 可以留到下一次人為觸發(fā)重試。第三類是業(yè)務(wù)錯(cuò)誤即使 HTTP 返回 200服務(wù)端也可能在響應(yīng)體里放一個(gè)統(tǒng)一錯(cuò)誤碼。這類錯(cuò)誤必須透?jìng)鹘o業(yè)務(wù)層不能盲目重試。我在本地包里加了一個(gè)請(qǐng)求日志開關(guān)類似這樣class ServiceStackOptions { final bool enableLog; final bool enableRetry; final Duration connectTimeout; final Duration receiveTimeout; }開關(guān)只在開發(fā)階段打開會(huì)輸出請(qǐng)求 URL、請(qǐng)求體摘要、響應(yīng)狀態(tài)碼和耗時(shí)。排查鴻蒙適配問(wèn)題時(shí)這份日志非常關(guān)鍵。因?yàn)樵W(wǎng)絡(luò)層很多異常不會(huì)自動(dòng)拋到 Dart 層沒有日志的話就只能靠鴻蒙側(cè)控制臺(tái)一點(diǎn)一點(diǎn)摳。4. 實(shí)戰(zhàn)驗(yàn)證與問(wèn)題排查4.1 編譯期問(wèn)題依賴缺失與類型沖突鴻蒙化適配最常見的編譯錯(cuò)誤并不是 servicestack 本身的問(wèn)題而是它的傳遞依賴在鴻蒙工程里沒有被正確解析。比如某個(gè)包依賴package:http但鴻蒙工程里只聲明了 servicestack沒有顯式聲明 http。這種錯(cuò)誤在 Android/iOS 上可能不會(huì)出現(xiàn)因?yàn)?Gradle/Xcode 會(huì)自動(dòng)處理部分依賴但鴻蒙 Flutter 工程的依賴解析更嚴(yán)格。解決辦法很簡(jiǎn)單在pubspec.yaml里把所有用到的頂層依賴顯式聲明一遍。不要信任“自動(dòng)解析”更不要偷懶縮寫依賴版本否則后續(xù)環(huán)境一換就崩。類型沖突主要集中在dynamic和強(qiáng)類型之間。servicestack 里有些公開 API 返回值是dynamic業(yè)務(wù)層在使用時(shí)通常會(huì)做一次強(qiáng)轉(zhuǎn)。鴻蒙環(huán)境的編譯期類型檢查比 Android 更嚴(yán)格時(shí)強(qiáng)轉(zhuǎn)失敗會(huì)拋TypeError。解決辦法是在適配層包一層類型安全轉(zhuǎn)換函數(shù)不要直接把dynamic拋給業(yè)務(wù)層。4.2 運(yùn)行期連不上服務(wù)端從權(quán)限到證書逐一排查如果適配后請(qǐng)求一直超時(shí)第一步不是看代碼而是確認(rèn)鴻蒙工程里是否真的加入了INTERNET權(quán)限。我見過(guò)不止一個(gè)人改了代碼但忘記在module.json5里補(bǔ)權(quán)限結(jié)果所有網(wǎng)絡(luò)請(qǐng)求全部失敗。第二步確認(rèn)服務(wù)端地址的證書。用瀏覽器能訪問(wèn)不代表鴻蒙設(shè)備能訪問(wèn)。如果服務(wù)端是內(nèi)網(wǎng) IP、自簽名證書必須先處理證書信任否則原生網(wǎng)絡(luò)層會(huì)直接在 TLS 握手階段丟棄請(qǐng)求。第三步才是看適配層有沒有正確傳遞 headers。排查時(shí)可以在鴻蒙側(cè)原生網(wǎng)絡(luò)代碼里加一個(gè)調(diào)試日志打印出完整的請(qǐng)求 URL 和 headers。這個(gè)方法比在 Dart 層猜要快得多。我通常會(huì)在開發(fā)階段把響應(yīng)體也打印出來(lái)重點(diǎn)確認(rèn)返回的 JSON 編碼。若響應(yīng)體里中文是\uXXXX形式不是問(wèn)題亂碼才是問(wèn)題。4.3 數(shù)據(jù)不一致DTO 字段映射和時(shí)區(qū)問(wèn)題服務(wù)調(diào)用通了之后最煩的是“字段名對(duì)不上”的問(wèn)題。鴻蒙端拿到的 JSON 是created_at但 DTO 里聲明的是createdAt。如果漏寫JsonKey反序列化結(jié)果就是 null并且不會(huì)報(bào)編譯錯(cuò)誤。這種問(wèn)題在聯(lián)調(diào)時(shí)非常隱蔽因?yàn)橹挥芯唧w業(yè)務(wù)邏輯訪問(wèn)這個(gè)字段時(shí)才會(huì)暴露。另外就是時(shí)間字段。服務(wù)端返回的是 UTC 時(shí)間Dart 的DateTime默認(rèn)會(huì)帶上本地時(shí)區(qū)。不同設(shè)備時(shí)區(qū)設(shè)置不同就會(huì)導(dǎo)致同一份數(shù)據(jù)在不同設(shè)備上顯示的時(shí)間不一樣。我在適配時(shí)要求所有時(shí)間字段在 DTO 解析階段統(tǒng)一轉(zhuǎn)成 UTC 存儲(chǔ)顯示層再做時(shí)區(qū)轉(zhuǎn)換。三端同步測(cè)試時(shí)這個(gè)策略非常有效。4.4 典型問(wèn)題速查表癥狀可能原因?qū)Σ咚姓?qǐng)求直接失敗鴻蒙工程沒有 INTERNET 權(quán)限在 module.json5 中加入權(quán)限請(qǐng)求成功但響應(yīng)亂碼響應(yīng)體沒有按 UTF-8 解碼在原生網(wǎng)絡(luò)層明確解碼編碼HTTP 200 但 DTO 字段為 nullJSON 字段名和 DTO key 不一致用 JsonKey 顯式映射并發(fā)請(qǐng)求時(shí) token 刷新多次缺少全局刷新鎖用單一的 refresh future部分接口超時(shí)超時(shí)時(shí)間設(shè)置過(guò)短區(qū)分連接超時(shí)和讀取超時(shí)自簽名證書請(qǐng)求失敗證書不在信任域配置鴻蒙網(wǎng)絡(luò)證書白名單同一接口三端行為不一致請(qǐng)求體或 headers 構(gòu)造不同統(tǒng)一走同一個(gè)本地包適配層這張表不是萬(wàn)能藥但基本覆蓋了我在鴻蒙適配過(guò)程中遇到的 80% 問(wèn)題可以作為自查清單使用。5. 個(gè)人總結(jié)與后續(xù)建議5.1 性能與包體積觀察替換原生網(wǎng)絡(luò)通道后每一次請(qǐng)求會(huì)比純 Dart 的dart:io多一次 MethodChannel 調(diào)用。單次延遲通常在毫秒級(jí)對(duì)普通業(yè)務(wù)沒有太大影響但這種開銷會(huì)累積。如果業(yè)務(wù)里有大批量請(qǐng)求比如列表頁(yè)一次性拉 20 個(gè)接口建議把請(qǐng)求放進(jìn)并發(fā)池不要串行等待。鴻蒙原生網(wǎng)絡(luò)層有自己的連接池所以不必在 Dart 側(cè)重復(fù)實(shí)現(xiàn)連接復(fù)用。包體積方面本地包引入后增加的主要是鴻蒙原生網(wǎng)絡(luò)適配代碼和一些依賴整體增量不大。真正需要關(guān)注的是 JSON 代碼生成文件的數(shù)量。如果 DTO 特別多生成后的.g.dart文件會(huì)讓代碼體積膨脹這也是使用 json_serializable 的代價(jià)。5.2 團(tuán)隊(duì)協(xié)作與回歸建議鴻蒙適配不是一個(gè)人能長(zhǎng)期維護(hù)的。如果團(tuán)隊(duì)里還有其他人負(fù)責(zé)服務(wù)端和其他端最好把 DTO 生成、本地包構(gòu)建、適配層日志這三塊獨(dú)立分工。我后來(lái)把 DTO 生成腳本放進(jìn)了 CI每次服務(wù)端接口變更后自動(dòng)跑一遍生成新的 Dart 文件然后三端一起提交。這個(gè)流程讓“跨端服務(wù)調(diào)用同步”從口頭約束變成了自動(dòng)化約束。回歸測(cè)試也要盡量復(fù)用現(xiàn)有 Flutter 測(cè)試用例。不要只測(cè)鴻蒙端Android 和 iOS 也要跑一遍確保本地包的替換沒有破壞原有行為。我的經(jīng)驗(yàn)是加一個(gè)環(huán)境變量切換適配層的“真實(shí)網(wǎng)絡(luò)/模擬網(wǎng)絡(luò)”實(shí)現(xiàn)能同時(shí)滿足單元測(cè)試和端到端聯(lián)調(diào)。5.3 最后分享一個(gè)小技巧排查鴻蒙適配問(wèn)題時(shí)我習(xí)慣在本地包里加一個(gè)叫H-ADAPTER的自定義響應(yīng)頭。每次請(qǐng)求結(jié)束后如果響應(yīng)頭里帶了這個(gè)標(biāo)記說(shuō)明請(qǐng)求確實(shí)走過(guò)了鴻蒙適配層而不是被某種緩存或替代邏輯攔截。這個(gè)標(biāo)記本身沒有業(yè)務(wù)含義但在多端聯(lián)調(diào)時(shí)能快速確認(rèn)請(qǐng)求路徑省去很多扯皮時(shí)間。如果后續(xù)要擴(kuò)展鴻蒙設(shè)備形態(tài)比如平板、折疊屏建議把適配層繼續(xù)保持在消息管道這一步不動(dòng)需要?jiǎng)討B(tài)適配的通常只是 UI 層。把網(wǎng)絡(luò)和序列化穩(wěn)定住框架才不會(huì)在設(shè)備形態(tài)變化時(shí)重新翻工。 Flutter鴻蒙適配實(shí)戰(zhàn)：servicestack強(qiáng)類型JSON與消息管道改造
做 Flutter 時(shí)間稍微長(zhǎng)一點(diǎn)的人遲早會(huì)碰到鴻蒙適配。我這次接到的任務(wù)不算復(fù)雜一個(gè)已經(jīng)在 Android 和 iOS 跑得很穩(wěn)的 Flutter 工程要往鴻蒙設(shè)備上搬。業(yè)務(wù)層所有服務(wù)調(diào)用走的都是 servicestack它負(fù)責(zé)把 Dart 里的強(qiáng)類型請(qǐng)求對(duì)象變成 JSON再通過(guò) HTTP 發(fā)給服務(wù)端響應(yīng)也自動(dòng)反序列化回 DTO。問(wèn)題在于這個(gè)庫(kù)在設(shè)計(jì)時(shí)并沒有把鴻蒙 Flutter 運(yùn)行時(shí)納入考量導(dǎo)致真正適配時(shí)有幾個(gè)坎需要繞。這篇文章想把適配路徑寫清楚重點(diǎn)放在 Message-based 架構(gòu)集成、強(qiáng)類型 JSON 序列化這塊還有跨端服務(wù)調(diào)用同步的一點(diǎn)經(jīng)驗(yàn)。適合正在做 Flutter 鴻蒙化的同行參考也適合剛接手這類改造、心里沒底的同學(xué)。1. 適配前的背景與整體拆解1.1 先搞清楚 servicestack 到底做了什么servicestack 不是一個(gè)普通的 HTTP 請(qǐng)求庫(kù)它是一整套 Message-based 服務(wù)調(diào)用框架。使用方先定義強(qiáng)類型 DTO比如GetUserRequest、GetUserResponse然后通過(guò)客戶端把請(qǐng)求對(duì)象發(fā)出去框架負(fù)責(zé)把對(duì)象序列化成 JSON 報(bào)文發(fā)給服務(wù)端再把返回的 JSON 包裝成對(duì)應(yīng)的響應(yīng) DTO。整個(gè)鏈路對(duì)業(yè)務(wù)層來(lái)說(shuō)像是“調(diào)用本地方法”一樣。這套設(shè)計(jì)在企業(yè)級(jí)項(xiàng)目里很有優(yōu)勢(shì)因?yàn)榉?wù)端和客戶端的接口契約是明確的DTO 字段變化會(huì)直接影響編譯結(jié)果比維護(hù)一堆散落的MapString, dynamic要安全得多。再加上 servicestack 自帶服務(wù)端元數(shù)據(jù)支持可以生成 Dart 客戶端代碼兩端 DTO 的同步成本會(huì)低很多。但代價(jià)也很明顯它不是一個(gè)“零配置”的庫(kù)實(shí)際請(qǐng)求時(shí)需要處理 URL 拼接、Headers 注入、查詢參數(shù)、JSON 編解碼、超時(shí)、異常映射等一組邏輯這些邏輯背后依賴的是 Flutter 常規(guī)環(huán)境下的 HTTP 能力。如果這個(gè)庫(kù)只跑在 Android 和 iOS 上基本上不需要關(guān)心底層網(wǎng)絡(luò)實(shí)現(xiàn)。要移植到鴻蒙 Flutter 運(yùn)行時(shí)就得先確認(rèn)兩件事第一庫(kù)用到的純 Dart 能力在鴻蒙環(huán)境里是否完整第二它默認(rèn)走的網(wǎng)絡(luò)棧、平臺(tái)通道、簽名校驗(yàn)這些能力鴻蒙平臺(tái)是否完全兼容。我這次踩的坑其實(shí)都集中在這兩個(gè)問(wèn)題上。1.2 鴻蒙 Flutter 運(yùn)行時(shí)和常規(guī) Flutter 的三點(diǎn)差異不是說(shuō)同樣的 Dart 代碼復(fù)制過(guò)去就能跑。鴻蒙版 Flutter 在工程結(jié)構(gòu)、插件機(jī)制、平臺(tái)通道幾個(gè)維度上和 Android/iOS 是有實(shí)質(zhì)性差異的。工程結(jié)構(gòu)上鴻蒙側(cè)會(huì)多出一個(gè)ohos平臺(tái)目錄原生代碼是用 ArkTS 這類語(yǔ)言組織而不是原來(lái)的 Java/Kotlin/ObjC。Flutter 插件如果只實(shí)現(xiàn)了 Android/iOS 原生端在鴻蒙設(shè)備上就無(wú)法工作必須額外實(shí)現(xiàn)鴻蒙平臺(tái)的插件代碼。純 Dart 寫的包通常不受影響但前提是它沒有隱式依賴原生能力。平臺(tái)通道上Flutter 的 MethodChannel 機(jī)制在鴻蒙上同樣存在但通道的“另一端”需要鴻蒙側(cè)原生代碼實(shí)現(xiàn)。如果三方庫(kù)內(nèi)部依賴某個(gè)插件提供的通道而該插件沒有鴻蒙實(shí)現(xiàn)就只能在適配時(shí)自己補(bǔ)齊。最容易被忽略的是網(wǎng)絡(luò)能力。雖然 Dart 的dart:io在鴻蒙 Flutter 上基本可用但證書校驗(yàn)、代理設(shè)置、DNS 解析這類操作系統(tǒng)底層的網(wǎng)絡(luò)策略和 Android/iOS 并不完全一致。尤其在企業(yè)內(nèi)網(wǎng)環(huán)境中常常需要走自建證書或特殊代理直接用默認(rèn) HTTP 棧容易出現(xiàn)“代碼沒報(bào)錯(cuò)請(qǐng)求卻超時(shí)”的詭異現(xiàn)象。servicestack 屬于偏純 Dart 實(shí)現(xiàn)的三方庫(kù)所以第一關(guān)其實(shí)是網(wǎng)絡(luò)層然后才是 JSON 序列化和平臺(tái)通道。如果一開始就把它當(dāng)成一個(gè)“純 Dart 包直接引入”后面會(huì)被各種運(yùn)行期問(wèn)題抓瞎。1.3 為什么我選擇“替換底層、保留業(yè)務(wù)層”的方案當(dāng)時(shí)擺在我面前的有三條路。第一條路是直接升級(jí)到 servicestack 官方最新版本看它是否已經(jīng)支持鴻蒙。這個(gè)方法最省事但我查了一下當(dāng)時(shí)的版本并沒有針對(duì)鴻蒙做專門適配而且新版本升級(jí)可能會(huì)帶來(lái) DTO 生成邏輯的變化風(fēng)險(xiǎn)不可控。第二條路是在業(yè)務(wù)層包一層全新客戶端重新封裝一套 RestClient。這個(gè)方案的隔離效果很好但業(yè)務(wù)代碼改動(dòng)量太大幾十個(gè)請(qǐng)求 DTO 都要處理而且相當(dāng)于把 servicestack 的價(jià)值全部丟掉維護(hù)成本不降反升。第三條路也是我實(shí)際采用的思路復(fù)制一份 servicestack 源碼到工程里作為本地包維護(hù)然后把它的網(wǎng)絡(luò)傳輸層替換成鴻蒙可用的實(shí)現(xiàn)。業(yè)務(wù)層照常調(diào)用JsonServiceClient照常使用強(qiáng)類型 DTO框架內(nèi)部負(fù)責(zé)把請(qǐng)求投遞到鴻蒙原生的網(wǎng)絡(luò)能力上。選用第三條路的核心原因是兼容性風(fēng)險(xiǎn)最小。本地包和業(yè)務(wù)層之間保持原有接口業(yè)務(wù)層不需要感知鴻蒙適配的存在。替換點(diǎn)集中在請(qǐng)求發(fā)送、響應(yīng)接收、錯(cuò)誤處理這幾個(gè)關(guān)鍵函數(shù)中出現(xiàn)問(wèn)題時(shí)只需要對(duì)著一個(gè)適配層排查不需要全局翻代碼。提示不是所有三方庫(kù)都適合“復(fù)制源碼”這個(gè)方案。servicestack 的源碼體量適中、依賴邊界清晰網(wǎng)絡(luò)層相對(duì)獨(dú)立所以 fork 成本可控。如果你的庫(kù)是幾千個(gè)文件、依賴鏈極深最好先評(píng)估一下維護(hù)負(fù)擔(dān)。2. 環(huán)境準(zhǔn)備與工程改造實(shí)操2.1 先搭一個(gè)鴻蒙 Flutter 工程把現(xiàn)有 lib 遷進(jìn)去所謂鴻蒙化適配前提是有一個(gè)能跑通的鴻蒙 Flutter 工程。如果你已經(jīng)有鴻蒙版本的 Flutter SDK可以在項(xiàng)目目錄下創(chuàng)建ohos平臺(tái)代碼。大致流程是先用鴻蒙版 Flutter 工具創(chuàng)建一個(gè)支持ohos平臺(tái)的新工程再把原來(lái)項(xiàng)目里的lib/目錄、資源文件、pubspec 依賴整體遷移過(guò)來(lái)。新工程會(huì)生成一個(gè)ohos目錄里面是鴻蒙原生工程的入口文件包括entry/src/main/module.json5、entry/src/main/ets等。業(yè)務(wù) Dart 代碼基本不需要改重點(diǎn)是把pubspec.yaml里的依賴關(guān)系理清楚。遷移完成后我建議第一件事就是跑一次鴻蒙模擬器上的“Hello App”確認(rèn) Flutter 引擎和鴻蒙平臺(tái)的基礎(chǔ)通道是通的再做后續(xù)適配。這一步聽起來(lái)簡(jiǎn)單但容易被忽略的是包名和 Bundle 名。鴻蒙工程對(duì)包名規(guī)范有自己的要求如果你的 Flutter 項(xiàng)目用了 Android 的 applicationId 或 iOS 的 bundleId遷移到鴻蒙時(shí)需要映射好。否則后面在做平臺(tái)通道或拉起系統(tǒng)能力時(shí)會(huì)報(bào)“能力未配置”一類的錯(cuò)誤。2.2 用 dependency_overrides 把本地包替換進(jìn)去為了讓業(yè)務(wù)層無(wú)感我建議不要把修改后的 servicestack 代碼直接提交到全局 SDK 目錄里而是放到自己的工程內(nèi)做一個(gè)本地包。在pubspec.yaml中通過(guò)dependency_overrides指定本地路徑dependencies: flutter: sdk: flutter servicestack: ^4.1.0 http: ^1.1.0 json_annotation: ^4.8.0 dev_dependencies: build_runner: ^2.4.0 json_serializable: ^6.7.0 dependency_overrides: servicestack: path: packages/servicestack_harmony這樣服務(wù)端和本地包在邏輯上是兩份代碼但最終 Flutter 工程解析依賴時(shí)會(huì)強(qiáng)制使用本地包。這個(gè)方式的靈活之處在于如果你需要對(duì)比官方版本和鴻蒙改動(dòng)版本的行為直接改dependency_overrides的路徑即可業(yè)務(wù)代碼零改動(dòng)。本地包目錄里除了源碼還需要把pubspec.yaml一并復(fù)制保證它的依賴解析和主工程一致。我第一次做的時(shí)候就漏了這一步結(jié)果本地包的依賴只能用相對(duì)路徑硬編碼非常痛苦。2.3 配置鴻蒙網(wǎng)絡(luò)權(quán)限和明文流量如果服務(wù)端是 HTTPS且證書正常那么只需在鴻蒙工程里聲明 INTERNET 權(quán)限。找到ohos/entry/src/main/module.json5在requestPermissions里加入{ name: ohos.permission.INTERNET, }如果內(nèi)網(wǎng)環(huán)境調(diào)試時(shí)用到 HTTP 明文請(qǐng)求鴻蒙默認(rèn)會(huì)攔截必須在網(wǎng)絡(luò)安全配置里允許明文流量。不同版本的鴻蒙工程目錄結(jié)構(gòu)略有差異通常是在resources/base/profile/network_config.json中配置{ network-security-config: { base-config: { cleartext-traffic-permitted: true }, domain-config: [] } }注意千萬(wàn)不要把cleartext-traffic-permitted直接設(shè)置成全局 true 然后發(fā)布到生產(chǎn)環(huán)境。正確做法是給指定的內(nèi)網(wǎng)測(cè)試域名配置單獨(dú)的白名單比如domain-config里寫cleartext-traffic-permitted為 true其他域名仍然強(qiáng)制 HTTPS。這不僅是安全要求也避免被應(yīng)用市場(chǎng)或合規(guī)審查卡住。另外一個(gè)容易踩的坑是自簽名證書。如果服務(wù)端使用的是自建 CA鴻蒙原生網(wǎng)絡(luò)棧默認(rèn)可能不信任。常見做法是把 CA 證書放到鴻蒙工程的安全配置中或者在適配層臨時(shí)關(guān)閉證書校驗(yàn)。后者只適合聯(lián)調(diào)不適合生產(chǎn)。我的建議是盡量走正規(guī)的證書信任配置否則后面運(yùn)維會(huì)被證書問(wèn)題反復(fù)折騰。3. 核心模塊適配強(qiáng)類型 JSON 與 Message-based 管道3.1 強(qiáng)類型 JSON 序列化的鴻蒙兼容改造servicestack 的強(qiáng)類型能力本質(zhì)上依賴于“DTO 到 JSON 字段”的雙向映射。在 Dart 里通常每個(gè)請(qǐng)求 DTO 都需要有toJson()方法每個(gè)響應(yīng) DTO 需要有fromJson()方法。在鴻蒙適配時(shí)這部分代碼可以繼續(xù)使用 json_serializable 生成也可以手寫。我建議大數(shù)據(jù)量大團(tuán)隊(duì)用 json_serializable因?yàn)樗鼫p少手寫出錯(cuò)的概率。比如import package:json_annotation/json_annotation.dart; part create_order_request.g.dart; JsonSerializable() class CreateOrderRequest { final String orderNo; final double amount; JsonKey(name: createdAt) final DateTime createdAt; CreateOrderRequest({ required this.orderNo, required this.amount, required this.createdAt, }); factory CreateOrderRequest.fromJson(MapString, dynamic json) _$CreateOrderRequestFromJson(json); MapString, dynamic toJson() _$CreateOrderRequestToJson(this); }使用 json_serializable 后序列化邏輯是編譯期生成的不依賴運(yùn)行時(shí)反射這在鴻蒙 Flutter 上運(yùn)行沒有兼容問(wèn)題。需要小心的反而是服務(wù)端字段風(fēng)格。比如服務(wù)端返回user_name而 DTO 里定義的是userName就必須用JsonKey(name: user_name)做映射。我遇到過(guò)團(tuán)隊(duì)里兩個(gè)平臺(tái)字段命名風(fēng)格不一致導(dǎo)致 Windows 端正常、鴻蒙端拿不到值的情況。建議把命名策略統(tǒng)一放進(jìn) CI 校驗(yàn)?zāi)_本里每次生成 DTO 后自動(dòng)比對(duì)服務(wù)端契約。從實(shí)踐角度看JSON 適配還涉及兩個(gè)細(xì)節(jié)。第一個(gè)是編碼問(wèn)題。鴻蒙原生網(wǎng)絡(luò)層拿到的字符串如果按默認(rèn)編碼處理中文字符容易亂碼。HTTP 響應(yīng)體必須明確使用 UTF-8 解碼并且在構(gòu)造請(qǐng)求體時(shí)也把 body 轉(zhuǎn)成 UTF-8 字節(jié)流。很多運(yùn)行期“能連上但是數(shù)據(jù)是亂碼”的問(wèn)題都是這里沒有處理干凈。第二個(gè)是數(shù)字類型。Dart 的int和double在 JSON 里沒有嚴(yán)格區(qū)分服務(wù)端返回100.0時(shí)Dart 端可能解析成int或double這取決于解析器的行為。如果 DTO 字段聲明為double但 JSON 里寫成100某些嚴(yán)格反序列化器會(huì)直接拋類型錯(cuò)誤。處理辦法是給反序列化邏輯加一個(gè)可配置的num到目標(biāo)類型的轉(zhuǎn)換或者統(tǒng)一要求服務(wù)端輸出規(guī)范。3.2 Message-based 請(qǐng)求管道的替換如果只是改 DTO 的序列化業(yè)務(wù)層也許還能正常跑。但真正的問(wèn)題在發(fā)送環(huán)節(jié)。servicestack 的請(qǐng)求流程是把 DTO 對(duì)象交給一個(gè)“消息管道”這個(gè)管道負(fù)責(zé)合并 query 參數(shù)、填充 headers、發(fā)送 HTTP 請(qǐng)求、接收響應(yīng)并反序列化。在鴻蒙適配中我把它替換成了一個(gè)HarmonyHttpClient。思路不復(fù)雜業(yè)務(wù)層不直接看到網(wǎng)絡(luò)實(shí)現(xiàn)它只負(fù)責(zé)傳CreateOrderRequest進(jìn)來(lái)框架內(nèi)部將請(qǐng)求變成 JSON然后調(diào)用鴻蒙原生網(wǎng)絡(luò)能力。偽代碼大概是這樣的class HarmonyHttpClient { static const MethodChannel _channel MethodChannel(com.example.harmony_http); FutureResponseData postJson({ required String url, required MapString, String headers, required String body, }) async { try { final result await _channel.invokeMethod(request, { method: POST, url: url, headers: headers, body: body, }); return ResponseData.fromNative(result); } on PlatformException catch (e) { throw ServiceStackException(e.message ?? harmony http error); } } }鴻蒙側(cè)則用原生網(wǎng)絡(luò)能力接收請(qǐng)求參數(shù)執(zhí)行真正的 HTTP 調(diào)用再把狀態(tài)碼、響應(yīng)頭、響應(yīng)體原樣返回。這樣做的目的是讓 Flutter 層只做“報(bào)文處理”不碰底層的網(wǎng)絡(luò)策略保證和企業(yè)內(nèi)網(wǎng)網(wǎng)關(guān)、代理、證書配置保持一致。你不需要照抄這段代碼因?yàn)椴煌姹镜?servicestack 內(nèi)部類名可能不同。關(guān)鍵是要找到負(fù)責(zé)“發(fā)請(qǐng)求”的那個(gè)方法把它替換成走鴻蒙原生網(wǎng)絡(luò)的實(shí)現(xiàn)。替換完成后服務(wù)端收到的請(qǐng)求頭、請(qǐng)求體不能發(fā)生變化否則會(huì)破壞既有契約。我在實(shí)現(xiàn)時(shí)額外加了一個(gè)開關(guān)線上走原生網(wǎng)絡(luò)通道本地單測(cè)走 mocked 通道。這個(gè)開關(guān)對(duì)調(diào)試非常有幫助因?yàn)?Dart 側(cè)可以模擬各類異常響應(yīng)不需要每次都啟動(dòng)鴻蒙設(shè)備。3.3 跨端服務(wù)調(diào)用同步與并發(fā)控制所謂“跨端服務(wù)調(diào)用同步”我理解包含兩層意思。一層是語(yǔ)義同步在 Android、iOS、鴻蒙三端調(diào)用同一個(gè)服務(wù)接口行為應(yīng)該一致。另一層是并發(fā)同步多個(gè)請(qǐng)求同時(shí)進(jìn)來(lái)時(shí)token 刷新、排隊(duì)順序不能亂。第一層相對(duì)容易。只要保證管道實(shí)現(xiàn)遵循同一個(gè)請(qǐng)求體構(gòu)造規(guī)則三端發(fā)出去的報(bào)文一致服務(wù)端返回的結(jié)果就不應(yīng)該有差異。真正麻煩的是第二層典型場(chǎng)景是 token 過(guò)期。很多團(tuán)隊(duì)的做法是在客戶端攔截器里處理 401收到 401 后先去后臺(tái)刷新 token刷新成功再重放原請(qǐng)求。這個(gè)過(guò)程在純 Dart 里寫沒問(wèn)題但放到鴻蒙適配后如果請(qǐng)求走的是原生通道刷新 token 的請(qǐng)求本身可能也走了同一個(gè)通道就會(huì)形成“所有請(qǐng)求都在等待一個(gè)刷新請(qǐng)求完成”的死鎖。我當(dāng)時(shí)的處理方式是加一個(gè)全局的刷新鎖FutureT _synchronizedRefreshT(FutureT Function() action) { if (_refreshFuture ! null) { return _refreshFuture!.then((_) action()); } final future action(); _refreshFuture future; return future.whenComplete(() _refreshFuture null); }第一次請(qǐng)求遇到 401 時(shí)會(huì)創(chuàng)建刷新任務(wù)其他并發(fā)請(qǐng)求則直接等待同一個(gè)_refreshFuture完成后重放。這樣能保證同時(shí)只有一個(gè)刷新請(qǐng)求在跑避免 token 互相覆蓋。還有一個(gè)容易忽略的點(diǎn)是請(qǐng)求超時(shí)。鴻蒙原生網(wǎng)絡(luò)棧默認(rèn)的超時(shí)策略和dart:io不一定相同。如果服務(wù)端接口本身就要跑幾分鐘直接在客戶端設(shè)置一個(gè)固定超時(shí)時(shí)間可能誤殺長(zhǎng)任務(wù)。我的建議是把超時(shí)參數(shù)做成可配置項(xiàng)并且區(qū)分“連接超時(shí)”和“讀取超時(shí)”不要一刀切。3.4 鑒權(quán)、錯(cuò)誤碼與重試策略企業(yè)級(jí)服務(wù)調(diào)用不可能只有 happy path。我的適配層里有一個(gè)專門處理錯(cuò)誤碼的組件會(huì)統(tǒng)一捕獲三類錯(cuò)誤第一類是網(wǎng)絡(luò)層錯(cuò)誤比如 DNS 解析失敗、連接被拒絕、讀取超時(shí)。這類錯(cuò)誤一般可以重試但要有次數(shù)上限和退避策略。第二類是 HTTP 狀態(tài)碼錯(cuò)誤比如 401、403、500。401 走 token 刷新邏輯403 直接拒絕重試500 可以留到下一次人為觸發(fā)重試。第三類是業(yè)務(wù)錯(cuò)誤即使 HTTP 返回 200服務(wù)端也可能在響應(yīng)體里放一個(gè)統(tǒng)一錯(cuò)誤碼。這類錯(cuò)誤必須透?jìng)鹘o業(yè)務(wù)層不能盲目重試。我在本地包里加了一個(gè)請(qǐng)求日志開關(guān)類似這樣class ServiceStackOptions { final bool enableLog; final bool enableRetry; final Duration connectTimeout; final Duration receiveTimeout; }開關(guān)只在開發(fā)階段打開會(huì)輸出請(qǐng)求 URL、請(qǐng)求體摘要、響應(yīng)狀態(tài)碼和耗時(shí)。排查鴻蒙適配問(wèn)題時(shí)這份日志非常關(guān)鍵。因?yàn)樵W(wǎng)絡(luò)層很多異常不會(huì)自動(dòng)拋到 Dart 層沒有日志的話就只能靠鴻蒙側(cè)控制臺(tái)一點(diǎn)一點(diǎn)摳。4. 實(shí)戰(zhàn)驗(yàn)證與問(wèn)題排查4.1 編譯期問(wèn)題依賴缺失與類型沖突鴻蒙化適配最常見的編譯錯(cuò)誤并不是 servicestack 本身的問(wèn)題而是它的傳遞依賴在鴻蒙工程里沒有被正確解析。比如某個(gè)包依賴package:http但鴻蒙工程里只聲明了 servicestack沒有顯式聲明 http。這種錯(cuò)誤在 Android/iOS 上可能不會(huì)出現(xiàn)因?yàn)?Gradle/Xcode 會(huì)自動(dòng)處理部分依賴但鴻蒙 Flutter 工程的依賴解析更嚴(yán)格。解決辦法很簡(jiǎn)單在pubspec.yaml里把所有用到的頂層依賴顯式聲明一遍。不要信任“自動(dòng)解析”更不要偷懶縮寫依賴版本否則后續(xù)環(huán)境一換就崩。類型沖突主要集中在dynamic和強(qiáng)類型之間。servicestack 里有些公開 API 返回值是dynamic業(yè)務(wù)層在使用時(shí)通常會(huì)做一次強(qiáng)轉(zhuǎn)。鴻蒙環(huán)境的編譯期類型檢查比 Android 更嚴(yán)格時(shí)強(qiáng)轉(zhuǎn)失敗會(huì)拋TypeError。解決辦法是在適配層包一層類型安全轉(zhuǎn)換函數(shù)不要直接把dynamic拋給業(yè)務(wù)層。4.2 運(yùn)行期連不上服務(wù)端從權(quán)限到證書逐一排查如果適配后請(qǐng)求一直超時(shí)第一步不是看代碼而是確認(rèn)鴻蒙工程里是否真的加入了INTERNET權(quán)限。我見過(guò)不止一個(gè)人改了代碼但忘記在module.json5里補(bǔ)權(quán)限結(jié)果所有網(wǎng)絡(luò)請(qǐng)求全部失敗。第二步確認(rèn)服務(wù)端地址的證書。用瀏覽器能訪問(wèn)不代表鴻蒙設(shè)備能訪問(wèn)。如果服務(wù)端是內(nèi)網(wǎng) IP、自簽名證書必須先處理證書信任否則原生網(wǎng)絡(luò)層會(huì)直接在 TLS 握手階段丟棄請(qǐng)求。第三步才是看適配層有沒有正確傳遞 headers。排查時(shí)可以在鴻蒙側(cè)原生網(wǎng)絡(luò)代碼里加一個(gè)調(diào)試日志打印出完整的請(qǐng)求 URL 和 headers。這個(gè)方法比在 Dart 層猜要快得多。我通常會(huì)在開發(fā)階段把響應(yīng)體也打印出來(lái)重點(diǎn)確認(rèn)返回的 JSON 編碼。若響應(yīng)體里中文是\uXXXX形式不是問(wèn)題亂碼才是問(wèn)題。4.3 數(shù)據(jù)不一致DTO 字段映射和時(shí)區(qū)問(wèn)題服務(wù)調(diào)用通了之后最煩的是“字段名對(duì)不上”的問(wèn)題。鴻蒙端拿到的 JSON 是created_at但 DTO 里聲明的是createdAt。如果漏寫JsonKey反序列化結(jié)果就是 null并且不會(huì)報(bào)編譯錯(cuò)誤。這種問(wèn)題在聯(lián)調(diào)時(shí)非常隱蔽因?yàn)橹挥芯唧w業(yè)務(wù)邏輯訪問(wèn)這個(gè)字段時(shí)才會(huì)暴露。另外就是時(shí)間字段。服務(wù)端返回的是 UTC 時(shí)間Dart 的DateTime默認(rèn)會(huì)帶上本地時(shí)區(qū)。不同設(shè)備時(shí)區(qū)設(shè)置不同就會(huì)導(dǎo)致同一份數(shù)據(jù)在不同設(shè)備上顯示的時(shí)間不一樣。我在適配時(shí)要求所有時(shí)間字段在 DTO 解析階段統(tǒng)一轉(zhuǎn)成 UTC 存儲(chǔ)顯示層再做時(shí)區(qū)轉(zhuǎn)換。三端同步測(cè)試時(shí)這個(gè)策略非常有效。4.4 典型問(wèn)題速查表癥狀可能原因?qū)Σ咚姓?qǐng)求直接失敗鴻蒙工程沒有 INTERNET 權(quán)限在 module.json5 中加入權(quán)限請(qǐng)求成功但響應(yīng)亂碼響應(yīng)體沒有按 UTF-8 解碼在原生網(wǎng)絡(luò)層明確解碼編碼HTTP 200 但 DTO 字段為 nullJSON 字段名和 DTO key 不一致用 JsonKey 顯式映射并發(fā)請(qǐng)求時(shí) token 刷新多次缺少全局刷新鎖用單一的 refresh future部分接口超時(shí)超時(shí)時(shí)間設(shè)置過(guò)短區(qū)分連接超時(shí)和讀取超時(shí)自簽名證書請(qǐng)求失敗證書不在信任域配置鴻蒙網(wǎng)絡(luò)證書白名單同一接口三端行為不一致請(qǐng)求體或 headers 構(gòu)造不同統(tǒng)一走同一個(gè)本地包適配層這張表不是萬(wàn)能藥但基本覆蓋了我在鴻蒙適配過(guò)程中遇到的 80% 問(wèn)題可以作為自查清單使用。5. 個(gè)人總結(jié)與后續(xù)建議5.1 性能與包體積觀察替換原生網(wǎng)絡(luò)通道后每一次請(qǐng)求會(huì)比純 Dart 的dart:io多一次 MethodChannel 調(diào)用。單次延遲通常在毫秒級(jí)對(duì)普通業(yè)務(wù)沒有太大影響但這種開銷會(huì)累積。如果業(yè)務(wù)里有大批量請(qǐng)求比如列表頁(yè)一次性拉 20 個(gè)接口建議把請(qǐng)求放進(jìn)并發(fā)池不要串行等待。鴻蒙原生網(wǎng)絡(luò)層有自己的連接池所以不必在 Dart 側(cè)重復(fù)實(shí)現(xiàn)連接復(fù)用。包體積方面本地包引入后增加的主要是鴻蒙原生網(wǎng)絡(luò)適配代碼和一些依賴整體增量不大。真正需要關(guān)注的是 JSON 代碼生成文件的數(shù)量。如果 DTO 特別多生成后的.g.dart文件會(huì)讓代碼體積膨脹這也是使用 json_serializable 的代價(jià)。5.2 團(tuán)隊(duì)協(xié)作與回歸建議鴻蒙適配不是一個(gè)人能長(zhǎng)期維護(hù)的。如果團(tuán)隊(duì)里還有其他人負(fù)責(zé)服務(wù)端和其他端最好把 DTO 生成、本地包構(gòu)建、適配層日志這三塊獨(dú)立分工。我后來(lái)把 DTO 生成腳本放進(jìn)了 CI每次服務(wù)端接口變更后自動(dòng)跑一遍生成新的 Dart 文件然后三端一起提交。這個(gè)流程讓“跨端服務(wù)調(diào)用同步”從口頭約束變成了自動(dòng)化約束。回歸測(cè)試也要盡量復(fù)用現(xiàn)有 Flutter 測(cè)試用例。不要只測(cè)鴻蒙端Android 和 iOS 也要跑一遍確保本地包的替換沒有破壞原有行為。我的經(jīng)驗(yàn)是加一個(gè)環(huán)境變量切換適配層的“真實(shí)網(wǎng)絡(luò)/模擬網(wǎng)絡(luò)”實(shí)現(xiàn)能同時(shí)滿足單元測(cè)試和端到端聯(lián)調(diào)。5.3 最后分享一個(gè)小技巧排查鴻蒙適配問(wèn)題時(shí)我習(xí)慣在本地包里加一個(gè)叫H-ADAPTER的自定義響應(yīng)頭。每次請(qǐng)求結(jié)束后如果響應(yīng)頭里帶了這個(gè)標(biāo)記說(shuō)明請(qǐng)求確實(shí)走過(guò)了鴻蒙適配層而不是被某種緩存或替代邏輯攔截。這個(gè)標(biāo)記本身沒有業(yè)務(wù)含義但在多端聯(lián)調(diào)時(shí)能快速確認(rèn)請(qǐng)求路徑省去很多扯皮時(shí)間。如果后續(xù)要擴(kuò)展鴻蒙設(shè)備形態(tài)比如平板、折疊屏建議把適配層繼續(xù)保持在消息管道這一步不動(dòng)需要?jiǎng)討B(tài)適配的通常只是 UI 層。把網(wǎng)絡(luò)和序列化穩(wěn)定住框架才不會(huì)在設(shè)備形態(tài)變化時(shí)重新翻工。