戰(zhàn)：servicestack強(qiáng)類型JSON與消息管道改造)
做 Flutter 時(shí)間稍微長一點(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再通過 HTTP 發(fā)給服務(wù)端響應(yīng)也自動(dòng)反序列化回 DTO。問題在于這個(gè)庫在設(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)求庫它是一整套 Message-based 服務(wù)調(diào)用框架。使用方先定義強(qiáng)類型 DTO比如GetUserRequest、GetUserResponse然后通過客戶端把請(qǐng)求對(duì)象發(fā)出去框架負(fù)責(zé)把對(duì)象序列化成 JSON 報(bào)文發(fā)給服務(wù)端再把返回的 JSON 包裝成對(duì)應(yīng)的響應(yīng) DTO。整個(gè)鏈路對(duì)業(yè)務(wù)層來說像是“調(diào)用本地方法”一樣。這套設(shè)計(jì)在企業(yè)級(jí)項(xiàng)目里很有優(yōu)勢因?yàn)榉?wù)端和客戶端的接口契約是明確的DTO 字段變化會(huì)直接影響編譯結(jié)果比維護(hù)一堆散落的MapString, dynamic要安全得多。再加上 servicestack 自帶服務(wù)端元數(shù)據(jù)支持可以生成 Dart 客戶端代碼兩端 DTO 的同步成本會(huì)低很多。但代價(jià)也很明顯它不是一個(gè)“零配置”的庫實(shí)際請(qǐng)求時(shí)需要處理 URL 拼接、Headers 注入、查詢參數(shù)、JSON 編解碼、超時(shí)、異常映射等一組邏輯這些邏輯背后依賴的是 Flutter 常規(guī)環(huán)境下的 HTTP 能力。如果這個(gè)庫只跑在 Android 和 iOS 上基本上不需要關(guān)心底層網(wǎng)絡(luò)實(shí)現(xiàn)。要移植到鴻蒙 Flutter 運(yùn)行時(shí)就得先確認(rèn)兩件事第一庫用到的純 Dart 能力在鴻蒙環(huán)境里是否完整第二它默認(rèn)走的網(wǎng)絡(luò)棧、平臺(tái)通道、簽名校驗(yàn)這些能力鴻蒙平臺(tái)是否完全兼容。我這次踩的坑其實(shí)都集中在這兩個(gè)問題上。1.2 鴻蒙 Flutter 運(yùn)行時(shí)和常規(guī) Flutter 的三點(diǎn)差異不是說同樣的 Dart 代碼復(fù)制過去就能跑。鴻蒙版 Flutter 在工程結(jié)構(gòu)、插件機(jī)制、平臺(tái)通道幾個(gè)維度上和 Android/iOS 是有實(shí)質(zhì)性差異的。工程結(jié)構(gòu)上鴻蒙側(cè)會(huì)多出一個(gè)ohos平臺(tái)目錄原生代碼是用 ArkTS 這類語言組織而不是原來的 Java/Kotlin/ObjC。Flutter 插件如果只實(shí)現(xiàn)了 Android/iOS 原生端在鴻蒙設(shè)備上就無法工作必須額外實(shí)現(xiàn)鴻蒙平臺(tái)的插件代碼。純 Dart 寫的包通常不受影響但前提是它沒有隱式依賴原生能力。平臺(tái)通道上Flutter 的 MethodChannel 機(jī)制在鴻蒙上同樣存在但通道的“另一端”需要鴻蒙側(cè)原生代碼實(shí)現(xiàn)。如果三方庫內(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)的三方庫所以第一關(guān)其實(shí)是網(wǎng)絡(luò)層然后才是 JSON 序列化和平臺(tái)通道。如果一開始就把它當(dāng)成一個(gè)“純 Dart 包直接引入”后面會(huì)被各種運(yùn)行期問題抓瞎。1.3 為什么我選擇“替換底層、保留業(yè)務(wù)層”的方案當(dāng)時(shí)擺在我面前的有三條路。第一條路是直接升級(jí)到 servicestack 官方最新版本看它是否已經(jīng)支持鴻蒙。這個(gè)方法最省事但我查了一下當(dāng)時(shí)的版本并沒有針對(duì)鴻蒙做專門適配而且新版本升級(jí)可能會(huì)帶來 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)問題時(shí)只需要對(duì)著一個(gè)適配層排查不需要全局翻代碼。提示不是所有三方庫都適合“復(fù)制源碼”這個(gè)方案。servicestack 的源碼體量適中、依賴邊界清晰網(wǎng)絡(luò)層相對(duì)獨(dú)立所以 fork 成本可控。如果你的庫是幾千個(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)的新工程再把原來項(xiàng)目里的lib/目錄、資源文件、pubspec 依賴整體遷移過來。新工程會(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ù)適配。這一步聽起來簡單但容易被忽略的是包名和 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ù)層無感我建議不要把修改后的 servicestack 代碼直接提交到全局 SDK 目錄里而是放到自己的工程內(nèi)做一個(gè)本地包。在pubspec.yaml中通過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: [] } }注意千萬不要把cleartext-traffic-permitted直接設(shè)置成全局 true 然后發(fā)布到生產(chǎn)環(huán)境。正確做法是給指定的內(nèi)網(wǎng)測試域名配置單獨(dú)的白名單比如domain-config里寫cleartext-traffic-permitted為 true其他域名仍然強(qiáng)制 HTTPS。這不僅是安全要求也避免被應(yī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ì)被證書問題反復(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ù)端字段風(fēng)格。比如服務(wù)端返回user_name而 DTO 里定義的是userName就必須用JsonKey(name: user_name)做映射。我遇到過團(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ǎng)絡(luò)層拿到的字符串如果按默認(rèn)編碼處理中文字符容易亂碼。HTTP 響應(yīng)體必須明確使用 UTF-8 解碼并且在構(gòu)造請(qǐng)求體時(shí)也把 body 轉(zhuǎn)成 UTF-8 字節(jié)流。很多運(yùn)行期“能連上但是數(shù)據(jù)是亂碼”的問題都是這里沒有處理干凈。第二個(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ù)層也許還能正常跑。但真正的問題在發(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)來框架內(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ò)通道本地單測走 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)用同步”我理解包含兩層意思。一層是語義同步在 Android、iOS、鴻蒙三端調(diào)用同一個(gè)服務(wù)接口行為應(yīng)該一致。另一層是并發(fā)同步多個(gè)請(qǐng)求同時(shí)進(jìn)來時(shí)token 刷新、排隊(duì)順序不能亂。第一層相對(duì)容易。只要保證管道實(shí)現(xiàn)遵循同一個(gè)請(qǐng)求體構(gòu)造規(guī)則三端發(fā)出去的報(bào)文一致服務(wù)端返回的結(jié)果就不應(yīng)該有差異。真正麻煩的是第二層典型場景是 token 過期。很多團(tuán)隊(duì)的做法是在客戶端攔截器里處理 401收到 401 后先去后臺(tái)刷新 token刷新成功再重放原請(qǐng)求。這個(gè)過程在純 Dart 里寫沒問題但放到鴻蒙適配后如果請(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í)間可能誤殺長任務(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ò)誤必須透傳給業(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í)。排查鴻蒙適配問題時(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)證與問題排查4.1 編譯期問題依賴缺失與類型沖突鴻蒙化適配最常見的編譯錯(cuò)誤并不是 servicestack 本身的問題而是它的傳遞依賴在鴻蒙工程里沒有被正確解析。比如某個(gè)包依賴package:http但鴻蒙工程里只聲明了 servicestack沒有顯式聲明 http。這種錯(cuò)誤在 Android/iOS 上可能不會(huì)出現(xiàn)因?yàn)?Gradle/Xcode 會(huì)自動(dòng)處理部分依賴但鴻蒙 Flutter 工程的依賴解析更嚴(yá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)限。我見過不止一個(gè)人改了代碼但忘記在module.json5里補(bǔ)權(quán)限結(jié)果所有網(wǎng)絡(luò)請(qǐng)求全部失敗。第二步確認(rèn)服務(wù)端地址的證書。用瀏覽器能訪問不代表鴻蒙設(shè)備能訪問。如果服務(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)體也打印出來重點(diǎn)確認(rèn)返回的 JSON 編碼。若響應(yīng)體里中文是\uXXXX形式不是問題亂碼才是問題。4.3 數(shù)據(jù)不一致DTO 字段映射和時(shí)區(qū)問題服務(wù)調(diào)用通了之后最煩的是“字段名對(duì)不上”的問題。鴻蒙端拿到的 JSON 是created_at但 DTO 里聲明的是createdAt。如果漏寫JsonKey反序列化結(jié)果就是 null并且不會(huì)報(bào)編譯錯(cuò)誤。這種問題在聯(lián)調(diào)時(shí)非常隱蔽因?yàn)橹挥芯唧w業(yè)務(wù)邏輯訪問這個(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)換。三端同步測試時(shí)這個(gè)策略非常有效。4.4 典型問題速查表癥狀可能原因?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è)置過短區(qū)分連接超時(shí)和讀取超時(shí)自簽名證書請(qǐng)求失敗證書不在信任域配置鴻蒙網(wǎng)絡(luò)證書白名單同一接口三端行為不一致請(qǐng)求體或 headers 構(gòu)造不同統(tǒng)一走同一個(gè)本地包適配層這張表不是萬能藥但基本覆蓋了我在鴻蒙適配過程中遇到的 80% 問題可以作為自查清單使用。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)求比如列表頁一次性拉 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è)人能長期維護(hù)的。如果團(tuán)隊(duì)里還有其他人負(fù)責(zé)服務(wù)端和其他端最好把 DTO 生成、本地包構(gòu)建、適配層日志這三塊獨(dú)立分工。我后來把 DTO 生成腳本放進(jìn)了 CI每次服務(wù)端接口變更后自動(dòng)跑一遍生成新的 Dart 文件然后三端一起提交。這個(gè)流程讓“跨端服務(wù)調(diào)用同步”從口頭約束變成了自動(dòng)化約束?；貧w測試也要盡量復(fù)用現(xiàn)有 Flutter 測試用例。不要只測鴻蒙端Android 和 iOS 也要跑一遍確保本地包的替換沒有破壞原有行為。我的經(jīng)驗(yàn)是加一個(gè)環(huán)境變量切換適配層的“真實(shí)網(wǎng)絡(luò)/模擬網(wǎng)絡(luò)”實(shí)現(xiàn)能同時(shí)滿足單元測試和端到端聯(lián)調(diào)。5.3 最后分享一個(gè)小技巧排查鴻蒙適配問題時(shí)我習(xí)慣在本地包里加一個(gè)叫H-ADAPTER的自定義響應(yīng)頭。每次請(qǐng)求結(jié)束后如果響應(yīng)頭里帶了這個(gè)標(biāo)記說明請(qǐng)求確實(shí)走過了鴻蒙適配層而不是被某種緩存或替代邏輯攔截。這個(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í)間稍微長一點(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再通過 HTTP 發(fā)給服務(wù)端響應(yīng)也自動(dòng)反序列化回 DTO。問題在于這個(gè)庫在設(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)求庫它是一整套 Message-based 服務(wù)調(diào)用框架。使用方先定義強(qiáng)類型 DTO比如GetUserRequest、GetUserResponse然后通過客戶端把請(qǐng)求對(duì)象發(fā)出去框架負(fù)責(zé)把對(duì)象序列化成 JSON 報(bào)文發(fā)給服務(wù)端再把返回的 JSON 包裝成對(duì)應(yīng)的響應(yīng) DTO。整個(gè)鏈路對(duì)業(yè)務(wù)層來說像是“調(diào)用本地方法”一樣。這套設(shè)計(jì)在企業(yè)級(jí)項(xiàng)目里很有優(yōu)勢因?yàn)榉?wù)端和客戶端的接口契約是明確的DTO 字段變化會(huì)直接影響編譯結(jié)果比維護(hù)一堆散落的MapString, dynamic要安全得多。再加上 servicestack 自帶服務(wù)端元數(shù)據(jù)支持可以生成 Dart 客戶端代碼兩端 DTO 的同步成本會(huì)低很多。但代價(jià)也很明顯它不是一個(gè)“零配置”的庫實(shí)際請(qǐng)求時(shí)需要處理 URL 拼接、Headers 注入、查詢參數(shù)、JSON 編解碼、超時(shí)、異常映射等一組邏輯這些邏輯背后依賴的是 Flutter 常規(guī)環(huán)境下的 HTTP 能力。如果這個(gè)庫只跑在 Android 和 iOS 上基本上不需要關(guān)心底層網(wǎng)絡(luò)實(shí)現(xiàn)。要移植到鴻蒙 Flutter 運(yùn)行時(shí)就得先確認(rèn)兩件事第一庫用到的純 Dart 能力在鴻蒙環(huán)境里是否完整第二它默認(rèn)走的網(wǎng)絡(luò)棧、平臺(tái)通道、簽名校驗(yàn)這些能力鴻蒙平臺(tái)是否完全兼容。我這次踩的坑其實(shí)都集中在這兩個(gè)問題上。1.2 鴻蒙 Flutter 運(yùn)行時(shí)和常規(guī) Flutter 的三點(diǎn)差異不是說同樣的 Dart 代碼復(fù)制過去就能跑。鴻蒙版 Flutter 在工程結(jié)構(gòu)、插件機(jī)制、平臺(tái)通道幾個(gè)維度上和 Android/iOS 是有實(shí)質(zhì)性差異的。工程結(jié)構(gòu)上鴻蒙側(cè)會(huì)多出一個(gè)ohos平臺(tái)目錄原生代碼是用 ArkTS 這類語言組織而不是原來的 Java/Kotlin/ObjC。Flutter 插件如果只實(shí)現(xiàn)了 Android/iOS 原生端在鴻蒙設(shè)備上就無法工作必須額外實(shí)現(xiàn)鴻蒙平臺(tái)的插件代碼。純 Dart 寫的包通常不受影響但前提是它沒有隱式依賴原生能力。平臺(tái)通道上Flutter 的 MethodChannel 機(jī)制在鴻蒙上同樣存在但通道的“另一端”需要鴻蒙側(cè)原生代碼實(shí)現(xiàn)。如果三方庫內(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)的三方庫所以第一關(guān)其實(shí)是網(wǎng)絡(luò)層然后才是 JSON 序列化和平臺(tái)通道。如果一開始就把它當(dāng)成一個(gè)“純 Dart 包直接引入”后面會(huì)被各種運(yùn)行期問題抓瞎。1.3 為什么我選擇“替換底層、保留業(yè)務(wù)層”的方案當(dāng)時(shí)擺在我面前的有三條路。第一條路是直接升級(jí)到 servicestack 官方最新版本看它是否已經(jīng)支持鴻蒙。這個(gè)方法最省事但我查了一下當(dāng)時(shí)的版本并沒有針對(duì)鴻蒙做專門適配而且新版本升級(jí)可能會(huì)帶來 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)問題時(shí)只需要對(duì)著一個(gè)適配層排查不需要全局翻代碼。提示不是所有三方庫都適合“復(fù)制源碼”這個(gè)方案。servicestack 的源碼體量適中、依賴邊界清晰網(wǎng)絡(luò)層相對(duì)獨(dú)立所以 fork 成本可控。如果你的庫是幾千個(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)的新工程再把原來項(xiàng)目里的lib/目錄、資源文件、pubspec 依賴整體遷移過來。新工程會(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ù)適配。這一步聽起來簡單但容易被忽略的是包名和 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ù)層無感我建議不要把修改后的 servicestack 代碼直接提交到全局 SDK 目錄里而是放到自己的工程內(nèi)做一個(gè)本地包。在pubspec.yaml中通過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: [] } }注意千萬不要把cleartext-traffic-permitted直接設(shè)置成全局 true 然后發(fā)布到生產(chǎn)環(huán)境。正確做法是給指定的內(nèi)網(wǎng)測試域名配置單獨(dú)的白名單比如domain-config里寫cleartext-traffic-permitted為 true其他域名仍然強(qiáng)制 HTTPS。這不僅是安全要求也避免被應(yī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ì)被證書問題反復(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ù)端字段風(fēng)格。比如服務(wù)端返回user_name而 DTO 里定義的是userName就必須用JsonKey(name: user_name)做映射。我遇到過團(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ǎng)絡(luò)層拿到的字符串如果按默認(rèn)編碼處理中文字符容易亂碼。HTTP 響應(yīng)體必須明確使用 UTF-8 解碼并且在構(gòu)造請(qǐng)求體時(shí)也把 body 轉(zhuǎn)成 UTF-8 字節(jié)流。很多運(yùn)行期“能連上但是數(shù)據(jù)是亂碼”的問題都是這里沒有處理干凈。第二個(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ù)層也許還能正常跑。但真正的問題在發(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)來框架內(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ò)通道本地單測走 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)用同步”我理解包含兩層意思。一層是語義同步在 Android、iOS、鴻蒙三端調(diào)用同一個(gè)服務(wù)接口行為應(yīng)該一致。另一層是并發(fā)同步多個(gè)請(qǐng)求同時(shí)進(jìn)來時(shí)token 刷新、排隊(duì)順序不能亂。第一層相對(duì)容易。只要保證管道實(shí)現(xiàn)遵循同一個(gè)請(qǐng)求體構(gòu)造規(guī)則三端發(fā)出去的報(bào)文一致服務(wù)端返回的結(jié)果就不應(yīng)該有差異。真正麻煩的是第二層典型場景是 token 過期。很多團(tuán)隊(duì)的做法是在客戶端攔截器里處理 401收到 401 后先去后臺(tái)刷新 token刷新成功再重放原請(qǐng)求。這個(gè)過程在純 Dart 里寫沒問題但放到鴻蒙適配后如果請(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í)間可能誤殺長任務(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ò)誤必須透傳給業(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í)。排查鴻蒙適配問題時(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)證與問題排查4.1 編譯期問題依賴缺失與類型沖突鴻蒙化適配最常見的編譯錯(cuò)誤并不是 servicestack 本身的問題而是它的傳遞依賴在鴻蒙工程里沒有被正確解析。比如某個(gè)包依賴package:http但鴻蒙工程里只聲明了 servicestack沒有顯式聲明 http。這種錯(cuò)誤在 Android/iOS 上可能不會(huì)出現(xiàn)因?yàn)?Gradle/Xcode 會(huì)自動(dòng)處理部分依賴但鴻蒙 Flutter 工程的依賴解析更嚴(yá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)限。我見過不止一個(gè)人改了代碼但忘記在module.json5里補(bǔ)權(quán)限結(jié)果所有網(wǎng)絡(luò)請(qǐng)求全部失敗。第二步確認(rèn)服務(wù)端地址的證書。用瀏覽器能訪問不代表鴻蒙設(shè)備能訪問。如果服務(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)體也打印出來重點(diǎn)確認(rèn)返回的 JSON 編碼。若響應(yīng)體里中文是\uXXXX形式不是問題亂碼才是問題。4.3 數(shù)據(jù)不一致DTO 字段映射和時(shí)區(qū)問題服務(wù)調(diào)用通了之后最煩的是“字段名對(duì)不上”的問題。鴻蒙端拿到的 JSON 是created_at但 DTO 里聲明的是createdAt。如果漏寫JsonKey反序列化結(jié)果就是 null并且不會(huì)報(bào)編譯錯(cuò)誤。這種問題在聯(lián)調(diào)時(shí)非常隱蔽因?yàn)橹挥芯唧w業(yè)務(wù)邏輯訪問這個(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)換。三端同步測試時(shí)這個(gè)策略非常有效。4.4 典型問題速查表癥狀可能原因?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è)置過短區(qū)分連接超時(shí)和讀取超時(shí)自簽名證書請(qǐng)求失敗證書不在信任域配置鴻蒙網(wǎng)絡(luò)證書白名單同一接口三端行為不一致請(qǐng)求體或 headers 構(gòu)造不同統(tǒng)一走同一個(gè)本地包適配層這張表不是萬能藥但基本覆蓋了我在鴻蒙適配過程中遇到的 80% 問題可以作為自查清單使用。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)求比如列表頁一次性拉 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è)人能長期維護(hù)的。如果團(tuán)隊(duì)里還有其他人負(fù)責(zé)服務(wù)端和其他端最好把 DTO 生成、本地包構(gòu)建、適配層日志這三塊獨(dú)立分工。我后來把 DTO 生成腳本放進(jìn)了 CI每次服務(wù)端接口變更后自動(dòng)跑一遍生成新的 Dart 文件然后三端一起提交。這個(gè)流程讓“跨端服務(wù)調(diào)用同步”從口頭約束變成了自動(dòng)化約束?；貧w測試也要盡量復(fù)用現(xiàn)有 Flutter 測試用例。不要只測鴻蒙端Android 和 iOS 也要跑一遍確保本地包的替換沒有破壞原有行為。我的經(jīng)驗(yàn)是加一個(gè)環(huán)境變量切換適配層的“真實(shí)網(wǎng)絡(luò)/模擬網(wǎng)絡(luò)”實(shí)現(xiàn)能同時(shí)滿足單元測試和端到端聯(lián)調(diào)。5.3 最后分享一個(gè)小技巧排查鴻蒙適配問題時(shí)我習(xí)慣在本地包里加一個(gè)叫H-ADAPTER的自定義響應(yīng)頭。每次請(qǐng)求結(jié)束后如果響應(yīng)頭里帶了這個(gè)標(biāo)記說明請(qǐng)求確實(shí)走過了鴻蒙適配層而不是被某種緩存或替代邏輯攔截。這個(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í)重新翻工。