本章把邊界拆成四個方向，每個方向由一個實際踩過的 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 指南的讀側與觀測路線 進。

閘門 spike：編排的宿主能不能在 headless 環境立起來

流程測試要驅動的是控制器裡的真實編排——順序約束、防護動作、收尾同步——而 Flutter 的控制器在 onInit 常帶平台耦合（platform channel 訂閱、相機偵測、外接裝置 plugin）。這些耦合在 headless 測試環境全部失效。

開工前先做一條最小測試 spike：能否建構控制器並呼叫編排入口。spike 的答案決定整個套件形態——立得起來就直接驅動真實編排（零漂移），立不起來要先評估重構接縫的成本。

平台耦合的中和工具在 Dart 生態有固定的對應：

時序欄位承載的是這張表最容易踩的陷阱：EventChannel 的訂閱發生在 plugin 建構子裡，晚一步掛 mock，訂閱已經對著真實 channel 成立、之後補掛不會回溯生效——症狀是測試偶發卡在等事件。MethodChannel 的容錯高一些（呼叫當下才查 handler），但同樣要在第一次呼叫前就位。no-op 子類優於 mock 框架的場景：要中和的成員少（覆寫列表一目瞭然）、其餘行為要保留真實。流程測試的精神是假件越少，測試的證言越可信——這裡指的是平台耦合層的假件（與被驗編排無關的雜訊），被測邊界本身的假後端是另一回事，它的設計判準與忠實性把關見語意級假後端。

這套 channel mock 加 no-op 子類的組合（後文稱 harness）一旦成立就收斂為共用 bootstrap 方法——之後每條流程測試的邊際成本只剩劇本本身。完整 case 與程式碼範例：讓 UI 控制器在 headless 測試立起來。

兩種測試的共存：binding 的檔案級 isolate 隔離

流程測試需要 TestWidgetsFlutterBinding（mock channel、立控制器），真實後端驗證測試需要真實網路——兩者互斥。TestWidgetsFlutterBinding.ensureInitialized() 的副作用之一是把 dart:io 的 HttpClient 換成一律回 400 的假件，且這個副作用是程序級全域、沒有乾淨的關閉開關。

共存機制不需要額外設計：flutter test 讓每個測試檔案跑在獨立 isolate，而 isolate 之間記憶體不共享——binding 換掉的全域物件只在自己的 isolate 內生效，副作用因此以檔案為邊界。

硬約束：真實後端驗證測試的檔案不可 import 流程測試的 harness——harness 為了 mock channel 第一步就是 ensureInitialized，import 進來即使不直接呼叫，任何共用 helper 順手初始化都會中招。違反這條約束的症狀是「穩定 400、無網路痕跡」——症狀與原因之間距離太遠，值得寫進檔頭。

真實後端驗證檔裡繞開產品 DI 的做法：手組最小可用的 Dio，請求與解析仍走產品的 API client 與模型（型別化解析層共用、不手寫 JSON）。完整機制與程式碼：TestWidgetsFlutterBinding 會擋掉真實網路。

輸出雜訊治理：預期環境狀態的正確處理路徑

harness 立起後，測試輸出可能固定印出幾行「錯誤長相」的文字——相機偵測的 MissingPluginException、toast 套件的 assert fallback。這些在生產環境是正確的防護路徑，在測試環境是必然觸發的假警報。假警報訓練人忽略輸出，新的真警報混在裡面就被同一個心理過濾器吃掉。

治理原則：測試環境 100% 必然成立的觸發條件，用前置判斷或 harness mock 讓它走正常路徑，讓例外接管只剩真正的例外。

前置判斷放在 runZonedGuarded 的 zone 內而非外——極端環境（binding 未初始化）連 WidgetsBinding.instance 都會拋，放 zone 內讓它落入兜底。分工因此變乾淨：前置判斷處理已知的環境狀態，zone 兜底處理未知的失敗。完整案例與判準：測試輸出的雜訊治理。

假後端的回應序列化：物件 → toJson，不是手寫 JSON

有狀態假後端的回應資料從哪裡來，是 Dart 生態特有的選型：freezed 模型天生雙向（fromJson/toJson），假後端持有模型物件、出口一律 toJson()，服務層走的反序列化路徑與生產環境完全相同。

手寫 JSON 樣板跳過這個閉環的前半段——樣板對不對靠人眼比對 API 文件。實際案例：同一批測試裡的 raw 寫法重踩了產品早已內建處理的分頁包裝（信封解析層的知識被重複實作在測試 helper 裡），改走產品的 API client 與模型後，helper 連同它代表的重複知識一起刪除。

判準一句話：回應形狀的知識只該存在一份。測試裡出現 data['data'] 之類手挖回應欄位的 helper，就是重複知識的訊號。

假後端的狀態演變用 copyWith 在 handler 裡宣告式完成，一個 handler 對應一條已證實的後端行為。toJson 閉環的忠實性由配對的真實後端驗證測試把關——模型的 fromJson/toJson 若與真實後端不對稱，會在那裡先於產品爆出來。完整做法與對照組事故：有狀態假後端用真實模型序列化回應。

建置順序

四個限制的處理有先後依賴：

1. spike：一條最小測試驗證控制器能否在 headless 環境建構並呼叫編排入口
2. harness 收斂：spike 過了之後，把 channel mock + no-op 子類 + postFrameCallback 補位收進共用 bootstrap
3. 檔案隔離規劃：真實後端驗證測試另開檔案、不 import harness、不初始化 binding
4. 雜訊治理：harness 的 channel mock 順便解決大部分雜訊；剩餘的 headless 環境假警報加前置判斷
5. 假後端序列化：以 freezed 模型持有狀態、toJson 出口，seed builder 集中維護初始狀態
6. 第一條劇本：走完一段跨服務業務旅程，斷言散佈在各階段的可觀察結果上

步驟 1 決定後續全部形態——立不起來就回到策略層重新評估（語意級假後端與流程測試的「可測性閘門」段）。

下一步路由

• 策略層的完整判準（什麼時候值得建假後端）→ 語意級假後端與流程測試
• 配對的真實後端驗證（假後端行為漂移的防線）→ 真實後端驗證測試
• 憑證的存放與 CI 注入 → 測試憑證管理
• 各限制的完整 case：headless 控制器、binding 互斥、雜訊治理、假後端序列化

「這個領域值該不該升級成值物件」的判定屬於理論層，判準是同一性語意與語意封閉、與語言無關，見 entity 與 value object 的判準 與 value object 卡。本章接手判定之後的問題：在 Dart 裡，同一個「值物件」有三種實作載體，成本結構與適用情境各異——選哪條由這個值的欄位數、要不要 runtime 身份、以及專案對產生器的容忍度決定。

判斷：什麼領域值值得升級

值得升級的訊號是一個領域概念以裸的通用型別跨模組流通、而它的合法運算明顯少於底層型別。金額用 double 或 Decimal、識別碼用 String、數量用 int——這些型別在模組之間傳遞時，型別系統對「金額乘金額」「識別碼相加」這類無意義運算全部放行，因為它們在底層型別的世界裡都合法。合法運算集合小於底層集合、且裸型別已經跨越模組邊界，包一層的價值就成立。

這裡有兩個常被壓成一個的獨立問題。精度是底層表示的問題——浮點數累加金額會把誤差堆到分位，換一個高精度數字型別就解決。語意是運算邊界的問題——換完精度型別後，「任何人都能對這個值做任意運算」原封不動。解掉第一個問題的當下第二個問題完整存在，而它要等夠多「拿金額亂算」的路徑累積後才顯形。把兩者混為一談的後果是換完 Decimal 就宣告收工、語意缺口留在原地。

反過來，不是每個領域值都值得升級。合法運算集合幾乎等於底層型別的集合時（一個真的就是任意整數的計數器），封閉沒有差集可關、專用型別只是多一層轉換。裸型別從不跨越模組邊界、只在單一函式內部短暫存在時，誤用的窗口太小、升級的維護成本收不回。判準操作化成一句話：盤點這個概念的合法運算清單、跟底層型別的運算集合做差集，差集非空且裸型別在模組間流動，才動手。

實作路徑的成本結構

三種載體對應兩條軸：這個值是單一底層值還是多欄位複合值、以及需不需要 runtime 的型別身份。單一底層值（金額包一個數字、識別碼包一個字串）走 extension type 最省；多欄位複合值（地址、日期範圍、含幣別的金額）需要一個真正的物件裝多個欄位，走 class 路徑，class 又分手寫與 freezed 產生兩種。runtime 身份的需求橫切這兩軸——需要 is Money 在執行期為真、或需要反射看得到型別時，只有 class 路徑滿足。

Dart 3 的 record 是多欄位載體、還自帶結構相等，看起來像多欄位複合值的第四條路徑，但它不入選值物件的載體、原因在型別語意。record 是結構型別而非名目型別：兩個欄位形狀相同的概念（(String, String) 的地址與姓名）在型別系統裡是同一個 record 型別、拿不到 DateRange 這種領域名字，也就換不到「傳錯型別編譯期就擋」的保護。record 沒有建構子、無處掛不變式檢查，也無法限縮 API——任何拿到它的程式碼都能讀所有欄位、組任意新值。值物件要的名目身份、建構期不變式、封閉介面，record 結構上三個都不給。它適合的是函式的匿名多回傳與臨時分組，不是需要領域約束的值物件。

手寫 immutable class 與 copyWith

手寫 immutable class 是最直接的載體：所有欄位 final、建構子帶不變式檢查、要「改」就造一個新實例。多欄位複合值在這條路徑上用 copyWith 做逐欄位覆寫——傳要改的欄位、其餘保留原值、回傳新實例，這對欄位組合全部合法的值語意清晰。成本在 boilerplate：== 與 hashCode 要手寫且要涵蓋所有參與相等性的欄位、copyWith 每加一個欄位就要同步一行，漏一個欄位的相等性比對是安靜的 bug。

這條路徑的邊界在 copyWith 的適用範圍。對欄位組合全部合法的資料袋與純值物件，copyWith 是正確工具；對有領域方法、欄位之間有不變式約束的型別，全欄位 public 的 copyWith 是繞過領域方法的逃生口——領域方法從「唯一變更路徑」降級成「建議路徑」。判準是型別有沒有「不允許任意組合的欄位」，有的話那些欄位就不該讓 copyWith public 可寫。完整機制見 copyWith 是逃生口，不是設計。

freezed 產生器

freezed 是把手寫 class 的 boilerplate 壓到接近零的產生器：標記 @freezed 後自動產生 copyWith、== / hashCode、toString()、以及 sealed union。多欄位複合值需要完整相等性與序列化、又不想手工維護每個欄位的同步時，freezed 是這條路徑的主流選擇；它的 sealed union 在枚舉分層上另有價值——exhaustive switch 讓「忘記決定新成員歸哪類」在編譯期就走不通。

成本結構有兩面。一面是工具依賴：freezed 走 build_runner 產生程式碼，專案要接受產生器的建置步驟與產物管理。另一面是預設路徑的一視同仁——freezed 不區分資料袋和有領域方法的 entity，每個被標記的 class 都得到全欄位 public copyWith，包含狀態欄位與稽核欄位。規範說「請走領域方法」、工具預設給全欄位 copyWith，兩者衝突時預設會贏。在 entity 上使用 freezed 需要額外收窄：把 copyWith 改 private、或從參數列移除受約束的欄位。結構細節見 Freezed 三層結構解剖。

extension type 零成本包裝

extension type 是 Dart 3.3 起提供的載體，把單一底層值包成一個新名字、限縮可用的 API、而 runtime 不存在額外物件——編譯後就是底層型別本身，所有約束活在編譯期。單一底層值的語意封閉、又在高頻路徑上流通（金額在每筆訂單明細累加、識別碼在每次查詢傳遞）時，這條路徑用零 runtime 開銷換到型別安全。它跟 class 路徑是互斥的實作選擇：class 走 runtime、有型別身份也有 overhead；extension type 走編譯期、零 overhead 但 runtime 透明，is 與 as 看到的是底層型別。

用 extension type 時要在設計期定 subtype 決策——它是底層型別的 subtype（寬鬆：可隱式 upcast 回底層、封裝邊界弱）還是獨立型別（嚴格：只能顯式拆封、每個銜接點都要拆）。金額的做法是 implements Object 而只有 Object：既有的格式化入口 formatAmount(Object) 能直接吃它、不必改簽名；同時它不是數字型別的 subtype，於是不能被傳進任何收數字型別的參數，裸運算沒有回來的路。這條路徑不搭 copyWith——extension type 沒有 runtime 物件可以逐欄位覆寫，逐欄位覆寫語意只在 class 路徑上成立。

三條路徑的選型錨點收在下表，每一列的成本結構與適用情境在上面各自的段落展開：

從原始型別遷移過去

值物件多半在裸型別的誤用累積之後才補上去，於是實作值物件常常等於一次型別遷移。一個金額欄位的遷移軌跡把兩個獨立問題各解一段：最初是浮點數、累加誤差堆到分位；第一段換成高精度數字型別、精度問題解決；金額仍然是裸的通用數字、任何拿到它的程式碼都能做任意運算，於是第二段把它包進 extension type，開放的運算限於領域有意義的集合。運算列表本身就是領域規則的宣告：金額加減可以、乘數量可以、乘倍率可以（刻意跟數量分開簽名），金額乘金額不存在、因為介面沒開放。想對它做底層型別的任意運算，得先顯式呼叫拆封方法，那一行拆封程式碼就是 code review 的攔截點。這條軌跡的完整素材見 金額型別的三段遷移。

遷移動的是全專案的欄位，安全網是 characterization test——遷移前對著舊實作寫、鎖住當前輸出（包含當前的邊界行為，例如找零算出負數時歸零），遷移後全綠就證明型別替換沒有帶入行為變化。它跟一般測試的差別在斷言的性質：它驗證「行為不變」、不驗證「行為正確」。正確性是另一批測試的事——把兩個問題混在同一批測試裡，遷移期間的紅燈就分不清是「換壞了」還是「本來就錯」。做法展開見 測「不變」、不測「正確」：characterization test。

取值出口：封裝的對象是運算、不是取值

值物件封住的是「任意運算」、不是「取原始值」本身。基礎設施邊界對原始值有正當需求——快取需要 key、資料庫需要 column 值、序列化需要原始表示、格式化銜接層需要底層型別。正確做法是給原始值一個語意明確的官方出口，而不是禁止取值逼下游硬撬。金額的拆封方法 toDecimal() 就是這種出口，註解直接寫明供哪種場合使用；序列化給 toDbValue() 這類名字說明用途的方法；UI 顯示給 displayValue。有官方出口的世界裡「誰在拆封」是可 grep 的（搜出口方法名就是完整清單），封裝邊界是明示的。

把取值本身當違規會來回撞牆。一個 App 的識別碼型別的封裝政策擺盪過兩輪：先追「零個外部取值」把公開介面只留 toString()，撞上基礎設施層的正當需求後又把取值 getter 加回來、改名叫「相容性介面」。兩個極端各自的撞牆點是同一個病的兩面——完全封裝逼正當消費把 toString() 當取值 API 用（語意寄生，toString() 哪天為除錯改格式、快取 key 就靜默換一批），零封裝則讓 ISBN 校驗、ID 格式這些不變式失去強制點。穩態在中間：原始值有官方出口、出口有語意、邊界寫進決策記錄。擺盪的完整軌跡見 Value Object 的封裝擺盪，出口設計的理論層展開見 建構路徑設計。

邊界

本章處理值物件在 Dart 的實作載體選擇，是實作層知識。三個上游判定不在本章：一個型別該不該模型化成領域模型（入口判準見 資料袋與領域模型）、模型化之後該用 entity 還是 value object（同一性判準見 entity 與 value object 的判準）、以及約束該落在文件層、型別層還是執行層（見 不變式的強制層次）。值物件把封閉做在型別層，防的是無心誤用——刻意用反射或 dynamic 拆封仍然繞得過，威脅模型是「防止意外」而不是「防止刻意」。

型別層防護的另一半責任落在 entity 而非 value object：entity 的同一性由身份定義、有生命週期、變更要走領域方法，那條路徑的收窄（copyWith 逃生口、稽核軌跡凍結）跟本章的值物件封閉是相鄰但不同的問題，路由到 狀態轉換與稽核軌跡。

下一步

三條實作路徑各有 case 可深讀：copyWith 的適用邊界在 copyWith 是逃生口，不是設計、freezed 的結構在 Freezed 三層結構解剖、extension type 的 subtype 決策與遷移在 金額型別的三段遷移。取值出口的封裝邊界在 Value Object 的封裝擺盪、遷移安全網在 characterization test。理論地基從 DDD 指南的模型設計主梯 進，值物件在其中的位置是 entity 與 value object 的判準 的語意封閉段。