本章把邊界拆成四個方向，每個方向由一個實際踩過的 case 支撐。排查判準收成三問：這個變化是 provider 圖上某個節點的狀態變化嗎？在哪個容器的圖上？節點還活著嗎？

心智模型：配方、廚房、圖

provider 的全域宣告是配方——描述狀態怎麼建、怎麼變化；狀態本身活在容器（ProviderContainer／ProviderScope）裡，同一份配方在兩個容器裡煮出兩份互不相干的狀態。容器內的 provider 依 ref.watch 的依賴關係連成圖：節點是 provider 的狀態、邊是 watch 依賴，狀態變化沿著邊傳播、觸發下游重建。

reactive 的全部機制都建立在這張圖上。四個邊界各是圖的一個面向：圖屬於誰（空間）、圖上有什麼（涵蓋）、圖外的變化怎麼進來（接入）、節點活多久（時間）。

空間邊界：狀態屬於容器、不屬於宣告

main() 自建 ProviderContainer 觸發初始化、UI 跑在 runApp 的 ProviderScope 裡——兩個容器各持一份狀態，初始化改的是外部容器那份、UI 監聽的是 Scope 那份，App 永遠停在載入畫面。跨容器操作不報錯、只是安靜地作用在預期之外的地方，每段程式碼單獨看都正確。

判準：一個 App 裡活著的容器數量應該是一，每多一個都要能說出它為什麼必須隔離（測試的 ProviderContainer(overrides:) 是正當隔離）。全專案搜 ProviderContainer(、逐一問「它跟 UI 的 Scope 是同一個嗎」。確實需要在 runApp 前操作 provider 時（如讀取啟動設定），用 UncontrolledProviderScope 讓兩邊共用同一個容器。完整機制與修法：App 永遠卡在載入畫面。

涵蓋邊界：圖上只有 provider 的狀態

ref.watch(bookRepositoryProvider) 對單例 Provider<BookRepository> 建立的依賴永遠不觸發——這個 provider 的狀態是「repository 物件參考」、整個生命週期不變；SQLite 寫入了一百本書，物件參考一動不動。資料庫的變化不在圖上，於是刷新被推到圖外解決：導航返回點補 loadData()、EventBus 橋接、多個視圖各自維護 load 時機——補償刷新的出現就是涵蓋缺口的訊號。

判準：要讓畫面對某個變化反應，那個變化本身必須是圖上某個節點的狀態變化。修法方向一致——把資料變更做成一級節點（repository 補 stream 出口、StreamProvider 包成 provider），視圖回到純 ref.watch。三段補償演進與判讀訊號表：ref.watch 觀察的是 provider 圖、不是資料庫。

接入邊界：圖外的變化要立節點才進圖

把 repository 的 stream 接成圖上節點、是涵蓋缺口的結構性修法，接入處有自己的實作契約。三個問題各有一個會靜默失效的預設答案：訂閱模型（多個視圖同時聽、StreamController() 預設單訂閱、第二個訂閱者執行期 throw）、初始值（broadcast 不補送歷史、不處理的話畫面空到下一次寫入）、dispose（controller 的關閉責任跟著持有者走）。三個實作點的完整落地：StreamProvider 包 repository watch stream。

其中訂閱模型的選擇值得單獨記：StreamController() vs .broadcast() 是零成本差異，選限制更高的單訂閱版本、限制在只有一個訂閱者期間完全沉默、第二個訂閱者出現才爆。在零成本差異下把「會有多個觀察者」的領域先驗寫死成單訂閱，是設計缺陷、不是需求演化。單訂閱與 broadcast 的行為差異全表（buffer、pause、重新訂閱）：StreamController single vs broadcast。

時間邊界：節點的生命有兩頭界線

async 函式的每個 await 都是一個 gap：等待期間使用者可能離開頁面、Notifier 被 dispose，await 回來再碰 ref 就炸 UnmountedRefException。修法可機械化——每個 await 之後、第一次碰 ref 之前檢查 ref.mounted；而且刻意不抽成 helper：guard 的價值在「它在哪」，明確的檢查點讓 review 用眼睛掃就能驗證每個 gap 有沒有守。長流程、可離開的頁面（匯入、同步、批次處理）風險最高。完整機制與「評估必跑、可決定不重構」的技術債處置：await 回來的時候、頁面已經關了。

生命週期的另一頭是 build 期間：widget tree 建置中直接改 provider 狀態同樣是非法時機，觸發點要用 addPostFrameCallback 延到首幀之後。ref 的合法視窗兩頭都有界——await 之後可能太晚、build 之中太早。

排查判準

reactive 失靈時沿三問走，每一問對應一個邊界：

三問都過、reactive 仍不對時，回到接入層的實作契約查：訂閱模型（Bad state = 單訂閱撞多訂閱）、初始值（畫面空到下次寫入 = broadcast 沒補當前值）、mock 與真實實作的 stream 契約對齊。

邊界

本章處理 Riverpod 這個框架的 reactive 機制邊界，是實作層知識。「觀測能力該放哪一層」（契約歸 domain、機制歸 infrastructure、框架訂閱歸組裝層）是理論層的歸屬判準、與框架無關，見 觀測出口的職責三分；「事件與狀態流哪個當通知載體」的選擇也在理論層，見 domain event 與狀態流。本章假設載體與分層已定、只管 Riverpod 端怎麼把它接對。

下一步

圖的邊界都守住之後，剩下的深化方向各有一篇 case 可讀：容器與作用域的空間問題在 雙容器狀態脫節、涵蓋缺口的補償演進在 ref.watch 觀察的是 provider 圖、接入實作在 StreamProvider 包 repository watch stream 與 StreamController single vs broadcast、生命週期在 await 回來的時候、頁面已經關了。理論地基從 DDD 指南的讀側與觀測路線 進。

觸發場景：書庫管理 App 的 repository 原本是純 Future pull 介面，衍生視圖靠補償刷新（背景在 ref.watch 觀察的是 provider 圖、不是資料庫）。決策定向後要落地：repository 補 watchBooks() Stream 出口、用 StreamProvider 接進 Riverpod。 本篇範圍：落地時要答對的三個實作點，每一個的預設答案都會靜默失效。

分層落點

實作橫跨三層、每層只說自己那層的語言（歸屬判準的推導見 觀測出口的職責三分）：

契約層放介面預設實作，讓不支援觀測的實作類（測試替身、舊實作）不必立刻全部跟上：

1/// 提供書單變更的 Stream 出口，取代衍生視圖各自補償刷新。
2/// 約束：僅純 dart:async + domain entity，禁止框架型別進入此介面。
3Stream<List<Book>> watchBooks() {
4  throw UnimplementedError('watchBooks 未在此 repository 實作');
5}

實作點一：訂閱模型選 broadcast

因為書庫清單、統計頁、待補完列表都要同時觀察同一份資料，這個觀測出口有多個訂閱者。StreamController() 預設建構子是單訂閱、第二個訂閱者出現時直接 throw Bad state；這個選型的完整分析（含單訂閱在只有一個訂閱者期間完全沉默的潛伏機制）在 StreamController single vs broadcast。

1class SQLiteBookRepository implements BookRepository {
2  /// 全部寫入方法完成後透過此 controller emit 最新完整書單。
3  final StreamController<List<Book>> _booksController =
4      StreamController<List<Book>>.broadcast();
5
6  @override
7  Stream<List<Book>> watchBooks() => _booksController.stream;
8}

emit 集中在一個私有方法、掛在每個寫入方法尾端：

1Future<void> _emitCurrentBooks() async {
2  if (_booksController.isClosed) {
3    return; // repository 已 close：靜默略過，不讓通知失敗中斷寫入流程
4  }
5  final books = await getAllBooks();
6  if (!_booksController.isClosed) {
7    _booksController.add(books);
8  }
9}

兩個容易漏的細節：

1. 委派方法不重複 emit。介面上的相容性方法（saveBook 內部委派 addBook、deleteBookById 委派 deleteBook）走到底層寫入方法時已經 emit 過；在委派層再掛一次會讓一次寫入發兩次通知。emit 的掛載點是「實際執行寫入的方法集合」、不是「介面上所有看起來會寫入的方法」。
2. isClosed 要查兩次。getAllBooks() 是 async——查詢期間 repository 可能被 close，add 前不再確認就會對已關閉的 controller 拋例外，而且是從寫入方法的尾端拋出來、污染寫入本身的成功語意。

實作點二：初始值——broadcast 不補送歷史

broadcast stream 對「訂閱之前發生的事件」直接丟棄。衍生視圖訂閱 watchBooks() 的當下，上一次 emit 早就過去了——不處理初始值，畫面會停在空清單直到下一次寫入才有資料。

修法放在組裝層：StreamProvider 用 async* 先給當前值、再轉接後續變更。

1final watchBooksProvider = StreamProvider<List<Book>>((ref) async* {
2  final repository = ref.watch(bookRepositoryProvider);
3  yield await repository.getAllBooks(); // 訂閱當下：先 emit 當前完整書單
4  yield* repository.watchBooks();       // 之後：轉發 repository 的變更通知
5});

這個「當前值 + 後續變更」的組合就是 RxDart BehaviorSubject 內建的行為；純 dart:async 用兩行 yield 補上，不必為此引依賴。把初始值放組裝層而非機制層也有語意理由：repository 的 stream 誠實地只代表「變更」，「訂閱時要不要先看到當下」是消費端的呈現需求。

實作點三：dispose——關閉責任跟著 controller 的持有者

controller 的持有者是 repository，關閉責任就在 repository 的生命週期方法裡：

1Future<void> close() async {
2  await _booksController.close(); // 與資料庫連線一起釋放，避免 controller 洩漏
3  // ...既有的連線清理
4}

配合實作點一的 isClosed 防護，close 之後殘留的寫入呼叫會靜默略過通知、不會炸在使用者的操作路徑上。驗收面用三個測試釘住這組行為：寫入後 stream 收到最新書單、多訂閱者同時收到、close 後不再送出事件。

測試替身要同步這份契約

repository 有介面就有替身；替身漏掉 watchBooks() 會出現「production 正常、測試環境炸 UnimplementedError」或反過來的錯位。這次落地同步了三類替身、依「既有測試依不依賴多次 emit」給不同深度：

第三列是 Dart 特有的陷阱：mock 類別 implements 介面時不會繼承介面上的預設實作，介面加了新方法、所有 codegen mock 都要重新產生，否則消費新方法的測試在執行期才爆。mock 與真實實作的 stream 契約不對齊的後果（測試綠、production throw）在 StreamController single vs broadcast 的修復清單有完整展開。

三個必答題

把 repository stream 接給任何 reactive 框架前，三個問題各給一個明確答案：

本文範圍只涵蓋成功路徑。第四個問題——查詢失敗時 stream 該 addError 傳播還是吞掉——這裡沒有處理：_emitCurrentBooks 裡 getAllBooks() 拋例外時目前走 isClosed 防護的外圍、不會 addError，消費端收不到錯誤通知。失敗傳播的設計（要不要讓 StreamProvider 進 AsyncError 狀態、重試策略）是獨立主題；設計時要把 Riverpod 3 的預設行為算進去——失敗的 provider 會被自動重試（ProviderScope 的 retry 參數可關閉或調整間隔），addError 進到 provider 層的後果跟 2.x 不同。

介面歸屬的提醒收在最後：watchBooks() 的需求來自 Riverpod 消費端，但介面簽名只用 dart:async Stream 加 domain entity，所以它屬於 domain repository 介面——歸屬由介面用什麼語言表達決定，需求來自誰只決定介面該不該存在。Riverpod 型別止步於 watchBooksProvider、SQLite 型別止步於實作類，這條線就是三層各自的邊界。

下一步

補了觀測出口但還沒搞懂為什麼之前的導航補償和 EventBus 橋接不夠，先讀 ref.watch 觀察的是 provider 圖、不是資料庫。三層各自該放哪一層、判準怎麼來的，見 觀測出口的職責三分。單訂閱 vs broadcast 的完整選型分析在 StreamController single vs broadcast。觀測出口跟 domain event 各管什麼，見 domain event 與狀態流。

觸發場景：Flutter 書籍管理 App 的掃描器 ViewModel 用建構子接收三個 service、provider 工廠手動 new 具體類別傳進去；資源清理寫在自訂的 dispose() 方法裡 疑問來源：這個 dispose() 誰呼叫？盤點後答案是沒有人——UI 透過 provider 取用 Notifier、從頭到尾沒有拿到過需要它負責釋放的物件 整理目的：記下 Notifier「生與死都歸容器管」的機制、建構端與銷毀端各自的正確掛法 本文邊界：素材是該專案 v0.31.1 的 DI 一致性重構記錄；屬架構調整、不是崩潰事故——風險是結構性的（清理掛在無人呼叫的方法上）

機制：Notifier 的建構與銷毀都不歸使用者管

Riverpod 的 Notifier 生命週期兩頭都由容器控制。建構端：provider 工廠（NotifierProvider(ViewModel.new)）在容器第一次需要這個狀態時實例化 Notifier、接著呼叫 build()；銷毀端：容器判定節點該回收時（scope 銷毀、autoDispose 無人監聽）觸發 dispose 流程。使用者的程式碼在這兩頭都沒有控制點——UI 拿到的是 ref.watch(provider.notifier) 的引用、它不建構也不銷毀。

在這個前提下，兩種常見寫法都是跟容器搶生命週期控制權：

• 建構子注入依賴：工廠得手動 new 依賴傳進建構子——依賴的建構脫離 provider 圖，BookService() 直接實例化、不經過 bookServiceProvider，測試 override 摸不到它、依賴的依賴也斷鏈。
• 手寫 dispose() 方法：方法宣告在那裡、等一個呼叫者——但 Notifier 的持有者是容器、容器只認自己的 dispose 流程，UI 沒有任何一處會呼叫這個方法。掛在裡面的 Timer 取消、StreamSubscription 釋放，等於沒掛。

遷移：兩頭都收進 build()

 1// 之前：建構子注入 + 手寫 dispose
 2class IsbnScannerViewModel extends Notifier<IsbnScannerState> {
 3  IsbnScannerViewModel(this._bookService, this._cameraService, this._validator);
 4  final BookService _bookService;
 5  // ...
 6  void dispose() { _cancelScanning(); }   // 沒有呼叫者
 7}
 8
 9final isbnScannerViewModelProvider = NotifierProvider<IsbnScannerViewModel, IsbnScannerState>(
10  () => IsbnScannerViewModel(BookService(), CameraService(), IsbnValidationService()),
11);

 1// 之後：依賴在 build() 內 ref.watch、清理在 ref.onDispose 註冊
 2class IsbnScannerViewModel extends Notifier<IsbnScannerState> {
 3  late final BookService _bookService;
 4  late final CameraService _cameraService;
 5  late final IsbnValidationService _isbnValidationService;
 6
 7  @override
 8  IsbnScannerState build() {
 9    _bookService = ref.watch(bookServiceProvider);
10    _cameraService = ref.watch(cameraServiceProvider);
11    _isbnValidationService = ref.watch(isbnValidationServiceProvider);
12    ref.onDispose(_cancelScanning);   // 容器銷毀節點時執行
13    return IsbnScannerState.initial();
14  }
15}
16
17final isbnScannerViewModelProvider = NotifierProvider<IsbnScannerViewModel, IsbnScannerState>(
18  IsbnScannerViewModel.new,          // 工廠只負責實例化、不碰依賴
19);

改完之後的責任分佈：工廠回到 ViewModel.new 一行、依賴全部經 provider 圖取得（可 override、可追蹤）、清理掛在容器一定會走的 hook 上。ref.onDispose 跟手寫方法的差別就是「誰保證執行」——前者由容器的 dispose 流程保證、後者由一個不存在的呼叫者保證。

兩個附帶的工程紀律

這次重構的執行記錄留了兩件跟主題無關、但可轉移的事：

Pre-existing 失敗要用 baseline 重跑確認。改完後跑測試、一個多語系版型測試在小螢幕溢位失敗。判定它跟本次改動無關的方式是機械的：git stash 還原變更、在 baseline 重跑同一個測試、同樣失敗——確認是既有問題、記錄待追蹤、不混進本次範圍。「看起來無關」是猜測、baseline 重跑是證據。

Worktree 的 dart analyze 要先 pub get。在 git worktree 裡跑 dart analyze、它會向上解析到主 repo 的舊版 package_config 造成假錯誤；先在 worktree 內 flutter pub get 產生本地設定檔才能得到真結果。

判讀徵兆

• Notifier / ViewModel 類別裡有自訂的 dispose() 或 close() 方法——先找呼叫者，找不到就是本文的形態：清理掛在無人呼叫的方法上、改掛 ref.onDispose
• provider 工廠裡出現 new 具體類別（SomeService()）傳進建構子——依賴脫離 provider 圖、測試 override 失效，改成 build() 內 ref.watch
• 工廠寫法不是 ViewModel.new 一行——通常代表建構子還揹著依賴
• 改動後測試失敗、懷疑是既有問題——stash 還原跑 baseline、用同樣失敗證明、不用直覺判定

相關閱讀

• 生命週期的另一頭：await 回來的時候、頁面已經關了——本文管銷毀時的清理、那篇管銷毀後的 ref 使用
• provider 圖的整體邊界：Riverpod 的 reactive 邊界——依賴經 ref.watch 取得才在圖上、正是本文遷移的理由
• DI 的概念地基：Dependency Injection——建構與使用分成兩個責任、Notifier 的工廠與 build() 是這個分工的框架版

觸發場景：書庫管理 App 的資料管理頁顯示書庫統計（總書數、待補完書籍數）。從這頁進入搜尋或掃描流程加了書、返回後統計停在舊值；退回首頁再重新進入、數字才更新。 疑問來源：ViewModel 明明用 Riverpod、build() 裡也有 ref.watch，為什麼資料變了畫面不動？

核心認知：ref.watch 的觀察範圍

ref.watch 建立的是「這個 provider 的狀態變化時、重新執行我」的依賴——它觀察的是 provider 圖上的節點，範圍到 provider 的狀態為止。provider 背後的資料庫發生了什麼，不在這張圖上。

出問題的 ViewModel 依賴長這樣：

 1final bookRepositoryProvider = Provider<BookRepository>((ref) {
 2  return SQLiteBookRepository();
 3});
 4
 5class DataManagementViewModel extends Notifier<DataManagementState> {
 6  @override
 7  DataManagementState build() {
 8    // 這個 watch 只在 bookRepositoryProvider「換了一個 repository 實例」時觸發 rebuild
 9    final repository = ref.watch(bookRepositoryProvider);
10    // ...
11  }
12}

bookRepositoryProvider 是單例 Provider<BookRepository>：它的狀態是「那個 repository 物件本身」、整個 App 生命週期不會變。所以這個 ref.watch 建立的依賴永遠不會觸發——SQLite 寫入了一百本書，provider 的狀態（物件參考）一動不動。

畫面「有用 Riverpod」跟畫面「會對資料變更反應」是兩件事。要成立後者，「資料變更」本身必須是 provider 圖上的一個節點。

三段補償演進

這個缺口在專案裡先後被三種方式處理過。前兩段是補償——在 reactive 邊界外面用別的機制把刷新縫回來；第三段才把缺口本身補上。

第一段：導航返回點補償

最直覺的修法：既然「從加書流程返回」是統計過期的時刻，就在導航返回點重新載入。

1Future<void> _navigateAndRefresh(BuildContext context, String route) async {
2  await Navigator.pushNamed(context, route);
3  // pop 返回後重新載入統計
4  await ref.read(dataManagementViewModelProvider.notifier).loadData();
5}

它解掉了當下的 bug、也暴露了補償的形狀：涵蓋面靠枚舉。頁面上每個會導向「可能寫入資料的流程」的入口（匯入捷徑、搜尋、掃描）都要記得包這個 helper；漏一個入口就漏一條刷新路徑。而且它只涵蓋「本頁導航出去再回來」——資料在別的路徑變更（背景匯入、其他頁面操作）時，這頁照樣過期。

第二段：EventBus 橋接

第二段把既有的 domain event 系統接過來：用 StreamProvider 包 EventBus、ViewModel ref.listen 監聽，任何事件進來就 loadData()。

1final dataManagementEventStreamProvider = StreamProvider<DomainEvent>((ref) {
2  return ref.watch(eventBusProvider).on<DomainEvent>();
3});
4
5// ViewModel build() 內
6ref.listen(dataManagementEventStreamProvider, (_, __) => loadData());

這一段看起來把「資料變更」接進 provider 圖了——但接進來的節點是業務事件流、不是資料狀態。兩個新問題浮出來：

1. 涵蓋面仍靠枚舉，只是枚舉對象換了。導航補償要枚舉入口、事件橋接要枚舉「每條寫入路徑都有發事件」。實際盤點發現搜尋加書與掃描加書路徑沒有發布任何 domain event——這兩條路的刷新斷鏈，導航補償被迫保留、兩套機制並存。
2. domain event 被借用成 UI 刷新訊號。事件系統的設計語意是「記錄發生了什麼」（跨 domain 通知、日誌、審計）；拿它當刷新訊號後，「要不要發這個事件」開始被「某頁要不要刷新」綁架。監聽端也只能全事件監聽再考慮過濾——任何無關事件都觸發一次重新查詢。這條界線的完整推導在 domain event 與狀態流。

第三段：repository 補觀測出口

第三段修的是缺口本身：repository 介面新增 Stream<List<Book>> watchBooks()、實作在每個寫入方法尾端 emit 最新書單、DI 層用 StreamProvider 包裝成 provider 圖上的節點。

1final watchBooksProvider = StreamProvider<List<Book>>((ref) async* {
2  final repository = ref.watch(bookRepositoryProvider);
3  yield await repository.getAllBooks(); // 初始值：訂閱當下先給完整書單
4  yield* repository.watchBooks();       // 後續變更
5});

從此「資料變更」是 provider 圖上的一級節點：任何衍生視圖 ref.watch(watchBooksProvider) 就取得 reactive 更新，統計頁、書庫清單、待補完列表全部走同一條觀察路徑。涵蓋面從「枚舉入口／枚舉事件」變成「寫入方法的集合」——新增加書路徑時，寫入必然經過 repository 的寫入方法，emit 自動涵蓋，沒有「記得補」這個動作。實作細節（broadcast、初始值、dispose）在 StreamProvider 包 repository watch stream。

判準：補償刷新是缺口訊號

三段演進收斂成一條可操作的判讀：

每個訊號的修法都指向同一個方向：讓資料變更成為 provider 圖上的節點（StreamProvider 包 repository 的 stream 出口、或 Notifier 持有狀態），視圖回到純 ref.watch。輪詢式定時重抓（每 N 秒或 App resume 時重新查詢）是另一個合法選項，適用於新鮮度容忍度高、寫入頻率低的場景（管理後台的統計卡、低優先級的快取）。本文判準只處理「需要即時反應」的情境——多個視圖要看同一份即時資料、補償刷新已經散在各處時，輪詢的涵蓋面跟導航補償一樣靠枚舉維持，觀測出口才是結構性解。

介面歸屬：需求來自誰、不決定介面放哪

watchBooks() 的需求完全來自 presentation 層——是 Riverpod 想觀察資料變更、domain 自己沒有這個需要。直覺會說「誰需要就放誰那層」，把 Stream 出口做在 infrastructure 或 presentation 的某個 service 裡。

實際的歸屬判準是介面用什麼語言表達、不是需求來自誰：

Stream<List<Book>> watchBooks() 全句只用語言標準庫加 domain entity——它是 getAllBooks() 的 push 版本、放 domain repository 介面語意自然。需求從消費者出發決定介面該不該存在；介面放哪一層由表達語言決定。這條判準的完整推導（含機制層與組裝層的歸屬）在 觀測出口的職責三分。

下一步

• 契約／機制／組裝三層歸屬的完整判準：觀測出口的職責三分
• 事件與狀態流的語意分界（為什麼 EventBus 橋接是越權）：domain event 與狀態流
• watchBooks 落地的三個實作點（broadcast、初始值、dispose）：StreamProvider 包 repository watch stream
• provider 圖與容器的關係（狀態屬於容器、宣告只是配方）：App 永遠卡在載入畫面
• 同一事故的 UX 分析角度（happy-path-only 資料版）：U.C6 加書後返回不刷新統計

觸發場景：Flutter 書籍管理 App 的一個版本完成 113 張票、單元測試 100% 通過、收尾驗收通過；實機測試（Android 實體機）找出五個問題——其中三個是「功能做完了、使用者到不了」 疑問來源：規格審查、測試、版本收尾三道防線都在運作，為什麼五個問題全數漏網？ 整理目的：記下佔位實作讓測試綠燈的機制、反向追溯提案與 use case 文件的結果、以及修補時「規格層／測試層／發版層」的分層落點 本文邊界：素材是該專案 v0.38.1 修復批次的分析記錄；DDD 觀念層的判準另見 組裝層的可達性

五個問題、三種佔位、兩種平台差異

實機日誌與使用者操作對出五個問題，斷裂點分成兩組：

前三個是同一種形狀：功能單元全部存在、對應測試全部通過，斷的是「把功能接到入口」的那一段——DI 容器沒接上真實依賴、路由表沒指向真實頁面、按鈕沒接上導航。後兩個是另一種形狀：程式碼在 host 測試環境行為正確，在目標平台的語意下失效。

佔位讓測試綠燈的三層共振

單一防線失效不足以讓五個問題全數漏網，三層機制疊在一起才做到：

第一層在規格。use case 的成功保證寫的是功能行為——「成功匯入 X 本書籍」「實體書籍立即新增到書庫」——入口是否接上不在任何驗收條款裡。文件描述了使用者「點擊匯入按鈕」，但按鈕、路由、頁面這條鏈由誰負責接、接完長什麼樣，設計文件裡沒有一個字。

第二層在測試設計。從 use case 推導出的測試落在 unit 與 widget 層，用 ProviderScope(overrides: [...]) 注入 mock。override 是 Riverpod 給的正當測試 seam——它讓 domain 與 ViewModel 可以脫離 infrastructure 單獨驗證，這是分層架構承諾的兌現。代價在 seam 的另一面：override 換掉的正是 production 的組裝——組裝完沒完成，這套測試從頭到尾無人作證。

第三層在佔位本身。ComingSoon 頁是合法 widget、空 onPressed 是合法函式、throw 佔位的 provider 在 override 之下永遠不會被解析——佔位不觸發任何紅燈，測試斷言的是 mock 環境下的行為，佔位在測試的視野之外。三層疊加的結果：佔位通過了全部以 mock 為基礎的驗收，一路走到使用者手上。

override 的雙面性

override 同時是解藥跟盲點，而且是同一個機制。判讀訊號有一條可操作的分界——override 出現在個別測試裡是正當用法；整個專案找不到任何一個「無 override 環境解析 provider」的測試，才是組裝層裸奔的訊號。這個專案屬於後者：grep 全部測試，production 等效環境（真實路由表、零 override 的 ProviderScope）的案例數是零。mock 遮蔽的另一種病因——替身的協定語意與真實體不符、而非組裝缺席——見 192 個測試全過、實機全壞。

反向追溯：設計文件裡找不到「入口」

修復批次先做了一件事：拿五個問題反向追溯提案（PROP）、use case（UC）、規格（SPEC），確認每個問題在設計文件裡的對應條目長什麼樣。結果分成兩型：

追溯給出的結論：提案端寫滿了能力（tag 管理要有七個 CRUD）、use case 端寫滿了行為（使用者點擊匯入按鈕），追到「按鈕由誰放上畫面、路由由誰指向真頁面」時，兩類文件都翻不到答案——三個佔位問題全部落在這條縫裡。

前置條件被當成免責條款

追溯裡有一個細節要單獨展開。匯出功能的 use case 前置條件寫著「書庫中存在至少一本書」——這條前置條件已經標出了一個狀態分支：書庫是空的時候會怎樣？匯出按鈕在哪？沒有任何文件回答。實機上使用者的書庫是空的（開庫失敗的下游效應），畫面走了空狀態分支、匯出按鈕只存在於正常狀態分支，使用者的回報是「匯出功能不見了」。

前置條件的每一條都隱含一個「不滿足時會怎樣」的分支。把前置條件當成限定範圍的免責條款用，分支就無人設計；把它當成狀態枚舉的線索用，空狀態的畫面就會在設計期被逼著給出答案。

修補的分層落點

五個問題各自的修法：三個接線問題把真實依賴、真實頁面、導航 callback 接回入口；zone 警告把 binding 初始化移進 runZonedGuarded、與 runApp 收在同一個 zone；PRAGMA 失敗把 journal mode 設定改走 rawQuery（回傳結果列的查詢路徑）。修掉之外，修補按層放了三組防線，涵蓋範圍超出「把五個問題修掉」本身：

規格層：use case 文件補上「端到端可達性」成功保證條款（路由指向真實頁面、callback 已接線、provider 在無 override 環境可解析），並新增 use case 撰寫檢核：名詞可定位、路徑連通、狀態完備、環境差異——問句全文與判定方式見 組裝層的可達性。

測試層：區分行為測試與接線測試。行為測試維持 mock override（驗功能邏輯）；接線測試零 override、用真實路由表與真實依賴，只驗「port 有沒有插上 adapter」——本案是 local-first 單機 app、零 override 做得到全量；有遠端依賴的專案，零 override 的範圍是組裝路徑、最外圈 infrastructure 在邊界替換。修復前先補了十三個案例，其中十一個對目標行為斷言、修復前確定性紅燈——修復票以這批測試變綠為驗收點。

發版層：兩道互補的防線。佔位掃描進發版前置檢查——ComingSoon、UnimplementedError、空 onPressed 都是靜態可 grep 的，掃到就警告；實機冒煙清單補掃描構不到的部分——平台語意差異只有在目標平台執行才會暴露，清單的三層（啟動健康、use case happy path 走查、平台敏感點）在打 tag 前人工走一輪。

平台層的兩個問題（zone、PRAGMA）在設計文件與 host 測試都無處可防：Android execSQL 拒絕有回傳列的 SQL 這件事，sqflite 的 ffi 測試環境重現不出來。能做的是把「這步只有實機能驗」在設計期標記出來，讓冒煙清單有明確來源——漏網的位置從使用者手上移到發版前的清單上。

判準收束

• 綠燈的證言範圍：一個測試證明的是它執行環境下的行為。override 環境的綠燈對 production 組裝零證言——證言缺口要由接線測試補、而非把行為測試的 mock 拆掉。
• 功能完成的定義：從入口可達才算完成。「MVVM 全套完成」與「使用者用得到」之間隔著組裝層，這段距離在票務上要有自己的驗收條款。
• 佔位的紀律：佔位是合法的開發中間態，但它需要一個攔截點（發版掃描）。缺攔截點的佔位會通過所有以 mock 為基礎的驗收，終點站是使用者的回報。
• 缺口分類先於對策：這批修復裡，三個接線問題走規格條款加接線測試，zone 與 PRAGMA 走冒煙清單。對五個問題一律用「補測試」回應，補到的只是 host 環境的綠燈——zone 與 PRAGMA 要目標平台實際執行才暴露。

觸發場景：Flutter 書籍管理 App 的 Widget 測試基礎設施，設計階段產出 783 行的完整規格、實作 1101 行；下一個 Phase 的重構審查判定整套重做，刪到剩 193 行（-82.5%）、其中核心 helper 62 行 疑問來源：一套經過完整設計流程、有架構圖有依賴規範的基礎設施，為什麼是該刪的？審查依據是什麼？ 整理目的：把這次刪除拆成三種可辨識的過度工程形態、以及「寫測試工具之前」的檢查點 本文邊界：素材是該專案 v0.7.0 的 Phase 1 設計文件與 Phase 4 重構記錄——同一個東西的誕生與死亡、對照完整

被刪掉的是什麼

四個檔案、一個目錄：

取代它們的是 62 行的 helper 加標準 Riverpod 模式：

1WidgetTestHelper.createFullTestApp(
2  const LibraryDisplayPage(),
3  [libraryDisplayViewModelProvider.overrideWith(() =>
4      LibraryDisplayViewModelForTest(LibraryDisplayState()))],
5);

功能沒有變少——變少的是「為了用這套工具而要學的東西」。

形態一：重新發明框架已有的輪子

整套 Mock Provider 架構要解的問題——「測試時把真實依賴換成受控替身」——Riverpod 內建的 overrideWith 一行就是官方解。389 行的 Mock 架構等於是在框架旁邊蓋了一座平行的依賴注入系統，每個新測試都得學它、每次框架升級它都可能斷。

寫測試工具前的第一個檢查點就是這條：先問「這個框架 / 生態的標準做法是什麼」、再問「標準做法哪裡不夠」。找不出第二題的答案，自建工具的每一行都是純負債——它不是產品碼、卻要跟產品碼一樣被維護。

形態二：解決不存在的問題

388 行的多語系測試 helper 是精緻度的巔峰：Mutex 狀態鎖、記憶體洩漏防護機制、三類版面溢位檢測（RenderFlex、文字截斷、螢幕邊界）。每個機能單獨看都「很完備」——但當時的 Widget 測試需求是「讓測試能編譯、能跑」，多語系切換測試根本還不在任何 use case 裡。重構記錄的判語：「解決一個不存在的問題」。

這個形態跟異步查詢系統的第一輪膨脹同構——設計期用「系統該有的完備性」取代「操作需要的能力」。測試工具的完備性想像還更容易失控，因為它不受產品需求審查：沒有 PM 會問「為什麼測試 helper 需要 Mutex」。

形態三：mock 了不需要 mock 的東西、放在不該放的地方

兩個架構層級的錯：

MockBook 取代真 domain entity。 mock 的正當對象是有副作用、慢、或不可控的依賴（網路、資料庫、時間）；Book 是純資料物件、建構它比 mock 它便宜——真 entity 直接用就好。mock 純物件的代價是雙重維護：entity 加欄位、MockBook 也要加，兩者漂移時測試守的是一個不存在的形狀。

mock 放在 lib/ 而不是 test/。 測試碼進了生產依賴圖——而且這不是手滑，Phase 1 設計文件把 test/ → lib/mocks/ → lib/core/ 畫成正式的單向依賴規範。方向本身「乾淨」，但前提就錯了：lib/ 的語意是「會被打包進 App 的程式碼」，mock 不屬於那裡。

精緻的設計文件不是價值證明

這個 case 最值得記的一點：被刪掉的系統有 783 行設計文件、有架構圖、有依賴方向規範、有驗收條件——整個設計流程認真地規劃了一個不需要存在的東西。精緻度讓它更難殺：看起來像紮實的工程產出，審查者要先推翻「這麼認真的東西應該有價值」的直覺才下得了手。

同專案的另一個記錄（同步 domain 架構評分 A- 但不能編譯）是同一課的另一面：評價「做得好不好」之前，先評價「該不該做」。Phase 4 重構記錄把這個順序寫成了方法論建議——「優先考慮刪除：先問『這個真的需要嗎？』再問『如何改善？』」。

判讀徵兆

• mock 類別 mock 的是純資料物件（entity / value object）——真物件更便宜、直接用
• 測試 helper 出現 framework 級機能（並發鎖、洩漏防護、自製 logger）——問是哪個測試需求逼出來的、指不出來就是完備性想像
• lib/ 底下出現 mocks/ 或 test 字樣的目錄——測試碼在生產依賴圖裡
• helper 的行數超過用它的測試——工具比問題大
• 「用這套工具寫測試」需要先讀文件——標準模式的優勢正是新人零學習成本

相關閱讀

• 同機制的產品側版本：異步查詢系統的過度設計震盪——設計期完備性想像的兩個現場
• mock 該放哪、多少才夠：192 個測試全過、實機全壞——那篇談 mock 過多遮蔽真實、本文談 mock 系統本身過重，同一個「mock 是手段不是資產」的兩面
• 原則層：#77「現在不決定」是合法選項——多語系測試工具的正確處置是等需求出現、不是先蓋起來放

觸發場景：Flutter App 啟動後永遠停在載入畫面。初始化的 provider 狀態永遠是 notStarted、初始化流程從未執行——但初始化邏輯的單元測試是綠的 疑問來源：main() 裡明明呼叫了 initialize()，為什麼 UI 看到的狀態完全沒動？ 整理目的：記下 Riverpod「provider 宣告全域、狀態屬於容器」的心智模型、以及跨容器操作靜默失效的機制 本文邊界：素材是該專案 v0.10.1 的修復記錄（Riverpod 2.x 時期）；「配方 vs 廚房」的心智模型跨版本成立

症狀與現場

出問題的 main() 長這樣：

1final container = ProviderContainer();
2container.read(appInitializationProvider.notifier).initialize();  // 對外部容器操作
3
4runApp(ProviderScope(child: BookLibraryApp()));                    // UI 在另一個容器裡

兩行各自都「正確」：initialize() 真的被呼叫、真的執行完；ProviderScope 裡的 UI 真的在監聽 appInitializationProvider。但 UI 的狀態永遠是 notStarted——因為它們操作的是兩份不同的狀態。

機制：provider 宣告是配方、容器持有狀態

Riverpod 的 provider 宣告寫在全域：

1final appInitializationProvider = NotifierProvider<...>(...);

全域宣告製造了「狀態也是全域」的錯覺。實際上這個全域物件只是配方——描述「這個狀態怎麼建、怎麼變化」。狀態本身活在容器裡：ProviderContainer() 建一個容器、ProviderScope 在 widget tree 裡也建一個容器（它內部就是包了一個 container）。同一份配方在兩個容器裡各煮出一份互不相干的狀態。

於是 container.read(...).initialize() 改的是外部容器那份狀態——改成功了、沒有任何錯誤；UI 監聽的是 Scope 容器那份——從頭到尾沒人動它。跨容器操作不會報錯、它只是安靜地作用在你以為之外的地方，這是這類 bug 難查的原因：每一段程式碼單獨看都在正常工作。

修法：把觸發點移進唯一的容器

修復選的方案是移除外部容器、讓初始化在 widget tree 內觸發：

 1// main.dart：只負責 runApp
 2void main() async {
 3  WidgetsFlutterBinding.ensureInitialized();
 4  runApp(const ProviderScope(child: BookLibraryApp()));
 5}
 6
 7// _AppWrapper：偵測未初始化、在首幀後觸發
 8if (initState.status == AppInitializationStatus.notStarted) {
 9  WidgetsBinding.instance.addPostFrameCallback((_) {
10    ref.read(appInitializationProvider.notifier).initialize();
11  });
12}

兩個細節。addPostFrameCallback 把觸發延到首幀之後——build 期間直接改 provider 狀態是另一類錯誤（widget tree 建置中修改 provider 會炸）。觸發條件掛在 notStarted 狀態上，讓「誰負責啟動初始化」有唯一答案：看到未初始化的第一個 wrapper。

如果情境真的需要在 runApp 之前操作 provider（例如讀取啟動設定），正解是讓兩邊共用同一個容器——自建的 container 透過 UncontrolledProviderScope 傳進 widget tree，而不是各建一個。判準收成一句：一個 App 裡活著的容器數量應該是一、每多一個都要能說出它為什麼必須隔離（測試裡的 ProviderContainer(overrides: ...) 就是正當的隔離）。

為什麼單元測試沒抓到

初始化 Notifier 的單元測試是綠的——它驗證「這份配方煮出來的狀態會正確走完初始化」，在測試自己的容器裡完全成立。bug 不在配方、在佈線：兩個容器的存在是 main() 的組裝問題，單元測試的邊界不含組裝。這類 bug 的守備範圍在整合層——一條「啟動 App、斷言最終離開載入畫面」的 widget 測試就能攔住。修復記錄還留了一個測試環境的絆腳石：初始化流程裡的 Future.delayed 計時器跟 widget test 的 pending-timer 檢查不相容，這也是當時整合測試缺席的原因之一——計時器類的延遲在可測性上要優先考慮可注入的 clock 或可等待的 Future。

判讀徵兆

• 「狀態改了但 UI 沒反應」且雙方程式碼各自看都正確——先數容器：全專案搜 ProviderContainer(，每一個實例都問「它跟 UI 的 Scope 是同一個嗎」
• main() 裡出現 ProviderContainer() 又出現 ProviderScope——幾乎就是本文的 bug 形態
• provider 狀態「永遠是初始值」——比「狀態錯誤」更指向無人操作這份實例、該查操作方作用在哪個容器

相關閱讀

• 同屬狀態管理框架的跨界 bug：Dart test 的跨檔案 GetX 狀態污染——GetX 的問題是全域單例讓狀態「太共享」、Riverpod 這裡是容器隔離讓狀態「太不共享」，兩篇合看是狀態作用域的兩個失敗方向
• 靜默失效的同構：#221 檢查規則的作用域要顯式列舉——作用在錯的作用域、不產生任何錯誤訊號，症狀在遠處浮現

觸發場景：Flutter 書籍管理 App 的批量匯入——一條會跑很久的 async 流程。使用者中途離開頁面，流程裡下一個 state = ... 拋出 UnmountedRefException：ViewModel 已經被 dispose、ref 不能再用 疑問來源：修復加了 16 個 if (!ref.mounted) return;——這麼多重複的檢查、不該抽成一個 helper 嗎？重構評估的答案是不該，為什麼？ 整理目的：記下 async gap 的生命週期機制、檢查點的擺放規則、以及「重複但刻意不抽象」的判斷 本文邊界：素材是該專案 v0.25.1 的修復與 Phase 4 重構評估記錄；ref.mounted 是 Riverpod 的 API、「await 前後是兩個世界」的機制跨框架成立

機制：await 前後是兩個世界

同步程式碼裡「this 活著」是全程成立的前提；async 函式裡這個前提在每個 await 處斷開一次。批量匯入的流程長這樣：逐本書處理、每本有儲存的 await、批次間有讓出控制權的 await——每一個 await 都把控制權交還 event loop，而 event loop 上可能正排著「使用者按了返回、頁面 dispose、Notifier 跟著 dispose」。

await 回來之後的程式碼，跑在一個「自己可能已經死了」的世界裡。讀區域變數沒事、但碰 ref（寫 state、讀 provider）就是對已釋放資源的操作——Riverpod 用 UnmountedRefException 把這個錯誤變成显式的炸點（比靜默寫入無人監聽的狀態誠實）。修法就是在每次 await 之後、要碰 ref 之前重新確認世界還在：

1await _saveBook(book);
2if (!ref.mounted) return;          // await 後、碰 ref 前
3state = state.copyWith(processedBooks: progress.processed);

檢查點的擺放規則可以機械化：每個 await 之後、第一次碰 ref 之前。這次修復落了 16 個檢查點——對應這條流程的 16 個 async gap，漏任何一個就留下一條「使用者恰好在那個瞬間離開」的崩潰路徑。

刻意不抽象：重複、但每個重複都有座標

16 個一模一樣的 if (!ref.mounted) return; 天然引來「抽成 helper」的重構衝動。Phase 4 評估把它列為候選、然後否決，理由三條照錄：

1. 抽取為 helper 會增加複雜度；2. 明確的檢查點有助於程式碼審查；3. 這是 Flutter 社群的推薦實踐。

第二條是核心。這種 guard 的價值不在「做了什麼」（一行 return）、在「它在哪」——review 一段 async 流程時，審查的問題是「每個 gap 之後有沒有守」，明確的檢查點讓這件事用眼睛掃就能驗證；包進 helper（或用 zone、攔截器之類的魔法）之後，「哪個 gap 有守」變成要追實作才知道。重複的成本（16 行樣板）換明確性的收益，這筆帳在 guard 這類「位置即語意」的程式碼上是划算的——跟 DRY 在別處的正確性不矛盾：那裡重複的是行為（兩份 API 實作會分歧）、這裡重複的是哨位（每個位置本來就該有一個）。

第三條也值得停一秒：社群標準模式的地位跟 mock 基礎設施那篇的教訓相通——生態已收斂的做法、自建「更優雅」的抽象前先想清楚要解的是誰的問題。

評估必跑、可決定不重構

這份記錄的第二個看點是流程形態。Phase 4 重構評估必須執行、但結論可以是「不重構」：本次評分 B、識別出兩筆技術債（88 行的 _executeImport、重複五次的錯誤處理模式）、決策是「品質達標、債務記錄、排入下個重構週期」。

這個形態把兩件常被混在一起的事分開了：評估的義務（每次改動後都要看一眼品質）跟執行的判斷（現在修還是排程修）。混在一起的版本要嘛「評估完就得修」（每張票膨脹）、要嘛「不修就不評估」（債務靜默累積）。而這裡的技術債記錄不是垃圾桶——TD-012（88 行函式）在下一個版本真的被清償了、清償的過程就是函式分解那篇的拆分 case。從識別、記錄、排程到清償的完整鏈條，是「記錄技術債」這個動作有意義的前提。

判讀徵兆

• 崩潰 stack 指向 async 函式裡 await 之後的 state 寫入 / ref 操作——async gap 沒守，順著函式把每個 await 之後補檢查
• 流程越長、頁面越可離開（匯入、同步、批次處理），gap 風險越高——這類 ViewModel 寫完先數 await、對照數 mounted 檢查
• 想把 guard 抽成 helper——先問「review 時需不需要看見每個哨位」；位置即語意的程式碼、明確勝過 DRY
• 重構評估產出「不重構」卻沒有債務記錄——評估白跑了；「不修」的合法形式是「記錄 + 排程」

相關閱讀

• 債務清償的下文：88 行拆成 13 個函式——本文識別的 TD-012 在下個版本的清償實錄
• 同框架的生命週期家族：雙容器狀態脫節——那篇是容器的空間邊界、本文是 Notifier 的時間邊界
• build 階段的對偶：全域錯誤處理器在 widget tree 建置中改 provider 的崩潰（v0.9 的 microtask 延後修法）——await 之後太晚、build 之中太早，ref 的合法視窗兩頭都有界