接過(guò)別人做了一半的 Flutter 項(xiàng)目是我這幾年最常遇到的場(chǎng)景之一。壓縮包解開(kāi)lib目錄下有二十多個(gè).dart文件散在根層級(jí)main.dart一千多行網(wǎng)絡(luò)請(qǐng)求、頁(yè)面跳轉(zhuǎn)、本地緩存、彈窗全擠在里面assets里圖片按1.png、2.png編號(hào)命名。它能跑但你讓我加一個(gè)新模塊我得先把那個(gè)一千行的文件從頭讀到尾。還有一個(gè)反向的場(chǎng)景自己從flutter create開(kāi)始做一個(gè)新項(xiàng)目第一天很爽第二十天開(kāi)始懷疑人生——不知道該把新寫(xiě)的文件放在哪同一個(gè)功能的相關(guān)代碼分居兩地刪一個(gè)舊功能要翻五個(gè)目錄確認(rèn)沒(méi)有殘留。這兩個(gè)場(chǎng)景指向同一個(gè)問(wèn)題一個(gè)完整的 Flutter 項(xiàng)目構(gòu)成它的不只是能編譯通過(guò)的代碼而是一套讓第二個(gè)人、第二十天之后的你自己還能順暢接手的文件組織秩序。目錄怎么分、根目錄那些不認(rèn)識(shí)的文件各自管什么、資源放哪、路由寫(xiě)在哪、測(cè)試和構(gòu)建配置怎么和主代碼對(duì)齊——這些看起來(lái)是工程規(guī)范實(shí)際上是每天都要打交道的東西。下面我按從項(xiàng)目根目錄往里走的順序把一套完整 Flutter 項(xiàng)目的構(gòu)成拆開(kāi)講一遍包括每個(gè)文件為什么存在、為什么這么分、以及我在實(shí)際搭建時(shí)踩過(guò)的那些坑。1. 拆開(kāi)一個(gè)能跑的工程根目錄里每個(gè)文件到底管什么執(zhí)行flutter create之后你不寫(xiě)一行代碼根目錄就已經(jīng)有十幾個(gè)條目了。新手最常見(jiàn)的處理方式是認(rèn)識(shí)的留著不認(rèn)識(shí)的不管.metadata、.gitignore、analysis_options.yaml這三個(gè)常年躺在那里沒(méi)人碰。但你一旦開(kāi)始接別人的項(xiàng)目、或者項(xiàng)目要在多臺(tái)機(jī)器和流水線上跑這些沒(méi)人碰的文件就會(huì)跳出來(lái)咬你一口。我先把它們的職責(zé)逐個(gè)說(shuō)清楚。1.1 pubspec.yaml 的三個(gè)身份依賴表、資源清單、約束聲明大部分人把pubspec.yaml當(dāng)成一個(gè)依賴列表來(lái)用需要什么包就flutter pub add一下完事。它實(shí)際承擔(dān)三件事而且后面兩件出問(wèn)題的概率更高。第一是依賴與版本約束。這里的關(guān)鍵不是寫(xiě)了哪些包而是版本約束的寫(xiě)法。^1.2.3這種 caret 寫(xiě)法允許次版本號(hào)浮動(dòng)對(duì)應(yīng)用項(xiàng)目來(lái)說(shuō)通常是可以接受的但如果你的項(xiàng)目依賴某個(gè)包的行為非常精確比如某個(gè)圖表庫(kù)的渲染細(xì)節(jié)、某個(gè)序列化庫(kù)對(duì) null 的處理把它寫(xiě)成1.2.3鎖定反而更安全。同時(shí)別忘了environment段里的 SDK 約束——這條決定了這個(gè)項(xiàng)目能被哪個(gè)版本的 Dart 工具鏈打開(kāi)團(tuán)隊(duì)里有人用舊版本 IDE 打不開(kāi)項(xiàng)目八成是這里卡住了。第二是資源聲明。flutter段下的assets列表決定了哪些文件會(huì)被打進(jìn)產(chǎn)物。這里有一個(gè)幾乎所有新手都踩過(guò)的坑聲明目錄時(shí)結(jié)尾的斜杠。寫(xiě)- assets/images/會(huì)把該目錄下的文件包含進(jìn)來(lái)寫(xiě)- assets/images只會(huì)包含這個(gè)路徑本身而它是個(gè)目錄所以實(shí)際上什么也沒(méi)包含進(jìn)去。區(qū)別只有一個(gè)字符報(bào)錯(cuò)信息還非常隱晦——運(yùn)行時(shí)圖片加載失敗控制臺(tái)給你一句Unable to load asset你回頭檢查文件名拼寫(xiě)檢查半小時(shí)。更麻煩的是這個(gè)列表不會(huì)遞歸assets/images/icons/下的文件必須單獨(dú)聲明一行很多人以為聲明了父目錄就自動(dòng)包含子目錄結(jié)果子目錄里的圖全部加載不出來(lái)。第三是項(xiàng)目元信息與構(gòu)建開(kāi)關(guān)。name決定了包名也決定了所有內(nèi)部 import 的前綴package:your_app/...改它的成本比想象中高version里的后面那串 build number 是提交應(yīng)用市場(chǎng)時(shí)的版本號(hào)依據(jù)很多人只改前面的語(yǔ)義化版本忘了后面那串。uses-material-design: true這條如果不寫(xiě)Icons.xxx系列圖標(biāo)全部渲染成空白方塊這是個(gè)非常經(jīng)典的排查點(diǎn)。字體聲明fonts段則在自定義字體場(chǎng)景下必不可少每個(gè) weight 都要單獨(dú)列一項(xiàng)漏一個(gè)就會(huì)導(dǎo)致FontWeight.w600渲染成默認(rèn)字重。提示pubspec.lock要提交到版本庫(kù)應(yīng)用項(xiàng)目但不要手動(dòng)編輯它。團(tuán)隊(duì)里兩個(gè)人pubspec.lock沖突時(shí)正確做法是取其中一份再重新flutter pub get而不是手工合并那些依賴樹(shù)。1.2 平臺(tái)殼工程 android/ios/web 的邊界在哪里android/、ios/、web/、macos/、linux/、windows/這六個(gè)目錄本質(zhì)上是同一個(gè) Dart 應(yīng)用在不同平臺(tái)上的殼。它們負(fù)責(zé)的是 Flutter 管不到的部分應(yīng)用圖標(biāo)、啟動(dòng)頁(yè)、權(quán)限聲明、簽名配置、原生插件注冊(cè)、深鏈配置。很多純 Flutter 開(kāi)發(fā)者對(duì)這幾個(gè)目錄有心理陰影看到build.gradle就想繞道走但只要理解它們的邊界日常需要?jiǎng)拥木湍敲磶滋?。Android 側(cè)的常改點(diǎn)集中在android/app/build.gradle現(xiàn)在新項(xiàng)目多半是build.gradle.ktsapplicationId、minSdkVersion、targetSdkVersion、簽名配置、以及buildTypes里的混淆開(kāi)關(guān)。權(quán)限相關(guān)的聲明在android/app/src/main/AndroidManifest.xml注意 Flutter 項(xiàng)目通常有三個(gè) Manifest 文件main、debug、profile網(wǎng)絡(luò)權(quán)限在 debug 版里默認(rèn)是開(kāi)著的release 版需要自己確認(rèn)——這是調(diào)試一切正常打包上線后接口全掛的頭號(hào)原因。iOS 側(cè)的關(guān)鍵文件是ios/Runner/Info.plist權(quán)限描述文案、URL Scheme、ATS 配置和ios/Podfile原生依賴的版本約束、平臺(tái)最低版本。Podfile里那行platform :ios, 12.0如果和某個(gè)插件要求的最低版本不匹配pod install就會(huì)失敗報(bào)錯(cuò)信息指向一堆你不認(rèn)識(shí)的原生庫(kù)。這種時(shí)候先看報(bào)錯(cuò)里那句required a higher minimum deployment target再去改這行數(shù)字比盲試快得多。Web 側(cè)相對(duì)簡(jiǎn)單web/index.html控制頁(yè)面外殼、title、以及首屏加載的占位內(nèi)容。這里有個(gè)細(xì)節(jié)Flutter Web 首次加載會(huì)有一段白屏引擎在下載在index.html里放一個(gè)簡(jiǎn)單的 loading 遮罩能顯著改善觀感成本卻極低。關(guān)于這些目錄要不要提交到版本庫(kù)——要。它們是項(xiàng)目的一部分尤其是原生側(cè)任何一次改動(dòng)圖標(biāo)、權(quán)限、簽名都必須被記錄否則換臺(tái)機(jī)器打包出來(lái)的產(chǎn)物就不一樣。1.3 analysis_options.yaml 與 .gitignore不出聲但決定項(xiàng)目壽命analysis_options.yaml這個(gè)文件的存在感極低但它決定了整個(gè)項(xiàng)目的代碼風(fēng)格是否統(tǒng)一。新項(xiàng)目默認(rèn)引入flutter_lints包包含一套官方推薦的規(guī)則集。我的建議是在項(xiàng)目第一天就把團(tuán)隊(duì)約定寫(xiě)進(jìn)去而不是等到代碼寫(xiě)了三個(gè)月再來(lái)批量修 lint——后者會(huì)產(chǎn)生一個(gè)幾百文件的巨型改動(dòng)評(píng)審沒(méi)法看最后往往不了了之。幾條我實(shí)際會(huì)打開(kāi)或關(guān)閉的規(guī)則prefer_const_constructors打開(kāi)對(duì)性能有實(shí)際收益且能培養(yǎng)習(xí)慣、avoid_print打開(kāi)防止調(diào)試用的 print 混進(jìn)生產(chǎn)代碼、prefer_single_quotes按團(tuán)隊(duì)習(xí)慣、always_specify_types建議關(guān)閉在 Dart 的強(qiáng)類型推斷下到處寫(xiě)類型反而是噪音。此外可以針對(duì)特定目錄做規(guī)則豁免比如生成的 l10n 文件、.g.dart生成文件用analyzer: exclude:把它們排除在分析之外能大幅減少分析器噪音。.gitignore的策略更簡(jiǎn)單粗暴build/、.dart_tool/、.flutter-plugins、*.iml這些必須忽略pubspec.lock必須提交。ios/Pods/和ios/.symlinks/也要忽略但ios/Podfile.lock建議提交它保證團(tuán)隊(duì)每個(gè)人的原生依賴版本一致。還有個(gè)小細(xì)節(jié).metadata這個(gè)文件記錄了項(xiàng)目創(chuàng)建時(shí)的工具鏈版本信息flutter命令會(huì)讀寫(xiě)它不要手動(dòng)編輯也不要輕易在沖突時(shí)刪除刪掉后某些工具會(huì)認(rèn)為這是一個(gè)非標(biāo)準(zhǔn)工程。2. lib 目錄的第一次分層為什么最后都會(huì)收斂到 feature-firstlib是整個(gè)項(xiàng)目的核心也是分層方案爭(zhēng)論最激烈的地方。我見(jiàn)過(guò)三種典型狀態(tài)一是所有文件平鋪在lib根下靠文件名區(qū)分二是按技術(shù)層切成models/、views/、services/、utils/幾大塊三是按業(yè)務(wù)功能切成features/login/、features/order/、features/profile/。第一種在文件超過(guò)三十個(gè)之后必然崩盤(pán)第二種能撐到中等規(guī)模但在業(yè)務(wù)交叉時(shí)開(kāi)始難受第三種是我目前所有新項(xiàng)目的默認(rèn)選擇。這一節(jié)講清楚為什么。2.1 main.dart 只該干三件事很多項(xiàng)目爛掉的起點(diǎn)就是main.dart。它一開(kāi)始只有五行然后有人加了個(gè)全局配置初始化有人加了個(gè)路由表有人把主題也放進(jìn)來(lái)半年后它變成一個(gè)八百行、import 了四十個(gè)文件、誰(shuí)都不敢動(dòng)的東西。我的做法是main.dart只保留三件事——綁定初始化、錯(cuò)誤捕獲、把控制權(quán)交給 bootstrap。具體來(lái)說(shuō)import package:flutter/material.dart; import bootstrap.dart; void main() async { WidgetsFlutterBinding.ensureInitialized(); await bootstrap(); }WidgetsFlutterBinding.ensureInitialized()這行必須在任何依賴平臺(tái)通道的操作之前調(diào)用否則會(huì)拋出Binding has not yet been initialized。本地?cái)?shù)據(jù)庫(kù)初始化、屏幕方向鎖定、SharedPreferences 預(yù)熱都屬于這一類它們?nèi)肯鲁恋絙ootstrap()里。bootstrap.dart則承擔(dān)注冊(cè)依賴 → 讀取配置 → 決定首屏 → runApp這條鏈路它是唯一知道全局裝配順序的文件。為什么要把這段拆出來(lái)因?yàn)樗蓽y(cè)。直接寫(xiě)在main()里的初始化流程單元測(cè)試沒(méi)法調(diào)用main會(huì)runApp測(cè)試環(huán)境里跑不起來(lái)。拆成bootstrap()之后你可以在集成測(cè)試?yán)锵扰芤槐檠b配、注入一個(gè) mock 的配置源再驗(yàn)證首屏路由的決策邏輯。這個(gè)收益在項(xiàng)目后期排查為什么冷啟動(dòng)偶發(fā)白屏這類問(wèn)題時(shí)體現(xiàn)得非常明顯。順帶一提app.dart它返回MaterialApp.router或MaterialApp只負(fù)責(zé)裝配主題、路由、本地化代理、全局 Provider 作用域。頁(yè)面的具體內(nèi)容一律不寫(xiě)在這里。這樣應(yīng)用級(jí)配置和頁(yè)面級(jí)實(shí)現(xiàn)的邊界就非常清晰改主題不會(huì)碰到業(yè)務(wù)代碼加頁(yè)面也不會(huì)碰應(yīng)用配置。2.2 按層切和按功能切的真實(shí)差異這兩種切法的差異不在于哪個(gè)更規(guī)范而在于你日常改一個(gè)需求時(shí)需要同時(shí)打開(kāi)幾個(gè)目錄。我用一張表說(shuō)明對(duì)比維度按技術(shù)層切models/views/services按功能切features/xxx新增一個(gè)功能在 3~5 個(gè)目錄各加文件在 1 個(gè)目錄內(nèi)加文件刪除一個(gè)功能需全局搜索確認(rèn)無(wú)殘留刪除整個(gè)目錄即可新人理解某個(gè)業(yè)務(wù)需跨目錄拼湊上下文打開(kāi)一個(gè)目錄即可通讀跨功能復(fù)用天然共享都在同一層需顯式下沉到 shared/core團(tuán)隊(duì)協(xié)作沖突多人同時(shí)改同一層目錄沖突集中在各自 feature適合規(guī)模小型、功能單一的 Demo中大型、多模塊并行的產(chǎn)品按層切的核心問(wèn)題是耦合度不可見(jiàn)。models/里有五十個(gè)模型你從目錄結(jié)構(gòu)上完全看不出OrderModel只被訂單模塊使用、而UserModel被八個(gè)模塊依賴等你想刪訂單模塊時(shí)才發(fā)現(xiàn)動(dòng)不了。按功能切之后一個(gè) feature 目錄內(nèi)的依賴是內(nèi)聚的跨 feature 的依賴必須走shared/或core/這個(gè)必須顯式走出去的動(dòng)作恰恰讓耦合變得可見(jiàn)可審計(jì)。按功能切的代價(jià)也很實(shí)在三個(gè)功能都需要一個(gè)帶圓角的頭像組件時(shí)你得決定它放哪。我的經(jīng)驗(yàn)是設(shè)一條明確的閾值——被兩個(gè)以上 feature 使用、且不含業(yè)務(wù)語(yǔ)義的組件下沉到shared/widgets/含業(yè)務(wù)語(yǔ)義的比如訂單狀態(tài)標(biāo)簽留在 feature 內(nèi)寧可復(fù)制一次。強(qiáng)行把帶業(yè)務(wù)的組件抽到公共層后期會(huì)因?yàn)椴煌?feature 的需求分化而變成一堆if-else開(kāi)關(guān)這比復(fù)制一份代碼的代價(jià)大得多。2.3 一份可以直接抄的目錄樹(shù)具體落地的目錄結(jié)構(gòu)長(zhǎng)這樣我把它當(dāng)模板用了好幾個(gè)項(xiàng)目改動(dòng)的都是細(xì)節(jié)lib/ ├── main.dart # 入口只做綁定與 bootstrap ├── bootstrap.dart # 依賴注冊(cè)、配置加載、首屏決策 ├── app.dart # MaterialApp.router裝配主題/路由/l10n ├── core/ # 與業(yè)務(wù)無(wú)關(guān)、全項(xiàng)目共享的能力 │ ├── constants/ # 常量、環(huán)境枚舉、存儲(chǔ) key │ ├── errors/ # 異常類型、失敗封裝 │ ├── network/ # Dio 客戶端、攔截器、基地址 │ ├── storage/ # 本地存儲(chǔ)封裝 │ ├── theme/ # 顏色、字體、組件主題 │ ├── router/ # 路由表與路由守衛(wèi) │ ├── utils/ # 無(wú)狀態(tài)工具函數(shù)、擴(kuò)展方法 │ └── di/ # 依賴注冊(cè)入口 ├── features/ │ ├── auth/ │ │ ├── data/ │ │ │ ├── datasources/ # 遠(yuǎn)端/本地?cái)?shù)據(jù)源 │ │ │ ├── models/ # DTO 與序列化 │ │ │ └── repositories/ # 倉(cāng)儲(chǔ)實(shí)現(xiàn) │ │ ├── domain/ │ │ │ ├── entities/ # 業(yè)務(wù)實(shí)體 │ │ │ ├── repositories/ # 倉(cāng)儲(chǔ)抽象 │ │ │ └── usecases/ # 用例 │ │ └── presentation/ │ │ ├── pages/ # 頁(yè)面 │ │ ├── widgets/ # 該功能專屬組件 │ │ └── state/ # 狀態(tài)控制器 │ └── home/ ├── shared/ │ ├── widgets/ # 跨功能復(fù)用的純 UI 組件 │ └── extensions/ # 跨功能復(fù)用的擴(kuò)展 └── l10n/ # arb 文件若開(kāi)啟國(guó)際化這里要強(qiáng)調(diào)domain 層不是必須的。如果你做的是一個(gè)數(shù)據(jù)展示型應(yīng)用業(yè)務(wù)邏輯就是拉接口、顯示列表硬套三層架構(gòu)會(huì)寫(xiě)出一堆只做轉(zhuǎn)發(fā)的 usecase純屬自找麻煩。我的判斷標(biāo)準(zhǔn)是這個(gè)功能有沒(méi)有需要獨(dú)立測(cè)試的業(yè)務(wù)規(guī)則——有就上 domain沒(méi)有就data presentation兩層保持輕量。架構(gòu)是為維護(hù)成本服務(wù)的不是為圖紙好看服務(wù)的。3. 狀態(tài)管理與依賴注入如何落在目錄結(jié)構(gòu)上選狀態(tài)管理框架的討論已經(jīng)夠多了我更關(guān)心的是另一個(gè)問(wèn)題選完之后代碼放在哪。同樣的 Riverpod 項(xiàng)目有人把所有 Provider 塞在一個(gè)providers.dart里有人每個(gè) feature 一個(gè)state/目錄六個(gè)月后的可維護(hù)性天差地別。目錄結(jié)構(gòu)其實(shí)是架構(gòu)的 X 光片看一眼就知道這個(gè)項(xiàng)目有沒(méi)有想清楚。3.1 目錄結(jié)構(gòu)其實(shí)是架構(gòu)的 X 光片判斷一個(gè) Flutter 項(xiàng)目的架構(gòu)成熟度我一般看三個(gè)信號(hào)。第一presentation/層里有沒(méi)有直接 import 網(wǎng)絡(luò)庫(kù)或數(shù)據(jù)庫(kù)包——如果有說(shuō)明數(shù)據(jù)獲取邏輯沒(méi)有被隔離UI 和 IO 焊死在一起改接口要改頁(yè)面。第二data/models/下的模型類有沒(méi)有混進(jìn)BuildContext、Widget之類的 UI 類型——如果有說(shuō)明序列化模型和視圖模型沒(méi)分開(kāi)后期接口字段一變就牽一發(fā)動(dòng)全身。第三domain/里有沒(méi)有 import Flutter 的任何包——理論上 domain 層應(yīng)該是純 Dart能在無(wú) UI 環(huán)境下跑測(cè)試。這三個(gè)信號(hào)都指向同一件事依賴方向是否單向。健康的依賴流向是presentation → domain ← dataUI 依賴抽象數(shù)據(jù)實(shí)現(xiàn)依賴抽象兩者互不知道對(duì)方。目錄結(jié)構(gòu)的作用就是讓這個(gè)方向在物理上可見(jiàn)——你從presentation/pages/login_page.dart里看到一行import ../../data/repositories/auth_repository_impl.dart立刻就知道這里越界了連代碼都不用讀。反過(guò)來(lái)說(shuō)如果目錄結(jié)構(gòu)只是把文件按名字分了類但依賴關(guān)系是網(wǎng)狀亂竄的那這個(gè)分層就是文件夾分層除了讓文件樹(shù)好看之外沒(méi)有任何約束力。真正的分層約束力來(lái)自代碼評(píng)審時(shí)的紅線以及把紅線寫(xiě)進(jìn)analysis_options.yaml或者團(tuán)隊(duì)文檔里。3.2 三種主流狀態(tài)管理的文件落位方式不同方案的落位習(xí)慣差別挺大我按自己實(shí)際用過(guò)的整理一下Provider / Riverpod 系核心是聲明與消費(fèi)分離。Provider 的聲明文件我建議放在 feature 內(nèi)的state/目錄一個(gè)文件聲明該 feature 的所有 Provider命名帶上 feature 前綴authStateProvider、homeListProvider?？?feature 共享的 Provider比如當(dāng)前登錄用戶放在core/di/或shared/providers/。Riverpod 用代碼生成時(shí)有.g.dart伴隨文件記得在.gitignore里做決策——我傾向于不提交生成文件但在 CI 里先跑dart run build_runner build保證產(chǎn)物一致。Bloc 系天然是一個(gè) feature 一組文件xxx_bloc.dart、xxx_event.dart、xxx_state.dart放在presentation/bloc/下即可。Bloc 的好處是文件命名強(qiáng)制暴露職責(zé)壞處是樣板代碼多一個(gè)小功能三四個(gè)文件。如果項(xiàng)目里 Bloc 數(shù)量超過(guò)二十個(gè)我建議做一層再抽象把重復(fù)的 loading/error 狀態(tài)收進(jìn)基類否則狀態(tài)類會(huì)膨脹得沒(méi)法看。setState 系別笑很多頁(yè)面確實(shí)只需要setState。這種情況下不需要任何狀態(tài)管理目錄把StatefulWidget寫(xiě)進(jìn)pages/即可。我見(jiàn)過(guò)為了架構(gòu)統(tǒng)一把一個(gè)純靜態(tài)展示頁(yè)也套上 Bloc 的三個(gè)文件管一個(gè)沒(méi)有狀態(tài)變化的頁(yè)面純屬浪費(fèi)。狀態(tài)管理只在有跨組件狀態(tài)共享需求時(shí)才引入這是原則。三種方案在目錄上的共同點(diǎn)是狀態(tài)控制器和頁(yè)面放在同一個(gè) feature 下不要全局集中。全局集中的后果是刪一個(gè)功能時(shí)控制器還留在那個(gè)大文件里沒(méi)人敢動(dòng)。3.3 get_it 與 ProviderScope注冊(cè)入口放在 bootstrap依賴注入的注冊(cè)入口只有一處放在core/di/由bootstrap()調(diào)用。這里有兩個(gè)高頻問(wèn)題。第一個(gè)是注冊(cè)順序。如果AuthRepository依賴ApiClient而ApiClient依賴AppConfig注冊(cè)時(shí)必須先AppConfig、再ApiClient、最后AuthRepository否則運(yùn)行時(shí)拋對(duì)象未注冊(cè)。項(xiàng)目大了以后這個(gè)順序很難維護(hù)我的做法是把注冊(cè)按模塊拆成registerCore()、registerAuth()、registerHome()幾個(gè)函數(shù)在bootstrap()里按模塊依賴順序調(diào)用并且每個(gè) feature 的注冊(cè)函數(shù)寫(xiě)在它自己的目錄下features/auth/di.dart由core/di匯總調(diào)用。這樣刪 feature 時(shí)注冊(cè)代碼也跟著目錄一起刪。第二個(gè)是懶加載與提前初始化。get_it的registerLazySingleton是第一次取用時(shí)才構(gòu)造registerSingleton是注冊(cè)時(shí)立刻構(gòu)造。對(duì)網(wǎng)絡(luò)客戶端這種需要讀配置的用懶加載對(duì)需要在啟動(dòng)階段就完成預(yù)熱的比如日志上報(bào)、崩潰捕獲用立即構(gòu)造并且await。這兩者混用會(huì)導(dǎo)致一個(gè)經(jīng)典現(xiàn)象某個(gè)服務(wù)在調(diào)試時(shí)正常、在冷啟動(dòng)首屏偶發(fā)報(bào)錯(cuò)因?yàn)槭灼另?yè)面取用它的時(shí)候它的依賴還沒(méi)就緒。Riverpod 的ProviderScope是另一套邏輯所有 override 在ProviderScope(overrides: [...])里聲明測(cè)試時(shí)用ProviderScope(overrides: [apiClientProvider.overrideWithValue(mock)])注入假實(shí)現(xiàn)。這個(gè)機(jī)制比 get_it 更適合測(cè)試因?yàn)樗亲饔糜蚧臏y(cè)試之間互不影響。我的項(xiàng)目里常見(jiàn)組合是get_it 管基礎(chǔ)設(shè)施網(wǎng)絡(luò)、存儲(chǔ)、日志Riverpod 管狀態(tài)兩套并存但職責(zé)不重疊。4. 資源、路由、本地化最容易堆在 lib 根目錄的三類東西這三類東西有個(gè)共同特點(diǎn)它們不屬于任何一個(gè)業(yè)務(wù)功能但又必須被業(yè)務(wù)功能引用。于是很多人圖省事在lib根目錄下建assets.dart、routes.dart、strings.dart三個(gè)大文件全部常量塞進(jìn)去。前三個(gè)月很爽半年后這三個(gè)文件各上千行每次改動(dòng)都提心吊膽。4.1 assets 的目錄規(guī)劃與 pubspec 聲明陷阱資源目錄我建議放在項(xiàng)目根和lib平級(jí)而不是lib里面——lib里的非 Dart 文件雖然能被打包但會(huì)讓代碼搜索變得嘈雜。標(biāo)準(zhǔn)結(jié)構(gòu)assets/ ├── images/ # 位圖資源 ├── icons/ # 圖標(biāo)svg 或 png ├── fonts/ # 字體文件 ├── animations/ # lottie / rive 動(dòng)畫(huà) └── config/ # 靜態(tài) json 配置pubspec.yaml的聲明有幾個(gè)必須注意的點(diǎn)我把它們和對(duì)應(yīng)的癥狀列成表寫(xiě)法實(shí)際效果典型癥狀- assets/images不含目錄下任何文件圖片全加載失敗- assets/images/含該目錄直屬文件不含子目錄子目錄圖片加載失敗- assets/fonts/且在fonts:段單獨(dú)聲明字體按 weight 注冊(cè)漏寫(xiě) weight 時(shí)字重回退默認(rèn)命名規(guī)范也值得定一下我習(xí)慣用前綴_用途_狀態(tài)的格式比如icon_nav_home_active.png、bg_login_gradient.png。純數(shù)字命名1.png、2.png的項(xiàng)目我基本可以斷定它沒(méi)有設(shè)計(jì)稿交接流程后續(xù)換皮膚時(shí)會(huì)非常痛苦。還有一個(gè)實(shí)操細(xì)節(jié)圖片資源體積。Flutter 打包不會(huì)自動(dòng)壓縮位圖一張 3MB 的背景圖會(huì)原樣進(jìn)包。我的習(xí)慣是加一步構(gòu)建前檢查超過(guò) 500KB 的位圖必須確認(rèn)是否有必要能轉(zhuǎn) WebP 的優(yōu)先轉(zhuǎn)Flutter 全平臺(tái)支持純色圖標(biāo)優(yōu)先用矢量flutter_svg。4.2 路由表集中化的收益路由有兩種寫(xiě)法命令式Navigator.push(context, MaterialPageRoute(...))和聲明式路由表。前者寫(xiě)起來(lái)快但三個(gè)月后你會(huì)收獲一堆散落在各頁(yè)面的跳轉(zhuǎn)代碼改一個(gè)頁(yè)面路徑要全局搜索。我現(xiàn)在的項(xiàng)目一律用集中路由表go_router或 Flutter 自帶的RouterAPI放在core/router/。集中路由表的收益具體有三條。第一路徑字符串只有一處定義用常量類包起來(lái)拼錯(cuò)會(huì)編譯報(bào)錯(cuò)而不是運(yùn)行時(shí) 404。第二路由守衛(wèi)有統(tǒng)一入口登錄態(tài)校驗(yàn)、權(quán)限攔截、深鏈參數(shù)解析都能在一個(gè)redirect回調(diào)里處理而不是每個(gè)頁(yè)面開(kāi)頭寫(xiě)一遍if (!loggedIn) return;。第三頁(yè)面結(jié)構(gòu)可見(jiàn)打開(kāi)路由文件就能看到整個(gè)應(yīng)用有哪些頁(yè)面、層級(jí)關(guān)系如何這對(duì)接手項(xiàng)目的人極其友好。路由文件我建議按層級(jí)拆而不是按數(shù)量拆router.dart只負(fù)責(zé)拼裝routes/auth_routes.dart、routes/home_routes.dart各自聲明本模塊的路由用ShellRoute或嵌套路由組合。這樣刪模塊時(shí)路由也跟著走。有一點(diǎn)必須提醒路由表里的路徑是外部契約。如果應(yīng)用有深鏈或者 Web 版本路徑一改外部鏈接就全廢了。所以路徑命名要在項(xiàng)目初期定好規(guī)范比如統(tǒng)一小寫(xiě)短橫線后期只增不改。4.3 l10n 的 arb 文件與代碼生成鏈路國(guó)際化這塊如果項(xiàng)目確定只做單語(yǔ)言可以完全跳過(guò)不要為了以后可能要而提前引入——它會(huì)給你帶來(lái)一堆AppLocalizations.of(context)!的空安全噪音。但如果確定要做多語(yǔ)言越早引入越好因?yàn)楹笃诎延簿幋a中文抽出來(lái)是個(gè)純體力活而且容易漏。標(biāo)準(zhǔn)鏈路是這樣l10n.yaml放在項(xiàng)目根配置 arb 目錄、輸出目錄、模板文件lib/l10n/app_en.arb、app_zh.arb存放鍵值執(zhí)行flutter gen-l10n新版 Flutter 在flutter run時(shí)會(huì)自動(dòng)跑生成AppLocalizations。生成文件我建議放在lib/l10n/generated/并加進(jìn)analysis_options.yaml的 exclude 列表避免 lint 噪音。arb 文件的組織有個(gè)經(jīng)驗(yàn)按功能拆文件不要一個(gè)大app_en.arb塞所有文案。auth_en.arb、home_en.arb分開(kāi)通過(guò)l10n.yaml的arb-dir配合多個(gè)模板文件組合或者干脆用一個(gè)文件但用前綴分區(qū)auth_loginTitle、home_greeting。前者更清晰后者更省事看團(tuán)隊(duì)規(guī)模選。鍵名的命名規(guī)范一定要在第一天定死loginTitle和login_title混用是后期最大的痛苦來(lái)源。5. test 目錄、構(gòu)建變體與流水線項(xiàng)目完整的最后一塊拼圖前面講的都是應(yīng)用本身怎么組織但一個(gè)完整的工程還包括它的外圍測(cè)試怎么寫(xiě)、多環(huán)境怎么切、自動(dòng)化怎么跑。這三塊在很多項(xiàng)目里是缺失的缺失的代價(jià)不會(huì)立刻顯現(xiàn)而是在第一次線上事故、第一次緊急熱修復(fù)時(shí)集中爆發(fā)。5.1 test 目錄與 lib 的鏡像關(guān)系test/目錄的結(jié)構(gòu)應(yīng)該鏡像lib/。lib/features/auth/domain/usecases/login_usecase.dart對(duì)應(yīng)的測(cè)試就是test/features/auth/domain/usecases/login_usecase_test.dart。這個(gè)鏡像關(guān)系的好處是找測(cè)試不用想——你知道代碼在哪就知道測(cè)試在哪。測(cè)試的層次我按投入產(chǎn)出比排個(gè)序domain 層的純邏輯測(cè)試性價(jià)比最高跑得快、不依賴環(huán)境、能覆蓋核心業(yè)務(wù)規(guī)則data 層的序列化測(cè)試次之重點(diǎn)測(cè)接口返回的畸形數(shù)據(jù)會(huì)不會(huì)導(dǎo)致崩潰widget 測(cè)試再次之只測(cè)關(guān)鍵的交互組件和狀態(tài)切換不要試圖用 widget 測(cè)試覆蓋所有 UI 細(xì)節(jié)維護(hù)成本會(huì)超過(guò)收益集成測(cè)試最少只覆蓋兩三條主流程登錄、下單、支付跑在真實(shí)設(shè)備或模擬器上。flutter create生成的test/widget_test.dart里那個(gè)計(jì)數(shù)器測(cè)試新項(xiàng)目第一件事就是刪掉或者替換掉它沒(méi)有任何價(jià)值留著只會(huì)讓人以為這個(gè)項(xiàng)目有測(cè)試。測(cè)試目錄里我還會(huì)單獨(dú)建test/helpers/放 mock 數(shù)據(jù)、測(cè)試用的 Provider 覆蓋、fake 實(shí)現(xiàn)避免每個(gè)測(cè)試文件重復(fù)造輪子。有個(gè)細(xì)節(jié)值得說(shuō)test/和integration_test/是兩個(gè)不同目錄。前者跑在 Dart VM 上速度快flutter test就能跑后者跑在設(shè)備上flutter test integration_test/需要連設(shè)備或模擬器。CI 里我一般只跑前者作為必過(guò)門(mén)禁后者放在 nightly 或者發(fā)布前的手動(dòng)觸發(fā)。5.2 flavors 與多環(huán)境配置的落地開(kāi)發(fā)、測(cè)試、生產(chǎn)三套環(huán)境配置不能硬編碼在代碼里。方案有兩層編譯期注入用--dart-define構(gòu)建期配置用 Flutter flavors。--dart-define的用法是flutter run --dart-defineAPI_BASE_URLhttps://xxx代碼里通過(guò)String.fromEnvironment(API_BASE_URL)讀取。它的優(yōu)點(diǎn)是簡(jiǎn)單、不需要改原生配置缺點(diǎn)是不能存在多個(gè)值同時(shí)在手每次切換要改命令而且不小心會(huì)把密鑰打進(jìn)產(chǎn)物所以密鑰絕對(duì)不要用 dart-define 傳那個(gè)不是加密的。flavors 則是在原生的構(gòu)建系統(tǒng)里定義多個(gè)變體。Android 側(cè)在build.gradle里配productFlavors { dev {} prod {} }可以給每個(gè)變體不同的applicationId后綴這樣開(kāi)發(fā)版和正式版能同時(shí)裝在一臺(tái)機(jī)器上這個(gè)體驗(yàn)提升非常明顯iOS 側(cè)配xcconfig文件。這條路配置成本高一些但能讓圖標(biāo)、應(yīng)用名、包名、簽名全部區(qū)分開(kāi)。我的實(shí)際做法是兩者結(jié)合flavor 區(qū)分為dev/prod兩套殼環(huán)境的細(xì)粒度配置接口地址、開(kāi)關(guān)用--dart-define或者config/dev.json靜態(tài)文件在啟動(dòng)時(shí)加載。配置讀取統(tǒng)一收在core/config/下暴露一個(gè)AppConfig對(duì)象其他代碼一律從它取絕不出現(xiàn)散落的String.fromEnvironment。5.3 CI 上的四條命令流水線不需要很復(fù)雜四條命令能兜住大部分問(wèn)題flutter pub get dart run build_runner build --delete-conflicting-outputs # 若使用代碼生成 flutter analyze --fatal-infos flutter testflutter analyze加--fatal-infos是關(guān)鍵默認(rèn)情況下 info 級(jí)別的 lint 不會(huì)讓命令失敗加上這個(gè)參數(shù)之后風(fēng)格問(wèn)題也會(huì)阻斷合并。這看起來(lái)很嚴(yán)格但它是讓 lint 規(guī)則真正生效的唯一辦法——只要有一條路可以繞過(guò)三個(gè)月后規(guī)則就形同虛設(shè)。構(gòu)建產(chǎn)物那一步flutter build apk --flavor prod --dart-define...。這里有個(gè)坑如果項(xiàng)目用了代碼生成freezed、json_serializable、riverpod_generator構(gòu)建機(jī)上必須先跑build_runner否則報(bào)找不到 xxx.g.dart。如果本地提交了生成文件要注意 CI 上重新生成的結(jié)果和提交的可能不一致生成器版本不同所以我的建議是統(tǒng)一不提交生成文件CI 每次重新生成環(huán)境一致性更好。6. 從零搭骨架的順序與幾個(gè)反復(fù)踩到的坑講了這么多構(gòu)成要素最后說(shuō)一下實(shí)際動(dòng)手時(shí)的順序。這個(gè)順序很重要因?yàn)橛行〇|西事后補(bǔ)成本極低有些東西事后改成本極高。6.1 我建議的搭建順序第一步定包名和應(yīng)用名。flutter create --org com.yourcompany --project-name your_app這一步定了之后applicationId、iOS Bundle ID、package:前綴全都跟著走。事后改包名的成本是重新創(chuàng)建一個(gè)項(xiàng)目再搬代碼非常痛苦。所以哪怕你還沒(méi)想好產(chǎn)品名也先把 org 和項(xiàng)目名想清楚。第二步配 lint 和目錄骨架。analysis_options.yaml先落地core/、features/、shared/三個(gè)空目錄建好哪怕里面只有一個(gè).gitkeep。骨架先立起來(lái)的意義在于后面每寫(xiě)一個(gè)文件都有明確去處不會(huì)因?yàn)闀簳r(shí)先放這而產(chǎn)生技術(shù)債。第三步配主題和路由。core/theme/里定顏色、字號(hào)、圓角、間距這幾個(gè)基礎(chǔ) tokencore/router/里定路由表和守衛(wèi)。這兩塊是全局性的定得越早后面頁(yè)面開(kāi)發(fā)越統(tǒng)一。第四步配網(wǎng)絡(luò)層和錯(cuò)誤模型。core/network/里封裝好客戶端、攔截器、統(tǒng)一錯(cuò)誤類型core/errors/定好失敗分類網(wǎng)絡(luò)失敗、業(yè)務(wù)失敗、解析失敗。這塊定得早各個(gè) feature 的數(shù)據(jù)層就能按統(tǒng)一模式寫(xiě)不會(huì)出現(xiàn)這個(gè)模塊用 try-catch 返回 null那個(gè)模塊拋異常的混亂。第五步再開(kāi)始寫(xiě)第一個(gè) feature。寫(xiě)完第一個(gè) feature 之后回頭檢查一次目錄結(jié)構(gòu)把不合適的地方調(diào)整掉。第一個(gè) feature 是最好的壓力測(cè)試它會(huì)把骨架的問(wèn)題全部暴露出來(lái)。此時(shí)改動(dòng)成本很低等到五個(gè) feature 寫(xiě)完再調(diào)整就是重構(gòu)了。第六步補(bǔ)測(cè)試和 CI。在只有一兩個(gè) feature 的時(shí)候把測(cè)試和流水線打通成本最低。等代碼量大了再補(bǔ)人會(huì)本能地抵觸。6.2 五個(gè)反復(fù)出現(xiàn)的坑坑一assets目錄聲明的斜杠。前面提過(guò)了但它值得再?gòu)?qiáng)調(diào)一次因?yàn)樗陌Y狀圖片加載失敗和原因少一個(gè)斜杠之間隔得太遠(yuǎn)新人平均要花半小時(shí)才能定位。我的做法是在pubspec.yaml里給資源聲明加注釋寫(xiě)明目錄必須帶結(jié)尾斜杠。坑二debug 能跑、release 崩。八成是混淆或者權(quán)限問(wèn)題。Android release 構(gòu)建默認(rèn)開(kāi)啟代碼壓縮某些反射式的序列化、原生插件的類名會(huì)被裁掉需要在proguard-rules.pro里保留。另外 release 版的AndroidManifest.xml不合并 debug 版里的網(wǎng)絡(luò)權(quán)限接口請(qǐng)求會(huì)靜默失敗。排查方法是先在本地跑一次flutter run --release把問(wèn)題暴露在開(kāi)發(fā)階段而不是發(fā)布階段?？尤?g.dart生成文件的沖突。多人協(xié)作時(shí)兩個(gè)人同時(shí)改了帶freezed的模型生成文件沖突出現(xiàn)在合并請(qǐng)求里。解決辦法就是前面說(shuō)的生成文件進(jìn).gitignoreCI 統(tǒng)一生成。切換過(guò)去的那一次要清一次緩存git rm --cached把所有已跟蹤的生成文件移除?？铀膄eature 之間的循環(huán)依賴。features/order引用了features/user的實(shí)體features/user又引用了features/order的模型Dart 編譯器不會(huì)直接報(bào)錯(cuò)但依賴關(guān)系變成了一團(tuán)亂麻。我的處理方式是出現(xiàn)第一個(gè)跨 feature 引用時(shí)就把被引用的實(shí)體下沉到domain/entities/或者shared/models/同時(shí)約定feature 之間不允許直接 import寫(xiě)進(jìn)評(píng)審清單?？游錶ib根目錄的文件不斷堆積。只要lib根下允許存在業(yè)務(wù)文件就一定會(huì)有人往里丟。我的做法是lib根下只留main.dart、app.dart、bootstrap.dart三個(gè)文件任何新增文件必須進(jìn)子目錄。這條規(guī)則簡(jiǎn)單粗暴但執(zhí)行成本極低效果立竿見(jiàn)影。我自己現(xiàn)在的習(xí)慣是新項(xiàng)目開(kāi)完flutter create的第一件事不是寫(xiě)代碼而是花一個(gè)小時(shí)把上面這套骨架搭完——lint、目錄、主題、路由、網(wǎng)絡(luò)層、配置讀取。這一個(gè)小時(shí)看起來(lái)沒(méi)有產(chǎn)出任何功能但它決定了這個(gè)項(xiàng)目在第三個(gè)月是能順暢加需求還是每加一個(gè)需求都要先做一次考古。踩過(guò)的坑多了之后會(huì)發(fā)現(xiàn)一個(gè)完整的 Flutter 項(xiàng)目代碼只是表面讓代碼能長(zhǎng)期被改動(dòng)的組織結(jié)構(gòu)才是底下那層真正支撐它的東西。