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