1. 為什么第一個實戰(zhàn)項目我選了一個信息流小應用而不是再寫一個 Todo我發(fā)現(xiàn)很多剛接觸 Flutter 的朋友學完基礎語法之后會卡在同一個地方教程里的每個知識點都看懂了Button、ListView、網(wǎng)絡請求都單獨跑通過但一說到做個自己的項目就完全不知道從哪下手。這個系列就是為了解決這個問題。這次實戰(zhàn)我給自己定的題目很簡單——做一個可用的信息流閱讀應用不做復雜特效不堆砌花哨交互但必須把真實 App 的骨架搭完整啟動頁、列表頁、詳情頁、網(wǎng)絡請求、加載狀態(tài)、錯誤處理、本地緩存、下拉刷新、上拉加載、打包配置。為什么選這個方向而不是再寫一個經(jīng)典 Todo原因很實際第一信息流是最常見、最不挑領域的應用形態(tài)。選它能保證讀者把代碼跑起來之后能立刻想象到這東西換個數(shù)據(jù)源就能變成新聞閱讀器、商品列表、開源項目導航。第二它天然覆蓋 Flutter 的核心知識點。列表渲染對應 ListView.builder網(wǎng)絡層對應 dio/http 封裝異步狀態(tài)對應 FutureBuilder以及后續(xù)的 Riverpod頁面跳轉(zhuǎn)對應命名路由本地緩存對應 shared_preferences 或文件存儲。做一遍等于把 Flutter 日常開發(fā)的高頻場景全部過了一遍。第三它足夠小。一個人一個周末能做出來不會因為工程太大半途而廢。我見過太多的學習路徑是每個組件學三遍項目一個都沒做完整過。這次我反過來——直接開干遇到什么補什么。提示這篇文章是項目實戰(zhàn)第一彈我會把從零到發(fā)布的全過程都寫出來。如果你還在猶豫我現(xiàn)在水平夠不夠先別糾結(jié)完整跟一遍你會發(fā)現(xiàn)自己能走通的路比想象中長。2. 開工前我先把目錄結(jié)構(gòu)和依賴一次定好2.1 為什么一開始就要定目錄結(jié)構(gòu)而不是寫到哪里算哪里很多初學者最喜歡在 main.dart 里一口氣寫五百行跑通了再說。這種做法在五十行以內(nèi)問題不大一旦項目超過兩三個頁面就會發(fā)現(xiàn)自己陷入改一個變量滿文件搜的困境。這次實戰(zhàn)從一開始我就把目錄按功能拆分目標很明確每個文件只干一件事通過命名快速定位。我先定義了一個標準分層結(jié)構(gòu)lib/ ├── main.dart # 入口負責初始化 ├── app.dart # 根組件負責主題和路由 ├── constants/ # 全局常量、API地址、存儲key ├── models/ # 數(shù)據(jù)模型 ├── services/ # 網(wǎng)絡請求、數(shù)據(jù)服務 ├── providers/ # 狀態(tài)管理控制器 ├── pages/ │ ├── home/ # 首頁相關 │ ├── detail/ # 詳情頁相關 │ └── splash/ # 啟動頁相關 └── widgets/ # 通用組件這樣拆分的直接收益是等代碼量過了兩千行你仍然能在十秒內(nèi)定位出一個組件或接口的位置。后續(xù)加頁面、加功能也只是往對應目錄里放文件不需要動其他模塊。2.2 依賴選型的思路依賴選型我遵循夠用、穩(wěn)定、生態(tài)好三個原則。下面是最終在 pubspec.yaml 里鎖定的關鍵依賴和選型理由依賴用途選型理由dio網(wǎng)絡請求攔截器機制成熟可統(tǒng)一處理日志、錯誤碼、token社區(qū)使用量最大riverpod狀態(tài)管理編譯期安全調(diào)試友好不需要 BuildContext 就能讀取狀態(tài)適合中大型項目shared_preferences本地鍵值存儲輕量適合存設置項和簡單緩存元數(shù)據(jù)cached_network_image網(wǎng)絡圖片緩存自帶內(nèi)存磁盤二級緩存列表圖片滾動時省流量不卡頓flutter_screenutil屏幕適配按設計稿尺寸自動換算省去不同機型手工調(diào)尺寸的麻煩intl日期格式化官方維護格式化相對時間很順手有一個容易忽略的點版本號我統(tǒng)一用了脫字符^限定大版本不鎖死具體小版本。這樣 pub get 的時候能拿到兼容范圍內(nèi)的最新版同時避免大版本升級帶來的破壞性變化。2.3 避免把依賴版本一直跟著最新走我知道有朋友習慣直接flutter pub add xxx然后一路 yes。跑是能跑但等過了兩三個月項目里可能會出現(xiàn)依賴間的兼容性沖突——你裝 A 的新版結(jié)果 B 的接口變了。我的做法是每次新增依賴之前先在 pub.dev 上看一眼它的更新時間、最后版本發(fā)布時間、以及 README 里有沒有提到 breaking change。穩(wěn)比新重要。3. 主題、路由、配置這幾塊決定了后面寫代碼的手感3.1 全局主題的配置方式一個信息流應用主題不需要復雜但配色和字體的統(tǒng)一是基本功。我在 constants 目錄下建了app_theme.dart用 Flutter 自帶的ThemeData把三套東西統(tǒng)一管理起來顏色主色、背景色、卡片色、文字主次色文本樣式標題字號、正文行高、輔助文字顏色通用組件樣式卡片圓角、陰影、AppBar 返回按鈕風格實際效果是頁面里幾乎不寫TextStyle(fontSize: 14)這種散裝樣式全走主題引用。后面想要換夜間模式或者調(diào)整品牌色只改一個文件全 App 生效。這里分享一個細節(jié)很多人會在MaterialApp里同時設置theme和darkTheme但在項目初期其實沒必要先保證一套主題足夠統(tǒng)一比提前做多皮膚更重要。多皮膚會引入大量邊界判斷前期只會拖慢進度。3.2 命名路由和頁面跳轉(zhuǎn)的取舍Flutter 里頁面跳轉(zhuǎn)有兩條路Navigator.push直接傳頁面實例或者用命名路由。我在這次項目里用了后者。routes: { /: (context) const SplashPage(), /home: (context) const HomePage(), /detail: (context) DetailPage(argument: argument), }命名路由的好處是跳轉(zhuǎn)時只需要拼字符串代碼里不會出現(xiàn)大量import頁面類的引用而且在需要做登錄攔截、深鏈跳轉(zhuǎn)時會方便很多。當然直接傳參數(shù)拼路由字符串有一個困擾——參數(shù)多了怎么辦我的處理方式是定義一個DetailArgument類把列表頁傳給詳情頁的所有字段打包成一個對象路由只傳這一個對象。這樣點進詳情頁時不會因為參數(shù)列表太長而眼瞎。3.3 全局配置獨立成文件接口地址、緩存過期時間、分頁大小、圖片占位圖這些環(huán)境級常量我集中放在了constants/app_config.dart里。用abstract final class包一層靜態(tài)常量后面切換到正式環(huán)境只需要改一個文件里的 API baseUrl。abstract final class AppConfig { static const String apiBaseUrl https://api.example.com; static const int pageSize 20; static const Duration cacheExpire Duration(days: 1); }這個習慣再往后延伸到多環(huán)境構(gòu)建時你只需要配合--dart-define就能實現(xiàn)測試、預發(fā)、正式三套環(huán)境的切換?，F(xiàn)在先把配置文件獨立出來等于給未來留了條后路。4. 數(shù)據(jù)模型和網(wǎng)絡層先把數(shù)據(jù)能不能順暢進來解決掉4.1 模型設計少一點手寫多一點規(guī)范信息流應用的核心數(shù)據(jù)無外乎一個文章摘要對象封面圖、標題、摘要、發(fā)布時間、內(nèi)容正文。我定義模型時遵循了一條很實用的原則模型的職責只有兩個——序列化和反序列化。所有業(yè)務邏輯都不寫在模型類里。class ArticleModel { final String id; final String title; final String summary; final String coverUrl; final String content; final DateTime publishedAt; const ArticleModel({ required this.id, required this.title, required this.summary, required this.coverUrl, required this.content, required this.publishedAt, }); factory ArticleModel.fromJson(MapString, dynamic json) { return ArticleModel( id: json[id] as String, title: json[title] as String, summary: json[summary] as String, coverUrl: json[cover_url] as String? ?? , content: json[content] as String? ?? , publishedAt: DateTime.tryParse(json[published_at] as String? ?? ) ?? DateTime.now(), ); } MapString, dynamic toJson() { return { id: id, title: title, summary: summary, cover_url: coverUrl, content: content, published_at: publishedAt.toIso8601String(), }; } }注意幾個細節(jié)coverUrl和content我都給了空字符串兜底而不是直接as String強轉(zhuǎn)因為真實后端返回的數(shù)據(jù)經(jīng)常缺字段空值處理不當會在渲染層崩掉publishedAt用了tryParse加兜底當前時間避免偶發(fā)的時間格式解析崩潰。4.2 dio 封裝把攔截器用到極致raw 的 dio 使用方式很簡單但一進入項目實戰(zhàn)我會立刻做一層封裝。不為了抽象而抽象而是為了三個非?，F(xiàn)實的需求統(tǒng)一設置超時時間和請求頭不用每個請求重復寫統(tǒng)一處理業(yè)務錯誤碼把請求成功但業(yè)務失敗和網(wǎng)絡異常分開統(tǒng)一打印日志接口調(diào)試的時候用得上class ApiClient { ApiClient._internal() { _dio Dio( BaseOptions( baseUrl: AppConfig.apiBaseUrl, connectTimeout: const Duration(seconds: 10), receiveTimeout: const Duration(seconds: 10), headers: {Accept: application/json}, ), ); _dio.interceptors.add( InterceptorsWrapper( onRequest: (options, handler) { // 這里可以統(tǒng)一加 token handler.next(options); }, onResponse: (response, handler) { final code response.data[code]; if (code ! 0) { handler.reject(DioException( requestOptions: response.requestOptions, message: response.data[message] ?? 業(yè)務錯誤, type: DioExceptionType.badResponse, )); return; } // 接口真正的數(shù)據(jù)藏在 data 里 response.data response.data[data]; handler.next(response); }, onError: (error, handler) { // 統(tǒng)一異常提示文案 handler.next(error); }, ), ); } static final ApiClient instance ApiClient._internal(); final Dio _dio; Dio get dio _dio; }這套封裝最常用的場景其實是后面調(diào)試階段——開代理抓包時需要加自定義 header改動只落在onRequest一處全 App 生效。我建議每個人在項目初期都做類似封裝后面省下的時間遠超前期花費的時間。4.3 數(shù)據(jù)服務層的另一個職責把數(shù)據(jù)喂給頁面之前先處理成頁面想要的形狀有些團隊會把 service 層做得很薄直接返回模型列表。我在這次項目里除了返回模型還封裝了一個重要的能力錯誤轉(zhuǎn)換成用戶可讀的提示。比如網(wǎng)絡斷開時Service 層會返回一個ApiException里面帶上messageUI 層拿到這個異常后直接展示在錯誤視圖上不用做二次判斷。class ArticleService { FutureListArticleModel fetchArticles({required int page, int pageSize AppConfig.pageSize}) async { try { final response await ApiClient.instance.dio.get( /articles, queryParameters: {page: page, page_size: pageSize}, ); final listJson response.data as Listdynamic; return listJson .map((e) ArticleModel.fromJson(e as MapString, dynamic)) .toList(); } on DioException catch (e) { throw ApiException( message: e.type DioExceptionType.connectionTimeout ? 網(wǎng)絡有點慢請稍后再試 : 加載失敗請檢查網(wǎng)絡, ); } } }這樣 UI 層永遠只面對兩種結(jié)果成功拿到模型列表或者拿到一個用戶能看懂的錯誤文案。判斷邏輯不散落在頁面各處長期維護的體驗會好很多。5. 狀態(tài)管理用 Riverpod但真正復雜的是頁面里怎么組織狀態(tài)5.1 為什么狀態(tài)管理從 Provider 換成了 Riverpod如果你早期用過 Flutter 官方的 Provider能明顯感覺到它簡單但也有幾個讓人別扭的痛點依賴 BuildContext 才能讀狀態(tài)測試的時候必須包一層 Provider 結(jié)構(gòu)。Riverpod 最大的改觀是Provider 聲明和組件樹解耦了任何地方都能通過 ref 讀到狀態(tài)代碼組織起來更接近依賴注入的思路。我在這次項目里用到的全局狀態(tài)只有兩類文章列表的異步加載狀態(tài)、以及當前的請求分頁參數(shù)?？雌饋聿欢嗟?Riverpod 在處理頁面銷毀后狀態(tài)要不要保留這個問題上非常順手。緩存的是 Provider 實例化的對象可以跨頁面保持這對詳情頁從列表頁讀取數(shù)據(jù)緩存很有用。5.2 AsyncNotifier 的寫法省掉所有手動 setState我實際上用的是AsyncNotifier因為它把加載中、成功、失敗三個狀態(tài)統(tǒng)一塞進了一個AsyncValue里。頁面里只需要看AsyncValue當前的快照來決定渲染加載動畫、錯誤視圖還是列表。class ArticleListNotifier extends AsyncNotifierListArticleModel { int _page 1; bool _hasMore true; override FutureListArticleModel build() async { return _fetchPage(); } FutureListArticleModel _fetchPage() async { final list await ref.read(articleServiceProvider).fetchArticles(page: _page); return list; } Futurevoid refresh() async { _page 1; _hasMore true; state const AsyncLoading(); state await AsyncValue.guard(_fetchPage); } Futurevoid loadMore() async { if (_hasMore) { final next await ref.read(articleServiceProvider).fetchArticles(page: _page 1); if (next.isEmpty) { _hasMore false; return; } state AsyncData([...?state.value ?? [], ...next]); _page; } } }注意refresh()里我用了AsyncValue.guard而不是自己寫 try-catch這是 Riverpod 提供的便捷方法能自動把異常包成AsyncErrorUI 層拿到它直接展示錯誤視圖方便得很。5.3 列表頁的 UI 組裝邊角狀態(tài)幾乎比主要邏輯還多一個信息流首頁正常狀態(tài)是列表除此之外還要處理空列表、初次加載中、刷新失敗、加載更多失敗、加載到底部等狀態(tài)。大多數(shù)人寫列表頁只放一個 ListView結(jié)果一旦網(wǎng)絡慢或斷網(wǎng)用戶體驗就很糟。我的做法是用AsyncValue.when分三路渲染再在error分支里區(qū)分是否已有歷史數(shù)據(jù)。如果當前state.value不為空說明是刷新失敗就保留列表并在頂部彈個 SnackBar如果state.value為空說明是首次加載失敗才展示全屏錯誤視圖。final articlesAsync ref.watch(articleListProvider); return articlesAsync.when( data: (articles) RefreshIndicator( onRefresh: () ref.read(articleListProvider.notifier).refresh(), child: ListView.builder( itemCount: articles.length 1, itemBuilder: (context, index) { if (index articles.length) { return const _NoMoreFooter(); } return ArticleCard(article: articles[index]); }, ), ), loading: () const Center(child: CircularProgressIndicator()), error: (err, stack) ErrorView(message: err.toString()), );這個拆分是真的實用上線后愿意把列表頁做完善的人和只跑通 Demo 的人頁面的皮實程度一眼就能看出來。6. 圖片、緩存、還有那個下拉刷新的隱藏坑6.1 圖片緩存不要手寫但要了解原理信息流頁面最容易卡的地方就是圖片。服務器返回的封面圖如果不做緩存每次滾出視野再滾回來就要重新下載基本等于災難。這次我用cached_network_image一行代碼接入CachedNetworkImage( imageUrl: article.coverUrl, fit: BoxFit.cover, placeholder: (context, url) const ShimmerBox(), errorWidget: (context, url, error) const Icon(Icons.broken_image), )它內(nèi)部會緩存到內(nèi)存和磁盤滾動回訪不再重新請求網(wǎng)絡。有一點必須提醒圖片占位圖不要用默認的灰色方塊我只是寫了一個極簡的ShimmerBox一個帶淺色背景的 Container就能讓首屏加載的觀感提升一個檔次。一個背景色循環(huán)動畫的封裝半天就能寫好收益很值。6.2 列表詳情頁的本地緩存策略我這次給詳情頁做了一個先展示緩存、再靜默更新的策略。具體實現(xiàn)進入詳情頁時先用文章的 id 去本地緩存找歷史記錄包括標題、內(nèi)容、時間如果有緩存立即展示緩存內(nèi)容同時發(fā)起網(wǎng)絡請求拿到最新數(shù)據(jù)后刷新頁面并更新緩存如果當前斷網(wǎng)就停在緩存頁面并提示當前顯示的是離線緩存這個策略的代碼核心非常簡單但能實打?qū)嵦嵘脩羧蹙W(wǎng)體驗。我用shared_preferences存緩存 JSON因為它是異步的、開銷小詳情頁數(shù)據(jù)這種單條對象用鍵值存儲足夠了。class DetailCacheService { static const String _keyPrefix detail_; final SharedPreferences _prefs; Futurevoid save(String articleId, ArticleModel article) async { await _prefs.setString(_keyPrefix articleId, jsonEncode(article.toJson())); } ArticleModel? read(String articleId) { final raw _prefs.getString(_keyPrefix articleId); if (raw null) return null; return ArticleModel.fromJson(jsonDecode(raw) as MapString, dynamic); } }如果換更大的項目建議改成數(shù)據(jù)庫或文件存儲一兩個頁面用 prefs 清爽夠用。6.3 下拉刷新的一個隱藏坑Flutter 的RefreshIndicator默認嵌套在ListView里很順暢但有一個常見 bug當列表內(nèi)容不滿一屏時手勢下拉經(jīng)常觸發(fā)不了刷新。原因是ListView默認只要內(nèi)容不到一屏就沒有足夠的滾動空間下拉手勢會被識別成普通滑動。解決辦法是給ListView加一個AlwaysScrollableScrollPhysics()ListView.builder( physics: const AlwaysScrollableScrollPhysics(), itemCount: articles.length 1, ... )這個小改動如果你不提前知道真機調(diào)試時會覺得明明寫了 RefreshIndicator 為什么拉不動特別浪費時間。7. 詳情頁、路由參數(shù)和返回刷新平時最容易忽略的聯(lián)動邏輯7.1 詳情頁布局與生命周期詳情頁的布局相對簡單頂部標題、作者和時間、封面大圖、正文文本。但有一個業(yè)務細節(jié)值得注意詳情頁可能會從列表頁進入也可能從收藏列表搜索頁進入。不管從哪進詳情頁都需要知道自己展示的是哪篇文章。我在前面提到過用一個DetailArgument打包參數(shù)class DetailArgument { final String articleId; final String title; final String coverUrl; const DetailArgument({ required this.articleId, this.title , this.coverUrl , }); }跳轉(zhuǎn)時Navigator.pushNamed(context, /detail, arguments: DetailArgument( articleId: article.id, title: article.title, coverUrl: article.coverUrl, ));詳情頁拿到articleId之后先裝飾性地展示傳入的標題和封面讓用戶感覺頁面秒開再實際請求正文內(nèi)容請求回來后再替換成完整數(shù)據(jù)。這比進入詳情頁轉(zhuǎn)圈等接口的體驗好太多。7.2 詳情頁返回列表頁時的狀態(tài)保留有時候用戶從列表點進詳情在詳情頁喜歡了某篇文章回到列表時希望能反映這個狀態(tài)。我這次把喜歡狀態(tài)放在 Riverpod 的全局 Provider 里而不是 DetailPage 的局部 State。這樣詳情頁更新了喜歡狀態(tài)列表項通過監(jiān)聽同一個 Provider 自動刷新。final favoriteIdsProvider StateProviderSetString((ref) String{});列表頁的 ArticleCard 用ref.watch(favoriteIdsProvider.select((v) v.contains(article.id)))來決定紅心是否點亮。返回列表時不用手動刷新任何東西狀態(tài)天然同步。這是狀態(tài)管理分離 UI 和邏輯之后最爽的一點。8. 調(diào)試技巧、打包配置、以及我在這個項目里最想分享的三句話8.1 日志與調(diào)試Flutter DevTools 是神器聯(lián)網(wǎng)應用調(diào)試時最剛需的是看請求參數(shù)和響應數(shù)據(jù)。dio 自帶的LogInterceptor在 debug 模式開起來就夠了if (!kReleaseMode) { _dio.interceptors.add(LogInterceptor(responseBody: true)); }真機調(diào)試時我最常用的工具是 Flutter DevTools 里的 Network 面板和 Inspector。前者能看請求耗時和數(shù)據(jù)體后者能實時查看 Widget 樹排查布局溢出非常直觀。開發(fā)時發(fā)現(xiàn)渲染問題先打開 Inspector 看父級約束一大半問題當場就能定位。8.2 Android 打包的配置要點先用flutter build apk --release打出安裝包前有幾步別漏確認ApplicationId改成自己的包名在AndroidManifest.xml里給發(fā)布版本加好網(wǎng)絡權(quán)限默認 debug 有release 可能沒開如果用了網(wǎng)絡明文地址Android 9 以上系統(tǒng)默認禁止明文 HTTP需要配置usesCleartextTraffictrue或者做網(wǎng)絡安全配置。一個小細節(jié)發(fā)布前把android/app/build.gradle里的minifyEnabled保持默認 false。Flutter 的 release 構(gòu)建體積本來不小開啟混淆并不能像原生那樣顯著瘦身反而可能引入 runtime 問題新手期沒必要碰。8.3 iOS 與 macOS 環(huán)境的注意點如果你主要在 Windows 上開發(fā)最后需要一臺 macOS 來打包 iOS 版本。這點我在項目開始就提醒了Flutter 項目跨端能力確實好但 Apple 平臺的構(gòu)建環(huán)節(jié)繞不開 macOS。提前確認好公司/團隊有沒有 Mac再決定最終交付哪幾個平臺。也可以在項目早期就把 iOS 目錄生成好避免后面想發(fā) iOS 還得回來補配置。提示我在實戰(zhàn)中踩過一個特別無腦的坑——用flutter create .時沒有先生成 iOS 目錄結(jié)果真正要發(fā) iOS 時補生成導致丟了一些平臺特有配置。項目創(chuàng)建時就把所有目標平臺的目錄一次性生成之后不想要可以刪但別等要的時候再補。8.4 三句實操心得第一項目實戰(zhàn)的進度不取決于你會多少而取決于你能不能把一個功能從網(wǎng)絡走到界面完整跑通。比起反復研究十幾個包不如把一兩條數(shù)據(jù)流徹底打通。第二處理異常時的體驗決定了別人愿不愿意持續(xù)用你的 App。網(wǎng)絡錯誤頁面不能只顯示一串英文異常至少提供重試按鈕加載失敗時要保留上次數(shù)據(jù)而不是直接白屏。這套邏輯在初期就要寫進列表頁模板里后面每個頁面都復用。第三從一開始就給工程留一層替換的余地。數(shù)據(jù)源的替換、接口的替換、ui 主題的替換分別隔離到 service、provider、theme 三層里。這個項目未來不管是接入真實后端、改成別的題材還是派生出新 App都會變得非常輕松。9. 關于這個項目的后續(xù)擴展信息流只是骨架到這里第一個實戰(zhàn)項目的核心流程已經(jīng)完整走通了啟動頁加載、首頁列表、網(wǎng)絡異常處理、詳情頁緩存、下拉刷新、返回聯(lián)動狀態(tài)、打包發(fā)布的前置配置。說實話這個骨架的復用性比我做之前預想的還要高。我真切建議你把這份代碼跑起來之后試著做三個方向的擴展把數(shù)據(jù)源從模擬接口換成本地 JSON 或真實后端給列表加上分類 tab加一個簡單的搜索頁。每一件事都不會動搖已經(jīng)搭好的架構(gòu)——這就是分模塊帶來的底氣。如果你碰到與文章里不同的報錯或現(xiàn)象大概率出在環(huán)境版本上。優(yōu)先確認三樣東西Flutter SDK 版本、dio 版本、Riverpod 版本。版本組合不同API 細節(jié)會有差異但整體思路完全一致。下次實戰(zhàn)我準備把登錄流程和 token 刷新、本地數(shù)據(jù)庫、通知推送這幾個更貼近商業(yè)項目的模塊拆開講到時候再繼續(xù)。