AppService 宣告了 late final PackageInfo packageInfo;，在 init() 中透過 PackageInfo.fromPlatform() 非同步初始化。測試用的 TestAppService extends AppService 想跳過平台呼叫，直接給一個固定值：

1// ❌ analyzer 報錯：overridden_fields
2@override
3late final PackageInfo packageInfo = PackageInfo(...);

Dart analyzer 報 overridden_fields：欄位覆蓋了從 AppService 繼承的欄位。

根因：late final 欄位 = getter + setter

Dart 的每個 instance 欄位在底層都會生成對應的 getter（和非 final 的會生成 setter）。late final 更特殊——它生成的 getter 包含「是否已初始化」的檢查邏輯，setter 包含「只能寫入一次」的 guard。

當子類用另一個欄位覆蓋時，記憶體中會有兩個獨立的儲存槽：

父類的 init() 或其他方法如果存取 packageInfo，會讀到父類那份未初始化的 slot，拋出 LateInitializationError。這就是為什麼 Dart 不允許用欄位覆蓋欄位。

修法：改用 getter 覆寫

1@override
2PackageInfo get packageInfo => PackageInfo(
3  appName: 'UniPos Test',
4  packageName: 'com.mxkj.unipos.test',
5  version: '1.0.0',
6  buildNumber: '1',
7  buildSignature: 'test',
8  installerStore: null,
9);

Getter 覆寫只有一個讀取入口——不管父類還是子類的程式碼呼叫 packageInfo，都走子類的 getter。不會有兩份 slot 的問題。

通則

Dart 中覆寫父類的欄位，一律用 getter（必要時加 setter），不要用欄位。這不只適用於 late final——所有欄位覆蓋都有同樣的雙 slot 風險，只是 late final 的症狀最明顯（直接拋 LateInitializationError），普通欄位的症狀更隱蔽（值不同步）。

測試用的 TestRiveAnimation extends StatelessWidget 裡宣告了 final Key? key;，constructor 中透過 super(key: key) 傳給父類。Dart analyzer 警告 key overrides an inherited member。

加了 @override 可以消除警告，但問題沒有解決——class 裡現在有兩個 key slot（子類自己的和 Widget 繼承的），而 build 方法裡又寫了 Container(key: key)，把同一個 key 同時掛在 parent widget 和 child widget 上。

根因

Widget 的 key 是 final 屬性，由 constructor 的 super(key:) 設定。子類重新宣告同名欄位會產生 shadowing：

• 子類的程式碼（包括 build）讀到的是子類自己的那份 key
• 父類 Widget 的框架程式碼讀到的是父類的那份 key

兩份值相同（因為 constructor 都有寫入），但語意上是兩個獨立的 slot。更危險的是，如果在 build 裡把 key 往下傳給 child，同一棵 widget 子樹會出現兩個相同的 Key 值，Flutter 在 diff 時可能拋出 duplicate key 錯誤。

修法

不要重新宣告 key，改用 super.key：

1const TestRiveAnimation.asset(
2  this.asset, {
3  super.key,           // 直接傳給 Widget，不產生新 slot
4  this.useArtboardSize = false,
5});

build 裡也不要把 widget 自身的 key 再傳給 child——key 是給 framework 用來識別這個 widget 的，不該手動轉發。

判斷原則

在 Flutter 中，key、hashCode、runtimeType 這類從 Widget / Object 繼承的屬性，子類永遠不該用欄位覆蓋。如果需要自訂行為，覆寫 getter。

核心議題：高階函式是特定場景的自然解 — 當「流程固定、變化點單一且開放」時，把變化點抽成函式參數最省。要不要用它，由場景特徵決定。本文先論證這個場景為何適合 HOF，再比較同一 pattern 的兩種表達（裸函式型別 vs typedef）各自的優缺點。 案例骨幹：SettingsController.update(transform) — 9 個設定欄位共用同一條「取值→算新值→去重→通知」流程，唯一的變化是「改哪個欄位」。

1. 案例：一個收函式的設定更新方法

設定有 9 個欄位（字型、顏色、描邊、時間格式、目標螢幕、開機啟動…）。每個欄位變更都要走同一串流程：取當前設定 → 算出新設定 → 比對是否確實改變 → 賦回並通知 UI 重繪。把這串流程封裝成一個方法：

1class SettingsController extends ValueNotifier<SettingsModel> {
2  void update(SettingsModel Function(SettingsModel current) mutate) {
3    final SettingsModel next = mutate(value);
4    if (next != value) {
5      value = next;
6    }
7  }
8}

呼叫端只描述「改哪個欄位」：

1controller.update((s) => s.copyWith(fillColor: c));
2controller.update((s) => s.copyWith(fontSize: v));

update 收的這個參數本身是「一個函式」 — 把函式當成可傳遞的值。這就是 higher-order function。

簽章的型別與名字拆解

這個簽章的關鍵是分清「哪裡是型別、哪裡是名字」。它是一個普通的參數宣告，順序跟常見的 int count、Color color 一樣是 型別 名字，只是這次型別換成了較長的函式型別：

1void update(SettingsModel Function(SettingsModel current)  mutate)
2//          └──────────── 型別（函式型別）────────────┘  └名字┘

mutate 是這個參數的名字 — 方法內部靠它指涉傳進來的那個函式：

1void update(SettingsModel Function(SettingsModel current) mutate) {
2  final SettingsModel next = mutate(value);  // ← 用名字 mutate「呼叫」傳進來的函式
3}

容易混淆的是型別裡面那個 current：它和 mutate 不同層級 — current 只是函式型別內標記參數的名字，純文件性，寫成 SettingsModel Function(SettingsModel) 行為完全一樣，只是讓型別讀起來更清楚。換句話說，前半的函式型別規定「這個名字必須是什麼形狀的函式」，最後的 mutate 則是「這個函式參數叫什麼」。下一節先補 HOF 的基礎，第 4 節再回頭談「前半那串型別裸寫在簽章」造成的閱讀摩擦。

2. Higher-order function 是什麼（最小定義）

把函式當資料處理的函式 — 接收函式當參數，或回傳函式，符合其一即是。前提是語言把函式視為一等公民（first-class），能像變數一樣傳遞。Dart、JS、Kotlin、Swift 皆成立。

常見的 list.map((x) => x*2)、list.where((x) => x>0)、onPressed: () => ... 都屬此類。update((s) => ...) 是同一家族。

3. 為什麼這個場景適合用 HOF

這個場景有三個特徵，剛好對上 HOF 的強項 — HOF 適不適用，由這些特徵決定。

3.1 流程固定、變化點單一

9 個欄位的更新，流程 100% 相同（取值、去重、賦回、通知），唯一差異是中間那一步「copyWith(哪個欄位: 值)」。

當「共用流程」與「變化點」能這樣切乾淨時，HOF 正好對上這個結構：把固定流程寫死在 update 裡，把變化點抽成函式參數 transform 由呼叫端帶入。map 對「走訪迴圈（固定）+ 元素變換（變化）」做的是同一件事。

3.2 模型不可變，本來就是「current → next」

SettingsModel 是不可變物件（@immutable + 全 final）：要改 fillColor，得用 copyWith 產生新副本、再把整個物件替換回去。

也就是說，不可變模型下的更新，在語意上就是一個 (current) => next 的函式 — 拿舊值算出新值。用函式參數表達這件事，是最貼合的形狀。

3.3 變化點開放、難以列舉

「未來會改哪些欄位、怎麼組合」是開放的（可能同時改兩個欄位、可能有條件邏輯）。函式參數能表達任意轉換；若改用「enum 指定欄位 + switch」則被固定的列舉鎖死，每加一種改法都要動 update 內部。HOF 把「怎麼改」的決定權留在呼叫端，update 不需要知道。

反過來說，當「變化集合是封閉的、而且需要被序列化或跨層比對」時，enum + switch 反而較好 — 例如要把「使用者改了哪個欄位」存進 undo 堆疊、或透過網路傳給後端，列舉值是可序列化的資料，閉包不是。本案例的變化點純粹發生在呼叫端、不需要 persist，HOF 才站得住。所以「開放」算不算優點，要跟「變化是否需要被當資料搬運」一起看。

判準：流程固定 + 變化點單一 + 變化開放 三者同時成立時，HOF 幾乎總是比「列舉 + 分支」或「複製多個方法」更省。

對照反例放進具體場景更清楚。假設一個只有「深色模式開關」單一布林設定的 controller，更新邏輯就是 value = !value，既沒有共用流程、也沒有開放的變化點 — 這時把它包成收函式的 update，只是逼讀者解析一串函式型別去做一件 toggleDarkMode() 就講完的事，抽象成本大於收益。另一種反向情境是：9 個欄位看似共用流程，實際每個的更新路徑各不相同（有的要打 API、有的要寫檔、有的純記憶體），那麼「固定流程」的前提根本不成立，硬抽進 update 反而把三條不同的路徑塞進同一個殼裡。三條件少一條，具名方法通常更省 — 場景不對時硬用，才是過度設計。

4. 原始寫法的優缺點（裸函式型別）

1void update(SettingsModel Function(SettingsModel current) mutate) {
2  final SettingsModel next = mutate(value);
3  if (next != value) value = next;
4}

什麼是「函式型別裸寫在簽章」

這是整個討論的起點，值得單獨講清楚。把術語拆三個詞：

• 函式型別：描述「一個函式長什麼樣」的型別，例如 SettingsModel Function(SettingsModel current) — 收一個 SettingsModel、回傳一個 SettingsModel。
• 裸寫：把完整型別整串攤開寫出來，沒有先取名包裝（對比「裸數字 / magic number」直接寫 120 而非具名常數）。
• 在簽章：寫在方法的參數列（signature）裡。

合起來就是：把那串 SettingsModel Function(SettingsModel current) 原封不動塞進參數位，而不是先用 typedef 取個名字再引用。

1// 裸寫：函式型別整串長在簽章裡
2void update(SettingsModel Function(SettingsModel current) mutate)
3//          └────────── 這一整串就是「裸寫的函式型別」──────────┘

為什麼偏偏是「函式型別」會因為裸寫而卡住，一般型別卻不會？因為 int、Color 這類型別已經是短名稱，裸寫毫無負擔；而函式型別的完整語法 X Function(Y) 較長、巢狀時更難讀，讀者得當場在腦中解析「這是收什麼、回什麼的函式」。讀程式碼第一眼卡住的，正是這串裸寫的函式型別 — 它才是這篇要討論「要不要抽 typedef」的真正觸發點。下面的優缺點，都圍繞「裸寫 vs 取名」這個軸展開。

優點

• 型別就地可見：函式的形狀（收什麼、回什麼）直接寫在簽章上，讀者不必跳到別處查定義。
• 零額外宣告：不需要為了一個參數多定義一個型別別名。

缺點

• 簽章冗長、語法門檻：SettingsModel Function(SettingsModel current) 對不熟函式型別語法的人構成解析負擔，一眼難消化。
• 命名與語境矛盾：參數叫 mutate（變異／就地修改），但模型不可變、實際是「產生新副本」，名稱會誤導。
• 缺使用錨點：簽章沒有範例，第一次用的人不知道該傳什麼形狀的 lambda。

5. typedef 改寫後的優缺點

1/// 設定轉換規則：收當前設定、回傳改好的新設定（通常以 copyWith 實作）。
2typedef SettingsMutator = SettingsModel Function(SettingsModel current);
3
4/// 套用一條「目前設定 → 新設定」的轉換規則 …
5/// 範例：`controller.update((s) => s.copyWith(fillColor: c));`
6void update(SettingsMutator transform) {
7  final SettingsModel next = transform(value);
8  if (next != value) value = next;
9}

優點

• 簽章簡潔、概念命名：SettingsMutator 把函式型別升格成領域詞彙，認知從「解析 X Function(Y)」降到「讀一個名詞」。
• 命名精準：transform（轉換）貼合不可變語境，不再暗示就地修改。
• 有錨點：doc comment 的範例讓第一次使用者立即知道怎麼傳。
• 錯誤訊息更易讀：型別對不上時，編譯器印的是 SettingsMutator 這個名字，而不是整串 SettingsModel Function(SettingsModel)；裸寫版的錯誤訊息會把完整型別攤開，較難一眼定位。
• 可重用：同一個 SettingsMutator 型別若日後被多個 API 共用，定義集中一處。

缺點

• 多一層 indirection：想知道 transform 的確切型別，得跳到 typedef 定義；只看 update 簽章看不到形狀。
• 多一個命名負擔：SettingsMutator 本身要取得好；命名不當反而多一層要理解的東西。
• 對單一用途略顯重：若這個函式型別只在一處使用，typedef 的「集中重用」優點用不上，只剩「命名」一項收益。

6. 並排比較

關鍵：兩者是同一個 pattern（HOF + ValueNotifier）的兩種表達。取捨重點在「型別就地可見」對上「簽章簡潔 + 概念命名」—— 當函式型別會被多處使用、或語法門檻造成實際閱讀摩擦時，typedef 划算；若只用一次且團隊熟悉函式型別語法，裸寫也完全合理。

改寫的驗證也印證它停在「表達層」：呼叫端傳 lambda 不依賴參數名 → 零修改；行為不變；全套測試原封不動通過。

7. 收斂

• HOF 適合的場景特徵：流程固定 + 變化點單一 + 變化開放。三者齊備時，把變化點抽成函式參數最省；場景不符（欄位少、流程各異）則具名方法更直白。
• 不可變模型的更新本質就是 (current) => next，用函式參數表達是語意上最貼合的形狀。
• 兩種寫法的取捨：裸函式型別型別就地可見、零宣告；typedef 簽章簡潔、命名成概念、可重用，但多一層 indirection。
• 選擇依據：函式型別是否多處共用、語法是否造成實際閱讀摩擦。摩擦明顯就抽 typedef，否則裸寫無妨。

延伸：本文「模型不可變」段是整個 HOF 適配的前提之一。SettingsModel 那種 @immutable + copyWith 結構怎麼產生、以及更好懂的替代路徑，見 Freezed 的三層結構解剖。

核心議題：寫測試時觸及 type system 看不到的 runtime contract — service locator 的注入契約、widget tree 的 framework state、async error 的 try-catch 邊界。三類都要 runtime 才會炸、test 跑到才會曝光。 案例骨幹：Popup.hint 同一條呼叫路徑同時持有 sync 與 async 兩條失敗路徑（缺 service 注入、BotToast 同步 assert、BotToast 從 async gap 後拋 LateInitializationError）。用 runZonedGuarded 把兩條路徑收斂到同一個 fallback handler、用 fallback signature 設計讓訊息不被誤判為 error。

1. Type system 看不到的 runtime contract

flutter analyze（與一般的 type checker）的責任是檢查宣告與名稱層的契約 — 型別一致、import 能解析、識別字能對到符號。它驗證的是「靜態可決定的事」：missing import、undefined method、type mismatch 都會在 compile 前被攔下。

它看不到的是 runtime 才成立的契約，這正是寫測試最容易暴露的盲區：

• Service locator 的注入契約：GetX 的 Get.find<T>()、get_it 的 GetIt.I<T>()、Provider 的 Provider.of<T>() 都是 runtime 查找機制（Map lookup 或 widget tree 上溯，視實作而定）。「呼叫前 T 必須先註冊或在 ancestor 提供」是執行期前置條件，型別系統看不見。
• Framework state 的存在前提：BotToast 需要 widget tree 上有 BotToastInit、Navigator 需要 MaterialApp 包著。這是 framework 的執行期狀態，不是型別。
• late 變數的跨呼叫順序契約：宣告對了不代表用對了。analyzer 對單一檔案內某些 unsafe pattern 能出警告，但「A 函式必須在 B 函式前被呼叫」這類跨呼叫順序契約，型別系統看不見。

這個邊界對「寫測試」的意涵：test setUp 不只是準備資料，更是補上 type system 看不到的 runtime contract — 注入哪些 service、提供哪些 framework state、控制哪些 init 順序。主程式裡那些「靠 widget tree」「靠 service locator」「靠 framework lifecycle」的契約，每一條都對應到 test setUp 的一個責任。

2. 案例：一條呼叫路徑觸及三類邊界

下面以 Popup.hint 對 BotToast.showNotification 的呼叫為例。寫一個跑 AuthService.afterLogin 的 unit test 時，這條呼叫一次觸及 runtime contract 段列的三類邊界：service locator 注入缺失、widget tree 缺 BotToastInit、late 變數在 async 排程後讀取。三組訊號攤開：

第一條的修法是 setUp 補注入。第二條的同步 assert 單獨看，sync try-catch 接得住。但它跟第三條 async error 是同一個 API 的兩種失敗模式 — 包 sync try-catch 只罩到同步那條、async 那條仍漏。

結論：要兩條都接到，需要一個同時 cover sync 與 async 的接管機制。

3. Sync try-catch 與 async error 的邊界

Sync try-catch 的作用範圍是同步調用棧：try block 執行期間棧上拋的錯誤會被接住。一旦執行流程穿越 async 邊界（Future、Timer、microtask 排程），原 try-catch 已經出 scope：

1Popup.hint() {
2  try {
3    BotToast.showNotification(...)   ← 同步返回，立刻離開 try
4      └─ 內部排到下一個 frame 或 microtask {  ← 之後才跑
5           ...拋 LateInitializationError...   ← try-catch 已經出 scope
6         }
7  } catch (e) { ... }
8}

辨識 async unhandled error 的訊號是 stack trace 裡有 ===== asynchronous gap ===== — 它代表錯誤穿越了一個 async 邊界。從 caller frame 來看「沒人在 stack 上」，錯誤會上溯到 zone 的 uncaught error handler；root zone 把它印到 stderr，或讓 flutter_test runner 當作 test failure。

async 函式內的 try-catch 是常見混淆點：寫成 try { await x; } catch (e) 時，try-catch 能接住 await 的 future rejection（await 把 async error rewire 成 sync throw）。但對沒 await 的 fire-and-forget 排程（直接呼叫一個會內部 schedule microtask 的 API），try-catch 的覆蓋範圍止於同步路徑。

風險：fire-and-forget API 的 error 路徑跨 async 邊界

BotToast、analytics、Toast、SnackBar 這類 API 通常同步返回（讓 caller 不必 await），內部排到下一個 frame 或 microtask 做 UI 工作。caller 看到的是同步呼叫，但錯誤可能從 async 邊界後跑出來。caller 端的 sync try-catch 看起來罩住了，實際接不到。

4. 接管機制：runZonedGuarded 同時罩 sync 與 async

接 async unhandled error 要用 zone-aware 機制。runZonedGuarded(body, onError) 建立一個子 zone，任何在這個 zone 內 schedule 的 async work，錯誤都會冒泡到 onError — 不管錯誤穿越幾層 microtask、Timer、Stream。它同時也 cover 同步拋錯，可以取代 try-catch 包住整個 best-effort 邊界：

 1// toast 是 best-effort：BotToast 需要 widget tree (BotToastInit)，
 2// 在非 UI 環境（unit test、isolate）顯示失敗時保留 log、不向 caller 傳遞錯誤。
 3// 用 runZonedGuarded 因為 BotToast 部分錯誤從 async gap 後拋出，sync try-catch 接不到。
 4runZonedGuarded(() {
 5  BotToast.showNotification(
 6    title: (_) => Text(message, style: AppTheme.whiteTextButtonStyle),
 7    backgroundColor: contentColor,
 8    duration: const Duration(seconds: 2),
 9    animationDuration: const Duration(milliseconds: 300),
10    animationReverseDuration: const Duration(milliseconds: 300),
11  );
12}, (error, stack) {
13  if (kDebugMode) {
14    debugPrint('[Popup.hint][fallback] BotToast 不可用，僅記 log：$error');
15  }
16});

機制重點：同一個 onError 同時接住同步的 Failed assertion 與 async 的 LateInitializationError — sync 與 async 兩條失敗路徑收斂到單一 fallback handler，不需要為兩條各寫一套錯誤處理。

5. runZonedGuarded 的責任邊界

runZonedGuarded 把整個邊界的錯誤導向 fallback handler，責任範圍要劃清楚：

zone ≠ thread。Dart 是單線程的，zone 只是邏輯標籤、不涉及並發。它只改變錯誤的去向、不會 cancel 已 schedule 的 work。

注意事項：何時不該用

Zone 歸屬以 schedule 時的 zone 為準、不是執行時 — async 物件「屬於」schedule 它的那個 zone。這個規則讓跨 zone 操作 Timer、Stream 的行為偏離直覺。實務上最常見的觸發場景是 WidgetsFlutterBinding.ensureInitialized() 在 root zone 註冊了 framework binding 後、才用 runZonedGuarded 包 runApp，binding 內部 callback 已綁在 root zone、外層 zone 接不到。Flutter 官方明確建議 ensureInitialized() 跟 runApp() 都在同一個 runZonedGuarded 內。

zone 適合包「整個邊界」：整個 isolate entry、整個 best-effort UI 工作、整個 background task。不適合包關鍵 transaction logic — 那是 try-catch + Future error handling 的責任，zone 是 fallback 收斂層、不是主要錯誤處理。

6. Fallback 訊息設計：可識別的 signature

Fallback path 跑通之後，留在 console 的訊息會被讀到很多次（每次 test 都會跑）。訊息措辭要與設計意圖一致，否則讀者每次都要花心力辨識「這是設計內降級、還是真的 bug」。

風險：fallback 長得像 error

直覺寫法 debugPrint('toast 顯示失敗：$error') 加上 framework 的 assert stack，字面看起來就是個 error。讀者第一眼會緊張、要花心力比對程式才能確認「這是設計內路徑」。test 跑很多次、每次都付一次辨識成本。

三條設計原則

Fallback path 要有可識別的 signature（標籤、prefix、特定字眼）、長得不像 error。對人類讀者，prefix 是視覺上一眼識別「設計內路徑」；對工具，grep -v "\[fallback\]" 可快速剔除 test 輸出裡的預期降級訊息。

字眼要表達因果與處置：「BotToast 不可用，僅記 log」比「顯示失敗」更完整 — 前者說了為什麼降級、後者只描述現象。寫 fallback 訊息要回答兩個問題：為什麼進這條路徑、降級到哪。

主程式不該感知測試框架：主程式 import dart:io、查 Platform.environment['FLUTTER_TEST'] 等於「主程式對自己被 test 跑」有意識 — 這違反「主程式不該知道 test 存在」的原則，test 框架是 caller 的事、不是 callee 的事。違反後續成本：app 行為依賴環境變數時，QA / staging / production 的環境一致性會多一條檢查線。

三個候選方案在原則上的取捨

下列三個方案分別在「signature 識別度」「主程式對 test 框架感知」「dev 可見性」三條原則上做不同取捨：

為什麼選 A

保留 dev 訊號（BotToast 在 dev app 真的壞時 console 仍會印） + 主程式對 test 框架無感知 + prefix 雙贏（人類視覺辨識 + grep 過濾）。方案 C 完全靜默會失去保險、dev 環境真壞時看不見；方案 B 雖然 test 輸出乾淨，代價是違反設計原則。

7. 設計副產物：修主程式對缺依賴的容錯

Popup.hint 對「沒有 widget tree」連環倒，這個失敗不只 unit test 會遇到 — isolate 內、background task 內、任何非 UI 環境都會炸。修 test 順手把主程式對缺依賴的容錯加上，是合理副產物：unit test 是觸發訊號、主程式被觸發後變得更能適應多元 caller 環境，這個改動的受益面大於原本 test 暴露的那個情境。

主程式變 robust 的價值大於「讓 test 過」。修主程式對 caller 環境的容錯時要分辨「容錯」與「掩蓋」的界線：log 仍要留、fallback signature 仍要可識別（Fallback 訊息設計段），錯誤完全靜默會讓 dev app 真壞掉時也看不見。

適用範圍

runZonedGuarded 適用情境：

• Fire-and-forget 的 UI 通知：Toast、SnackBar、analytics 上報；這些是 best-effort，caller 連環倒不合理。
• Isolate entry point：spawn 出來的 isolate 沒有預設 error handler，包一層 zone 才不會靜默掛掉。
• Background task / Timer 包裝：long-running periodic job 內部錯誤不該炸掉整個 process。
• flutter_test 內掛 Stream / Future 驗證：把測試體包進 zone 才能完整接 async 拋出的東西。

「Type system 看不到的 runtime contract」適用任何用 service locator / DI 容器、framework state、late init 的 Flutter 專案。Test 是這些 runtime contract 的事實驗證者 — analyze 過了不代表這些契約沒破，test 跑到才會炸。

參考資料

• Dart runZonedGuarded API
• Dart Zone 概念與 zone-local variables
• Flutter Zone mismatch breaking change — ensureInitialized() 與 runApp() 必須同 zone
• flutter_test async error 處理機制
• 同主題本站文章：Dart test 的跨檔案 GetX 狀態污染 — 另一種「test 環境組裝不完整」的 case

評估 code intelligence MCP 不能只看 README benchmark：每個工具的 benchmark 都選自己擅長的 codebase 跟語言，readme 數字只能參考、不能直接套到自家 stack。

這次選一個 Dart 商業專案做對照場域有兩個理由：

• Dart 是三個工具的「中間地帶」——cbm 不在 hybrid resolution 名單、codegraph 列為 full support、serena 借 dart analysis_server 有完整 LSP。三條技術路線在同一語言上的能力差距會被最大化。
• Dart 大量用 extension type、generic、factory pattern，這些是 type-inferred dispatch 的高發場景，能逼出每個工具的真實精度差。

在 Go / TypeScript 上跑同樣對照，結論會反過來——cbm 的 hybrid resolution 在那裡會接近 LSP 精度，三刀流的必要性會降低。所以這篇結論限定「LSP 成熟但 cbm 不在 hybrid resolution 名單」的語言。

本質差異：tree-sitter syntactic vs LSP type-aware

三個工具在 Dart 上的能力差距，根源是兩條技術路線的本質落差：

tree-sitter syntactic：只看語法結構。看到 a.b() 知道有個 method call、不知道 a 是什麼型別、不知道 b() 連到哪個 declaration。對 receiver 是 literal 或顯式型別宣告的 callsite 可以解、對 local variable / parameter / 推斷型別的 callsite 會漏。

LSP type-aware：走 language server 內建的型別推斷引擎。跟 IDE 用同一套後端、能解出 a 的真實型別、再從 type declaration 找到對應的 method。所以 reference 是型別精確的。

cbm 的 hybrid type resolution（限 Go / C / C++ / TS / JS）是把 LSP 的型別解析算法 clean-room 重寫進 binary、所以那幾個語言上 cbm 等於有 LSP 級精度但沒 LSP 依賴。Dart 沒得到這個待遇，所以 cbm 在 Dart 上只剩純 syntactic 結構抽取。

判讀訊號：看一個工具對某語言的能力強弱，問「它在這語言上做型別解析嗎？」——做的話接近 LSP，不做的話只是個結構抽取器。

這個 framework 建立後、下節展開到 9 個維度的設計對照。

三個工具的設計差異對照

三個工具雖然都是「code intelligence MCP」，設計取向互補：

這張表的判讀重點：三者擅長的事不重疊。cbm 強在「找東西」、codegraph 強在「日常 call graph + auto-sync」、serena 強在「型別精確 reference + 編輯出口」。

對照表的維度很多、但實務上踩到事故的多半集中在三個維度，把它們各自展開：

Type resolution 決定 caller 數字的可信度。Dart / Swift / Kotlin 這類「LSP 完整、但 cbm 走純 syntactic 路線」的語言上、tree-sitter 工具回的 caller 數字是 lower bound（實際值通常更高）。samplePrice.multiplyByRate(...) 這種 type-inferred receiver 是這層差距的主戰場。判讀訊號：對熱門 class 跑同一 query、若 tree-sitter 工具 caller 數比 LSP 工具低過半、type-inferred dispatch 在這語言是主流模式、tree-sitter 結果只能當 starting point。

Sync 機制決定「邊改邊問」是否可用。codegraph 的 native OS file watcher + 2s debounce 最貼近 IDE、cbm 的背景 git polling 有秒級至分級延遲、serena 的 session warm-up 是「啟動時等一次、之後即時」。事故型態：在 codegraph 改完檔案立刻問 caller 多半 OK、在 cbm 立刻問會拿到 stale graph。判讀訊號：問完 query 對結果存疑時、先檢查工具的 sync 狀態（cbm 跑 index_status、codegraph 跑 codegraph_status、serena 直接重 query）。

持久化模式決定跨 session 的累積成本。cbm / codegraph 寫 SQLite、跨 session 重用；serena per-session、每次 spawn LSP warm up。對「短任務反覆 ad-hoc 查詢」cbm / codegraph 邊際成本更低、對「會做 symbol-level edit 跟 diagnostic」serena 的 per-session warm up 是必要 cost。判讀訊號：第一次 query 慢、之後快——LSP indexing warm up、正常；每次 query 都慢——LSP 可能因記憶體不足重啟、需排查。

下面的實測是這張表在 Dart 上的數字驗證。

Dart 實測對照：同題不同工具

實測環境：

1專案類型：Dart 商業專案（POS / 零售領域）
2Branch：refactor/money-value-object
3索引規模：
4  cbm:        3,038 nodes,  6,355 edges（Dart 沒 CALLS edge）
5  codegraph:  6,244 nodes, 12,223 edges（含 CALLS edge）
6  serena:     per-session、無索引統計

cbm 跟 codegraph 的 nodes 約 2x、edges 約 2x，差異關鍵不在 nodes（cbm 缺 import / enum_member 等次要 node）、而在「有沒有 CALLS edge」——這直接決定 caller / impact 類查詢能不能用。

實測數字的適用範圍：本節的所有 callsite / caller / impact 數字（含查詢 1-5）都是單一 Dart 商業專案的內部 baseline、不保證跨專案重現。Dart 上 type-inferred receiver 比例高的專案會放大三個工具的差距、比例低的專案會縮小差距。換到 Swift / Kotlin / Rust 等語言上、絕對數字會不同但「tree-sitter syntactic vs LSP type-aware」的差距方向通常一致。讀者要套用結論時、先在自家 repo 跑一遍同題對照、看自己的數字落差。

查詢 1：誰呼叫了 Money.multiplyByRate

codegraph 漏掉的 3 個 callsite 共同特徵：

1// lib/data/models/product/product.dart
2final Money samplePrice = ...;
3samplePrice.multiplyByRate(Decimal.parse('0.9'));
4samplePrice.multiplyByRate(Decimal.parse('0.6'));

samplePrice 是 local variable、要型別推斷才知道是 Money。tree-sitter 看到的只是 <identifier>.multiplyByRate(...)、解不出 dispatch target。

serena 透過 dart analysis_server 拿到完整型別資訊、知道 samplePrice 宣告是 Money、能精確 dispatch。

查詢 2：誰呼叫了 LocaleSymbolConfig.formatAmount

這題 codegraph 跟 serena 的差距比較小——formatAmount 在很多地方是用顯式 receiver 呼叫（如 LocaleSymbolConfig.cny.formatAmount(...)），tree-sitter 對顯式 receiver 解得到。

兩邊數字的差異主因是 caller symbol 數 vs callsite 數的計數單位差：

• codegraph 算 caller symbol（一個 method 內呼叫幾次都算 1）
• serena 算 callsite

寫實測 baseline 時這個單位要寫死、否則 3 vs 9 看起來像精度差距、實際上一部分只是計數規則不同。

查詢 3：Money 符號的內部結構

Dart extension type 是相對新的特性、tree-sitter grammar 對它的支援深度不一。serena 走 LSP 直接拿到 dart analysis_server 對 extension type 的完整解析。

對需要「列出某 class / extension 所有 member」的場景、serena 是 Dart 上 LSP 級精度最可信的選項（其他 MCP 在 Dart extension type 上做不到完整 member 列舉）。

查詢 4：概念性搜尋「金額顯示」相關函式

對「我不知道精確名稱、只記得功能類別」這種 query：

前 4 名兩邊都抓到核心 formatAmount 實作，第 5 名後分歧明顯：

• cbm 補進的 getBalanceDisplay / _buildPriceDisplay / connectExternalDisplay 都跟「金額顯示」概念相關（顯示金額 / 顯示餘額 / 外接顯示器）
• codegraph 補進的 displayName / displayTags 只是符號名含 “display” 子字串、跟金額無關

差異來源是 cbm 的 11-signal scoring + cbm_camel_split 對 camelCase 切詞做語意切分（getMoneyField → get + money + field）。codegraph 的 search 是 symbol pattern match、沒對自然語言 query 做語意處理。

這題的判讀很關鍵——cbm 在「找東西」的角色不能被 codegraph 取代。即使 codegraph 在 Dart 上有可用的 call graph、它的 search 仍然贏不了 cbm 的概念性 query。

查詢 5：Money 的 impact 範圍 / cross-symbol trace

Money 是該專案大量使用的 value object、實際被使用的檔案橫跨 receipt_data 實作、settlement、cart_item、order_dto 等業務模組。codegraph 只回 1 個檔案 5 個 symbol、嚴重低估 blast radius。

漏掉的原因跟查詢 1 同源——something.multiplyByRate(...)、Money 在 factory 內被隱式構造這些都不在 tree-sitter 能解的範圍。MoneyFieldRenderer 之所以被抓到、是因為它的 field 顯式宣告為 Money，這是少數 tree-sitter syntactic 能抓的場合。

對 cross-symbol trace：

1codegraph_trace(from: "Money/multiplyByRate", to: "ProductSpecification")
2→ "No direct path"、建議跳到 dynamic dispatch

graph 上根本沒這條 edge（漏掉的 product.dart 那 3 個 callsite 正是這條 trace 的關鍵跳）、所以 trace 直接失敗。

判讀訊號：重要 refactor 不能單看 codegraph 的 impact 數字。要走 serena find_referencing_symbols 二次確認；對 cbm 不在 hybrid resolution 名單的語言、blast radius 必須用 LSP 工具驗證。

三刀流工作流

實測結論：cbm / codegraph / serena 各有不可替代的角色，組合使用才是 Dart 主力專案的合理 stack。

 1找東西（不知道精確名稱、概念性 query）
 2  → cbm search_graph(query="...")           ← 11-signal scoring 對概念性 query 最強
 3
 4知道精確名稱、找 caller / callee
 5  → codegraph_callers / codegraph_callees   ← auto-sync 2s 反應最快
 6  ↓
 7  發現結果可能不完整（type-inferred dispatch 多的場合）
 8  → serena find_referencing_symbols         ← LSP 完整精度補位
 9
10重要 refactor 確認 blast radius
11  → serena find_referencing_symbols         ← 不能單靠 codegraph_impact
12
13符號層級的編輯
14  → serena replace_symbol_body / rename     ← symbol-level atomic edit
15
16跨 service HTTP/RPC 鏈接（若 monorepo 含 client + server）
17  → cbm HTTP_CALLS edge                     ← 三個工具中只有 cbm 有這層

幾個關鍵的判讀原則：

入口跟出口要分清楚：cbm 是「廣度索引 + 模糊搜尋」的入口、拿到 qualified name 後轉給 serena 做精確查詢與編輯。codegraph 補在中間、做日常結構查詢。

重要 refactor 必走 serena 補位：codegraph 的 caller / impact 在 Dart 上系統性偏低、不能單看數字判斷影響範圍。決定 rename 或大幅修改 method 之前、用 serena 跑一次 find_referencing_symbols 對齊。

Hook 不要打架：cbm 會寫 PreToolUse hook 攔截 Grep / Glob / Read / Search（README 描述只擋前兩者、實裝版本含 Read / Search）、codegraph / serena 都不寫 hook。同時用三個工具時、注意 cbm hook 是否誤判把正常的 markdown grep 也擋掉（實測有 false positive）。

對其他語言 stack 怎麼變化

這個三刀流結論限定 Dart。不同語言 stack 的真實壓力不一樣、推薦組合也跟著變——把幾個常見 stack 各自展開。

Go / TypeScript / C / C++ 主力

這層是 cbm 的甜蜜點：hybrid type resolution 涵蓋這四個語族、CALLS edge 抽得到、cbm 的 caller / blast radius 精度接近 LSP。實務影響是「cbm 在 Dart 上需要 codegraph + serena 補位」的場景大幅縮小——cbm 自己就能處理 caller / impact、加上它原本就強的 11-signal 概念搜尋跟跨 service HTTP_CALLS，等於一個工具撐住「找東西」「caller / impact」「cross-service」三層。

serena 在這個 stack 仍是 symbol-level edit 跟 compile diagnostic 的關鍵來源——cbm 純讀、沒 rename / replace_symbol_body、沒 LSP 診斷整合。所以合理組合是「cbm + serena 雙刀流」、codegraph 的角色被 cbm 取代掉。判讀訊號：在自家 repo 跑 cbm trace_call_path 對 5 個熱門 class、若 caller 數跟 serena 的 find_referencing_symbols 對得上、codegraph 確實可以省下。

Swift / Kotlin / Rust 主力

這層跟 Dart 場景結構接近：serena 透過 sourcekit-lsp / kotlin-language-server / rust-analyzer 能拿到完整型別解析、cbm 不在 hybrid resolution 名單只剩純 syntactic。所以「三刀流」的論證仍適用。

但 codegraph 在這三個語言的 query 品質要實測——19+ 列表內這幾個都列為 supported、實際解析深度因語言成熟度而異。Swift 特別容易踩坑的點是 Objective-C interop（dispatch table 跨語言）跟 protocol extension 的型別推斷、Kotlin 則是 reified generics 跟 inline function、Rust 是 trait method 跟 macro 展開後的 callsite。判讀訊號：對自家專案最常用的 dispatch pattern 寫一個 minimal example、跑 codegraph callers、看抓不抓得到。

Python 主力

三個工具的 Python 支援都成熟、但著力點不同：cbm 對 Python 有完整 hybrid resolution、codegraph 對 Python 是核心支援語言之一（VS Code benchmark 在它的 7 codebase 列表內）、serena 透過 pyright / pylsp 拿型別資訊。

Python 的特殊壓力是 dynamic dispatch（duck typing / monkey patching / metaclass / getattr）——這層任何 static 工具都會漏。判讀訊號：對自家 codebase 跑「找 X class 的所有 method 呼叫」、若大量真實 callsite 在 type annotation 缺失的位置、所有工具都只能給 lower bound。實務組合多半雙刀（codegraph + serena）夠用、cbm 對 Python 的不可替代價值在 cross-service HTTP_CALLS（Django / FastAPI 跨 service 場景）。

冷門語言 / DSL（Liquid / Pascal / Svelte template 等）

這層 serena 多半沒 LSP 可借（除非自備 server）、cbm 純 syntactic（hybrid 名單外）、codegraph 是少數仍有 query 的工具——但 query 品質要看 codegraph 對該語言投入多深、Pascal / Delphi / Liquid 這類列表末段的支援度可能只到 symbol 抽取、callsite 不一定有。

實務上對這層語言、退回 grep + codegraph 比強推三刀流合理——caller / impact 用 codegraph 試、不夠就 grep 補、別期待 LSP 級精度。判讀訊號：若 codegraph status 顯示 indexed file 多但 edges 數明顯偏低（< 1 條 edge per file）、call graph 多半沒抽起來、視同純 syntactic 工具用。

共通的評估方法

無論哪個 stack、第一次裝 MCP 前在自家 repo 跑「找重要 class / function 的所有 caller」這個基準題、把不同工具的數字並列比較、再決定組合。README benchmark 是行銷數字、自家 stack 跑出的數字才是真實 baseline。

評估新 MCP 工具的 checklist

從這次踩三個（含一個跳過實裝的 GitNexus）的經驗回推、未來評估新 code intelligence MCP 要先確認：

License：商業專案要 MIT / Apache 2.0 / BSD。PolyForm Noncommercial 之類限制商業使用的 license 直接刷掉。這條最便宜、最早做、最少人記得做。

目標語言的 call graph 支援：README 寫「full support」要實測。tree-sitter wrapper 通常只到「結構抽得到」、沒到「call edge 抽得到」。同樣是「有 CALLS edge」、有 type-inferred dispatch 的 syntactic 工具跟有完整 LSP 的差距可能 2-3x callsite 數。

MCP tool 數量不等於能力：14 個 tool 不一定贏過 10 個。看 caller / impact / find_referencing_symbols 這類核心功能有沒有、品質好不好、勝過 tool 多寡。

是否會自動改 ~/.claude/ 設定：大多會。先看 install script 動了哪些檔案、能不能還原、uninstall 是否徹底（cbm uninstall 不清 hook 是踩過的坑）。

是否有 CLI 模式：有的話本 session 就能實測、不必等 Claude Code 重啟載入 MCP。CLI mode 對「驗證 baseline」特別重要——拿 CLI 結果當 ground truth、再對 MCP 結果做差異比對。

Auto-sync 機制：file watcher / git polling / 純手動 reindex 差異很大。「邊改邊問」工作流對 sync 延遲很敏感、選錯會踩到 stale graph 的事故。

結論

對 Dart 主力專案：三刀流（cbm + codegraph + serena）是合理 stack。三者擅長的事不重疊、互相補位有明確角色：

• cbm：概念性搜尋入口、跨 service HTTP/RPC 鏈接
• codegraph：日常 80% 的結構查詢、auto-sync 反應最快
• serena：型別精確 reference、symbol-level atomic edit、編譯 diagnostic

對其他語言 stack、cbm 進入 hybrid resolution 名單後組合會收斂、但 serena 的 symbol edit 跟 diagnostic 角色仍不可取代。

評估方法的更普遍結論：README benchmark 只是起點、要在自己的 stack 上跑同樣的基準題才算數。每個工具的 benchmark 都選自己擅長的語言跟 codebase、跨語言遷移結論需要重新驗證。用 5 個查詢做 baseline、把 CLI 數字當 ground truth、再對 MCP 結果做差異對比、是現階段最低成本的工具評估法。

觸發場景：實作營運端報表 API、寫了一個 freezed model 疑問來源：abstract class PeriodReportRow with _$PeriodReportRow implements ReportAmountsView 這一行包含太多陌生語法 整理目的：把「為什麼長這樣」與「是否有更好懂做法」的脈絡記錄下來、避免下次又從零開始查 本文邊界：這是一篇 work-log，目標是回溯一次具體實作中的理解成本；它不取代 freezed 官方文件，也不把某個專案的模型分層當成通用規則。

事件起點

今天在某個營運端 Flutter 專案新增週期彙總報表 API，這份報表和既有的單次作業報表共用呈現邏輯、各自有獨立的 DTO。為了讓兩個 DTO 共用 sections builder、抽了一個 ReportAmountsView 介面、讓兩邊的 *Row 都 implements 它。

寫完後盯著這行程式碼看了一下：

1@freezed
2abstract class PeriodReportRow
3    with _$PeriodReportRow
4    implements ReportAmountsView {
5  const factory PeriodReportRow({
6    required String date,
7    // ... 18 個欄位
8  }) = _PeriodReportRow;
9}

短短四行裡塞了好幾個需要分層理解的語法：abstract 為什麼能配 factory、with _$PeriodReportRow 在做什麼、_$ 這個前綴代表什麼、= _PeriodReportRow 如何接到生成類，以及為什麼要分成「我寫的 abstract」+「生成的 mixin」+「生成的具體類」三層。

這篇筆記把那次停下來查證的路徑整理成可重讀的判斷脈絡。

第一層：with 是什麼

with 是 Dart 的 mixin 語法、把另一個型別的成員「混入」當前 class。當前 class 會接上 mixin 提供的成員；如果 mixin 宣告了抽象成員，最後的具體類仍要提供實作。

三個關鍵字的差異

1abstract class PeriodReportRow
2    with _$PeriodReportRow         // ← mixin：接上生成 API surface
3    implements ReportAmountsView  // ← interface：拿到契約

extends 佔據唯一父類別位置，適合真正的 is-a 關係；implements 只拿契約，適合用型別描述能力；with 在中間，適合把一組生成或共用的成員接到 class 上。

在 freezed 中的角色

_$PeriodReportRow 是 build_runner 跑完後在 period_report_dto.freezed.dart 裡產出的 mixin，角色是把 Freezed 生成的 API surface 接到你宣告的 PeriodReportRow 門面上。

• 欄位 getter 的契約或 forwarding surface（date、grossAmount、channelA 等）
• == 和 hashCode 相關生成邏輯
• copyWith
• toString
• JSON 相關的 generated function / method 接線（取決於是否搭配 json_serializable 與 fromJson factory）

所以 abstract class PeriodReportRow with _$PeriodReportRow 在做的事是：

「我這個 class 是抽象門面，Freezed 會把生成 API 放在 _$PeriodReportRow mixin 與 _PeriodReportRow 具體類裡；門面透過 with 接上生成 surface，factory 再回傳真正持有欄位的生成類。」

這裡最容易誤解的是「mixin 等於所有實作」。在 Freezed 的常見生成模式裡，mixin 會宣告或提供部分生成成員，真正持有 final 欄位並滿足 getter 的通常是 factory 指向的 _PeriodReportRow 具體類。with _$PeriodReportRow 的價值是讓門面型別擁有一致的生成 API 形狀，而不是把每個欄位的儲存都塞進 mixin。

為什麼 freezed 用 mixin 而不是 extends

• mixin 不佔「父類別」的獨生子位置：Dart 只允許單一 extends、freezed 如果用 extends 強佔了、你就不能讓 model 繼承自己的 base class。with 可以無限疊加、給你自由度
• mixin 支援多個疊加：class Foo with A, B, C 會把 A、B、C 的方法依序混入。Freezed 利用這個語法位置，把生成 API 接到使用者宣告的門面類
• implements ReportAmountsView 在這裡剛好成立：ReportAmountsView 要求的是一組 getter 契約，而 Freezed 會讓生成的 _PeriodReportRow 具體類依照 factory 參數產生對應欄位。門面類宣告 implements，具體類回傳時提供欄位實作，所以不需要再手寫 18 個 forwarding getter

簡化的等價心智模型

 1// 你寫的：
 2abstract class PeriodReportRow
 3    with _$PeriodReportRow
 4    implements ReportAmountsView { ... }
 5
 6// 大致等於（觀念上）：
 7abstract class PeriodReportRow implements ReportAmountsView {
 8  // 門面接上 generated API surface：
 9  PeriodReportRow copyWith(...);
10}
11
12class _PeriodReportRow implements PeriodReportRow {
13  // 具體生成類持有欄位並滿足 interface getters：
14  @override final String date;
15  @override final Decimal grossAmount;
16  @override final Decimal channelA;
17  // ... 等等所有 factory 參數對應的欄位
18}

這是心智模型：with 接上 generated surface，factory = _PeriodReportRow 接到真正的資料承載類。

第二層：_$ 命名約定

第一次看到 _$PeriodReportRow 容易以為這是某個 framework 的特殊符號。實際上是兩個獨立慣例疊加的結果。

_ 和 $ 各自的角色

組合起來：

• _$PeriodReportRow → 機器產的 + 只給內部用（你不該在外部檔案引用它）
• $PeriodReportRowCopyWith → 機器產的 + 公開介面（呼叫 instance.copyWith(...) 時要看得到型別）

兩個前綴分別代表不同意圖——freezed 透過 _ 的有無、區分「實作細節」跟「公開介面」。

_$Foo 為什麼你的檔案看得到

Dart 的 library-private（_ 前綴）並非「檔案私有」、是「library 私有」。預設一個 .dart 檔就是一個 library、但 part 指令會把多個檔案併成同一個 library。

freezed model 檔案開頭那兩行：

1part 'period_report_dto.freezed.dart';
2part 'period_report_dto.g.dart';

就是在說：「這三個檔屬於同一個 library」。

結果：generated 檔裡的 _$PeriodReportRow 雖然 _ 開頭、但因為 part 連通、你的主檔還是看得見、可以 with 它。其他 import 你檔案的人就看不到、正好符合「只給內部生成檔用」的意圖。

這也是為什麼忘記寫 part 'xxx.freezed.dart'; 會編譯失敗——不是因為「找不到檔案」、是因為「_$Foo 不在同一個 library 內、外部不能引用」。

一個快速辨認方式

下次看 freezed / codegen 產出的名字、可以這樣判斷：

• _$Foo → mixin / 實作類（內部用）
• $Foo → public 介面（給外部呼叫）
• _Foo → 純內部 class（如 _PeriodReportRow 是 freezed 為你的 factory 產的具體類）
• Foo → 你自己寫的 abstract class、是門面（facade）

所以這次寫的：

1abstract class PeriodReportRow with _$PeriodReportRow implements ReportAmountsView
2//             ↑ 門面            ↑ 內部 mixin           ↑ 你定義的介面

三層責任可以被辨認：你自己寫的門面類、機器產的實作、你自己定義的契約。它不是透明抽象，因為使用者仍要看懂 part、with _$Foo 與 factory redirect 這些接線。

第三層：為什麼要這樣拆——是設計不當嗎

with _$Foo 加 part 加 abstract class 加 factory 加 _$ / $ / _ / 無前綴 四種命名……理解到這裡會自然冒出一個問題：這個拆分本身、是不是 freezed 設計不當？

我的看法：這個拆分不是 freezed 設計不當、但它確實暴露了 Dart 語言層的能力缺口。換個角度、「需要這樣拆」是症狀、不是病因——病因在語言本身。

拆分到底解決了什麼問題

把那幾個元素還原成「想做的事 vs 不得不這樣寫」：

前 3 行是真實需求；最後一行是「為了實現前 3 行、Dart 缺工具、所以要組裝」。

對比其他語言處理同樣問題

1// Kotlin —— 語言內建
2data class PeriodReport(val date: String, val grossAmount: BigDecimal)
3// copy、equals、hashCode、toString 全部自動、0 行 codegen

1// Rust —— derive macro 內建在語言
2#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
3struct PeriodReport { date: String, grossAmount: Decimal }

1// TypeScript —— 結構型別 + 解構即拷貝
2type PeriodReport = { date: string; grossAmount: Decimal };
3const next = { ...prev, grossAmount: newAmount };  // copyWith 不用存在

1// Swift —— struct 是值類型
2struct PeriodReport: Codable, Equatable {
3    let date: String; let grossAmount: Decimal
4}

 1// Dart 2 —— 你只能這樣寫（沒 freezed 的話）
 2class PeriodReport {
 3  final String date;
 4  final Decimal grossAmount;
 5  const PeriodReport({required this.date, required this.grossAmount});
 6  PeriodReport copyWith({String? date, Decimal? grossAmount}) =>
 7      PeriodReport(date: date ?? this.date, grossAmount: grossAmount ?? this.grossAmount);
 8  @override bool operator ==(...) => ...;
 9  @override int get hashCode => ...;
10  @override String toString() => ...;
11  factory PeriodReport.fromJson(Map<String, dynamic> json) => ...;
12  Map<String, dynamic> toJson() => ...;
13}
14// 18 個欄位 × 6 個樣板 ≈ 150 行手寫、每加一個欄位要改 5 個地方

Freezed 是在這個現實下做的工程權衡：用一個外部工具、把這上百行壓回十幾行宣告。代價就是看到的「分三層」。

Freezed 自己有沒有設計可議的地方

Freezed 的設計可議之處集中在抽象洩漏，而不是功能是否成立：

• part directive 是漏出的實作細節：使用者必須知道 library / part 的概念才能寫對。Freezed 依賴 part，是因為生成檔需要和主檔落在同一個 library，讓 _ 開頭的 generated member 可以被主檔看到
• with _$Foo 暴露了 codegen 接線：理想上 @freezed 只描述資料形狀，使用者不用知道生成 mixin 的名字。現行 codegen surface 需要使用者把生成 mixin 接上去，這就是學習成本來源
• abstract class + factory 需要語言模型支撐：abstract class 不能直接 new，但 factory 可以回傳具體子類。Freezed 產生 _PeriodReportRow，因此這個寫法在語言上成立；直覺成本來自「門面類」和「具體生成類」分離

那「設計得不當」的真正主體是誰

這個問題要拆成三層看：

1. 你的 model 設計：宣告一個 immutable DTO 並實作金額視圖契約，這個方向成立
2. Freezed 的設計：它用 codegen 換掉大量樣板，代價是 part、with _$Foo、factory redirect 這些接線露在使用者面前
3. Dart 的語言能力：Dart 長期缺少穩定的 data class / static metaprogramming 能力，讓資料模型的重複樣板需要靠 build_runner 與外部 codegen 補齊

未來改善方向不是 macros 這條直線

Dart 官方在 2025-01-29 宣布停止 macros 工作，因此「等 Dart macros 穩定後，這層拆分自然消失」已經不是可靠判斷。更務實的觀察是：Dart 仍會改善資料建模與 codegen 體驗，但方向可能是更專門的 data language features、build_runner 改善或 augmentations，而不是通用 macros。

理想中的資料模型語法可能長得像這樣：

1@Data()
2class PeriodReportRow implements ReportAmountsView {
3  final String date;
4  final Decimal grossAmount;
5  // ... 18 個欄位
6}
7// 目標是讓資料形狀、序列化、value equality、copyWith 更接近語言級宣告

這段只能當作「期待中的語言表達能力」，不能當作 Dart 已承諾的 roadmap。對今天的專案來說，Freezed 仍然是把資料模型樣板壓低的成熟工具；它的成本是 build_runner、生成檔、以及本文拆解的三層心智模型。

第四層：沒有 freezed 怎麼做

如果規劃時就決定不裝 freezed、Dart 怎麼處理「immutable + JSON + copyWith + equality」這組需求？

路線一：純手寫

把 freezed 產的東西自己寫一遍：

 1class PeriodReportRow implements ReportAmountsView {
 2  final String date;
 3  final int primaryOrderCount;
 4  final Decimal grossAmount;
 5  // ... 其他 16 個欄位
 6
 7  const PeriodReportRow({
 8    required this.date,
 9    required this.primaryOrderCount,
10    required this.grossAmount,
11    // ...
12  });
13
14  factory PeriodReportRow.fromJson(Map<String, dynamic> json) {
15    return PeriodReportRow(
16      date: json['date'] as String,
17      primaryOrderCount: json['primary_order_count'] as int,
18      grossAmount: jsonToDecimal(json['gross_amount']),
19      // ... 重複 18 次
20    );
21  }
22
23  Map<String, dynamic> toJson() => {
24        'date': date,
25        'primary_order_count': primaryOrderCount,
26        'gross_amount': grossAmount.toString(),
27        // ... 重複 18 次
28      };
29
30  PeriodReportRow copyWith({
31    String? date,
32    int? primaryOrderCount,
33    Decimal? grossAmount,
34  }) =>
35      PeriodReportRow(
36        date: date ?? this.date,
37        primaryOrderCount: primaryOrderCount ?? this.primaryOrderCount,
38        grossAmount: grossAmount ?? this.grossAmount,
39        // ... 重複 18 次
40      );
41
42  @override
43  bool operator ==(Object other) =>
44      identical(this, other) ||
45      other is PeriodReportRow &&
46          other.date == date &&
47          other.primaryOrderCount == primaryOrderCount &&
48          other.grossAmount == grossAmount;
49          // ... 重複 18 次
50
51  @override
52  int get hashCode => Object.hash(date, primaryOrderCount, grossAmount /* 18 個 */);
53
54  @override
55  String toString() => 'PeriodReportRow(date: $date, ...)';
56}

18 個欄位 × 6 個樣板 ≈ 150 行、每加一個欄位要改 5 處（constructor、fromJson、toJson、copyWith、==、hashCode）。漏改一處 → 隱性 bug。

路線二：只 codegen 序列化、其他手寫

只用 json_serializable（比 freezed 輕量很多）：

 1@JsonSerializable()
 2class PeriodReportRow {
 3  final String date;
 4  @JsonKey(name: 'primary_order_count') final int primaryOrderCount;
 5  @DecimalConverter() final Decimal grossAmount;
 6  // ...
 7
 8  const PeriodReportRow({required this.date, ...});
 9
10  factory PeriodReportRow.fromJson(Map<String, dynamic> json) =>
11      _$PeriodReportRowFromJson(json);
12  Map<String, dynamic> toJson() => _$PeriodReportRowToJson(this);
13
14  // 不寫 ==、hashCode、copyWith
15}

省掉 fromJson / toJson 的樣板（最容易出錯的部分）、但仍要自己寫 == 和 copyWith（如果需要）。

路線三：Dart 3 Records

 1typedef PeriodReportRow = ({
 2  String date,
 3  int primaryOrderCount,
 4  Decimal grossAmount,
 5  // ...
 6});
 7
 8// 建立
 9final row = (
10  date: '2026-05-11',
11  primaryOrderCount: 0,
12  grossAmount: Decimal.zero,
13  // ...
14);
15
16// 「copyWith」就是用解構重組
17final next = (
18  date: row.date,
19  grossAmount: newAmount,
20  primaryOrderCount: row.primaryOrderCount,
21  // ...
22);

Record 是 Dart 3 內建的不可變值型別，適合短距離攜帶一組值：

• 支援：自動 == / hashCode / toString
• 支援：不可變
• 限制：無名 → 不能 implements ReportAmountsView、不能加方法、不能 extends
• 限制：JSON 還是要手寫
• 限制：沒有 named constructor → 無法做「from raw API JSON」的轉換邏輯

對「跨模組共享、需要實作介面、需要 fromJson」的 DTO，record 的語意承載力不足。對「函式內部短暫的多回傳值」，record 很合適。

真正該問的問題：你需要的是哪幾項

回頭把「freezed 給你的功能」拆開看、對 DTO 真正用得到的有：

這個 DTO 情境的核心需求是 JSON 轉換與 immutable；其他能力是 Freezed 順手提供的附加價值，是否有用取決於後續資料流。

過剩功能不是壞事、但會誤導

用了 freezed 後會傾向「reach for copyWith」，因為它就在那。如果一開始只用 json_serializable，可能根本不會在 DTO 上做修改。較穩定的 DTO 用法是把 DTO 視為 API 邊界的快照；需要變更行為時，轉成 domain model 再承載狀態變化。

這次 DTO 只吃到 Freezed 的部分價值

Freezed 在 DTO 上仍有價值，尤其是 immutable、JSON 轉換接線、欄位同步與 toString 除錯。這次報表 DTO 的資料流比較單純，主要吃到的是 JSON 轉換與 immutable；copyWith、sealed union、複雜狀態轉移這些能力比較像附加值。

Domain 物件（如 ShoppingCart、Order）常有「在現有狀態上做小修改」或「多種狀態擇一」的場景，這時 copyWith 與 sealed union 更容易回收那層拆分成本。比較精確的判斷不是「Freezed 不適合 DTO」，而是「不同 model 層吃到的 Freezed 價值不同」。

第五層：更好懂的路徑是中間投影物件

重新用 WARP 看這個設計時，決策錨點不是「怎樣讓 builder 少寫一次」，而是「下一個維護者能不能快速看懂資料怎麼從後端 row 變成報表 sections」。如果這個錨點成立，讓 DTO 直接 implements ReportAmountsView 的寫法就不一定是最佳答案。

目前的做法把共用點放在 DTO 型別上。兩種報表 row 都是後端 API row，卻為了共用 _buildGeneralSections / _buildAccountSections，一起實作一個 18 個 getter 的 ReportAmountsView。這在型別上可行，但讀者要同時理解 Freezed 生成類、mixin、interface、DTO 與報表 builder，才能知道為什麼這行能編譯。

共用 builder 的三個局部方案

方案 1 是目前寫法。它的優點是 _buildGeneralSections / _buildAccountSections 可以直接共用，而且沒有額外 mapping；缺點是共用介面綁在 API DTO 上，讓「後端資料形狀」和「報表需要的共同金額視圖」混在同一層。這種寫法對熟悉 Freezed 的人不難，但對第一次接手的人，理解成本集中在一行 class 宣告上。

方案 2 是最直白的寫法。每種報表 row 用自己的 builder，讀者不用理解跨 DTO 介面；缺點是兩份 builder 很容易長得幾乎一樣。當報表欄位增加或文字調整時，維護者要記得同步兩邊，重複會變成一致性風險。

方案 3 把共用點移到更貼近需求的中間層。DTO 仍然只描述 API 回傳形狀，報表 builder 只吃 ReportAmounts，兩個 row 各自用 extension 或 mapper 明確轉成報表需要的共同資料。

 1class ReportAmounts {
 2  const ReportAmounts({
 3    required this.primaryOrderCount,
 4    required this.primaryTurnover,
 5    required this.grossAmount,
 6    // ...其餘報表需要的金額欄位
 7  });
 8
 9  final int primaryOrderCount;
10  final Decimal primaryTurnover;
11  final Decimal grossAmount;
12}
13
14extension SingleRunReportRowAmounts on SingleRunReportRow {
15  ReportAmounts toAmounts() => ReportAmounts(
16        primaryOrderCount: primaryOrderCount,
17        primaryTurnover: primaryTurnover,
18        grossAmount: grossAmount,
19      );
20}
21
22extension PeriodReportRowAmounts on PeriodReportRow {
23  ReportAmounts toAmounts() => ReportAmounts(
24        primaryOrderCount: primaryOrderCount,
25        primaryTurnover: primaryTurnover,
26        grossAmount: grossAmount,
27      );
28}

這個 mapping 看起來重複，但它是有價值的重複：它明確標出「哪些 API 欄位被投影成報表金額」。後端欄位名稱或語意改變時，維護者會在 mapper 裡看到轉換邊界，而不是在一個 18-getter interface 裡推理兩個 DTO 為什麼剛好長得一樣。

重新判斷

以好懂與好維護為核心，方案 3 比方案 1 更穩。它多寫一個 ReportAmounts 和兩份 mapping，但把複雜度放在比較合理的位置：DTO 層接 API，projection 層接報表語意，builder 層只處理畫面 / 呈現 sections。

方案 1 可以短期保留，因為它型別安全、改動小、和既有 Freezed 寫法一致。但若這段程式會長期被不同人維護，或未來還會增加其他 report row，應把 ReportAmountsView 換成明確的 ReportAmounts 投影模型。

實作落地時還有一個命名細節：如果已經從「共用介面」改成「中間投影模型」，檔名也應從 report_amounts_view.dart 改成 report_amounts.dart。否則程式碼雖然改成 projection，讀者仍會被舊的 View 命名帶回「DTO 實作介面」的心智模型。

實作後驗證

這輪實作已經把 ReportAmountsView 移除，改成 ReportAmounts 投影模型與兩個 toAmounts() extension。局部 flutter analyze 對修改檔案通過，並補了 report_amounts_test.dart 驗證兩種報表 row 的共同金額欄位投影正確。

這個驗證證明 projection 邊界在型別與欄位對應上可行，但它還沒有驗證呈現版面或實際 API response 的完整結果。後續若報表內容有差異，應回到 sections builder 或 API 欄位語意，而不是回頭讓 DTO 重新實作共用介面。

規劃有沒有瑕疵

整體判斷：使用 Freezed 本身不是瑕疵，但共用 builder 的抽象位置值得調整。

1. 工具選擇是「一致性 vs 適配度」的取捨

這類專案統一使用 freezed 的收益：

• 一致性：所有 model 一樣寫，接手者不用學兩套
• 未雨綢繆：今天 DTO 不需要 copyWith、明天可能要（例如做 optimistic update 時要短暫修改 DTO）
• 降低決策成本：不用每個 model 問「這個需要 copyWith 嗎？」

成本：

• DTO 上「邊際過剩」：用不到的功能也產出來、多花 build_runner 時間
• 抽象洩漏：使用者必須懂 _$ / part / mixin

這個取捨沒標準答案、看團隊規模和維護週期。若系統長期維護、多人接手、既有專案已經採用 Freezed、而 build_runner 成本可接受，一致性的價值通常會高於 DTO 上的邊際過剩。

2. DTO 與 domain model 兩層分離仍然合理

不在「用了 freezed」、而在於——是否需要 DTO 與 domain model 兩層分離？

這類專案結構：

1SingleRunReportRow（DTO、貼著 API）
2       ↓ service 轉換
3ReportSummary（domain、貼著 UI / 呈現）

兩層是分開的。這個分層有成本：

• 多寫一個 model
• 多寫一份轉換邏輯
• 多一份要維護

但價值：

• 後端改 API 欄位名 → 只動 DTO 層、domain 不受影響
• UI 要新增顯示邏輯 → 只動 domain 層、DTO 不受影響
• 呈現報表的格式可以脫離 API 變化

對長期維護、資料語意敏感的營運系統，這層分離通常值得；對短期 prototype，這層分離的維護成本可能高於收益。

3. 共用 builder 的抽象位置可能放太早

ReportAmountsView 把報表需要的共同欄位直接壓到 API DTO 上，這是目前寫法最需要檢討的地方。更清楚的分層是：DTO 先完整接住後端 row，再由 mapper 投影成 ReportAmounts，最後由 sections builder 使用這個報表模型。

這個調整不會否定 Freezed，也不會否定 DTO / domain 分層。它只是把「共同報表金額」從 API DTO interface 移到報表投影層，讓型別關係更接近讀者真正要理解的資料流。

一個反向思考

如果沒有 freezed、會怎麼做？

我猜會：

1. DTO 只用 json_serializable（最輕量）
2. domain model 手寫（反正欄位通常比 DTO 少）
3. 用 immutable 慣例但不強制（final 欄位 + 沒有 setter）

這樣寫出來會比現在少一層拆分但多一些手寫樣板。誰好誰壞、看 trade-off 什麼：

結論

1. 「拆」是 Freezed 在 Dart 現有 codegen surface 下的工程妥協：它用三層結構換掉大量手寫樣板
2. with _$Foo 和 part 是漏出的實作細節：使用者需要理解 library、mixin、factory redirect，才能讀懂 Freezed 生成模型
3. 不同 model 層吃到的 Freezed 價值不同：DTO 常吃到 immutable / JSON / 欄位同步，domain model 更容易吃到 copyWith / union / 狀態轉移能力；統一用法換來的一致性，在長期維護的專案上可能值得
4. Dart macros 不是可期待的解法路線：官方已停止 macros 工作，後續改善更可能來自 data features、build_runner 或 augmentations
5. 真正要檢討的是分層邊界：DTO 與 domain model 分離是否值得，比 with _$Foo 本身更接近架構決策
6. 目前 implements ReportAmountsView 可行但不一定最好懂：若核心目標是長期維護，ReportAmounts 投影模型通常比讓 API DTO 直接實作共用介面更清楚；落地時連檔名也要改成 projection 命名，避免舊抽象殘留

換個角度說：當你寫 with _$PeriodReportRow 時，你是在接受一個 codegen 工具的心智模型，用它補上資料類型在手寫 Dart 裡會產生的大量樣板。

附錄：今日實作中相關的設計決策

這次新增週期彙總報表 API 時，面對的關鍵設計選擇是「沿用既有 row、還是新增一個獨立 row」。

當下選擇了新增，然後抽 ReportAmountsView 介面共用 sections builder。這個決策當時在 A/B/C 三個選項裡合理，但重新用「好懂、好維護」作為錨點審查後，應該補上第四個選項：

選項 A 的主要問題是型別會說謊。既有 row 有單次作業、操作者、時間等語意，新的 row 是跨作業週期彙總；把兩種欄位塞進同一個 row，會讓 optional 欄位承擔太多語意分支。

選項 B 的主要問題是同步成本。它最容易讀，但如果兩種報表的 sections 幾乎一致，後續調整顯示項目時就要維護兩份相似邏輯。

選項 C 是當下採用的路徑。ReportAmountsView 只覆蓋「金額部分」、操作者 / 作業週期 / 日期等識別欄位刻意留給各自的 row 自管，避免介面變成 god interface；但它也讓 API DTO 直接承擔報表共用介面，讀者必須理解 Freezed 的門面類、generated mixin 與具體生成類。

選項 D 是重新審查後更好的候選。它保留兩種報表 row 各自獨立，也保留 sections builder 共用，但把共用點移到 ReportAmounts 這個報表投影模型。這樣多寫的 mapping 是刻意暴露資料轉換邊界，而不是無效樣板。

因此，本文更新後的判斷是：當下選 C 可以理解，但若要讓程式碼更好懂、更好維護，實作上應改成 D。

參考資料

• freezed 套件
• Dart language tour - Mixins
• Dart language tour - Libraries and imports
• Dart Blog - An update on Dart macros & data serialization
• Dart Records
• 既有的 freezed 選型評估筆記

事故類型：cross-file 狀態污染、dart test runner 同 process 共用 GetX 症狀：flutter test 約 50% 機率隨機失敗、每次失敗的 test 不固定；單獨跑該 test file 100% 通過 根因：dart test runner 在同 process 內跑多個 test file 共用 GetX 容器；前面 file 的 setUp 留下殘留（測試 mode 旗標、未 dispose 的 controller、stream subscription）污染後面 file 的測試環境

事故場景

表面症狀

跑 flutter test 全 suite，Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail。看到的失敗訊息類似：

100:27 +125: PrintCenter 廚房印表機管理 kitchenPrinter 向後兼容取第一台 - did not complete [E]
200:27 +125: PrintCenter 廚房印表機管理 重複呼叫 initFakeKitchenPrinters 會清除舊的 - did not complete [E]
300:27 +125: Some tests failed.

訊息直接點名 PrintCenter 廚房印表機管理 group 的兩個 test「did not complete」。直覺反應：那兩個 test 有問題、去看那個 file。

第一次診斷與失敗的修法

打開 online_order_print_handler_test.dart，看到 PrintCenter 廚房印表機管理 group 的 setUp 沒做 Get.reset()、純粹依賴 outer setUp 的 Get.reset()。判斷可能是 outer setUp 的 OnlineOrderPrintHandler.onInit 在這個 group 留下副作用（stream subscription 之類），於是給這個 group 加自己的 reset：

 1group('PrintCenter 廚房印表機管理', () {
 2  late PrintCenter printCenter;
 3
 4  setUp(() {
 5    Get.reset();  // ← 加這行隔離 outer setUp 的副作用
 6    printCenter = PrintCenter(FakePrinterAdapter('main'));
 7    Get.put(printCenter);
 8  });
 9
10  tearDown(() {
11    Get.reset();  // ← 加這行確保不殘留
12  });
13});

跑 5 次：Run 1 fail、Run 2 pass、Run 3 pass、Run 4 fail、Run 5 fail——flakiness 比例沒改變。

修錯了。

重新診斷：看 +N -1 計數的真正位置

把 fail 輸出存進檔案、仔細看 progress line 的 +N -1 部分：

100:08 +125 -1: ... auto_service_config_test.dart: ...
200:08 +126 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity searchedOrder 變更：badge 立即更新（list 與 selected 都沒命中時）
300:08 +127 -1: ... auto_service_config_test.dart: ...

-1 在第 126 個 test 才第一次出現——失敗的不是 print handler，是中間夾的 widget test。再看另一次 fail：

100:09 +124 -1: ... settle_page_order_object_test.dart: SettlePage.orderObject reactivity orderList[i] 替換：badge 從「已完成」立即變「退貨」

不同 run 失敗的 test 不一樣，但都是 settle_page_order_object_test.dart 的不同 case。print handler 的 did not complete 是被牽連、不是源頭。

確認 root cause：單獨跑全綠

把 widget test 單獨重複跑 8 次：

1for i in 1 2 3 4 5 6 7 8; do
2  flutter test test/widgets/settle_page_order_object_test.dart 2>&1 | tail -1
3done

8/8 全綠。單獨跑沒問題、混進全 suite 跑就 flaky——這是 cross-file pollution 的固定特徵。

為什麼 did not complete 訊息會誤導

dart test runner 的失敗訊息設計上有個盲點：

• +N 是累計通過數
• -N 是累計失敗數
• did not complete 是某個 test 還沒跑完整體就終止了（process 退出 / 超時 / 前面有未捕捉錯誤導致 runner 提前結束）

當前面有 test 失敗、後面的 test 沒機會跑、這些後面的 test 會印 did not complete——但它們本身沒問題。看到 did not complete 直覺會想「這個 test 卡住了」、但真實意思更接近「這個 test 還沒跑、上游已掛」。

正確的診斷流程：

1. 找 -N 第一次出現的位置（-1 表示第一個失敗）
2. 對照那一行的 test 名稱、那才是真正失敗的源頭
3. did not complete 出現的 test 通常只是受牽連

我第一次掉的坑：直接讀 did not complete 的 test 名、跳過了「往前找 -1 第一次出現」這步。

為什麼 cross-file 會污染：dart test runner 與 GetX 的不對齊

dart test runner 的執行模型

flutter test（背後是 dart test）跑全 suite 時不一定 1 file = 1 isolate。預設行為：

• 多個 test file 可能共用同一個 isolate / Dart VM
• 共用 isolate 等於共用所有 process-scoped state（static field、singleton、未 GC 的全域物件）

並發策略受 --concurrency 與 platform 影響、行為不固定，但「共用 process」是日常常見現象。

GetX 的 state 是 process-scoped

GetX 的 Get.put / Get.find 把 instance 放進一個 process-global 容器。Get.reset() 清空容器、但有些東西不會被 reset：

• Get.testMode 是 static field、reset() 不動它
• 如果 instance 在 onInit 內 subscribe 了 stream（例如 BroadcastReceiveService.messages.listen）、Get.reset() 移除 instance reference 但 subscription 不會自動 cancel
• StreamController / Timer / Future.delayed 在 GetX 容器外仍然活著

實際發生的污染鏈

跑全 suite 時，假設執行順序是：

11. test/services/online_order/...      ← 最前面
22. test/widgets/settle_page_order_...   ← 中間
33. test/services/auth_service_config... ← 後面

第 1 個 file 的 setUp 若有 Get.put(SomeService())，service 在 onInit 內訂閱了 stream，就算 tearDown 跑了 Get.reset()、那條 stream subscription 仍 active。第 2 個 file 開始跑時：

• 它的 setUp 也呼叫 Get.put(...)、放進去的物件可能是 完全不同類型 ——但 GetX 容器內可能還有上一輪殘留的物件
• 第 2 個 file 的 widget test 進入 widget tree、Obx 訂閱、各種 reactive 路徑啟動
• 上一輪殘留的 stream / timer 此時 fire、進到不該觸及的 state

整個 race 在「殘留事件何時 fire vs widget test 何時 expect」之間，所以 flakiness 是 ~50% 而不是 100%。

解法：setUp 開頭主動 reset

對任何用 GetX 的 test，setUp 最開頭就該 reset、不要依賴上一個 file 的 tearDown 跑乾淨：

 1setUp(() {
 2  // 同 process 內跑全 suite 時其他 test file 可能在 GetX 容器留殘留
 3  // （Get.testMode、未 dispose 的 controller、未 cancel 的 stream subscription），
 4  // setUp 開頭主動 reset 切斷 cross-file 污染
 5  Get.reset();
 6  Get.testMode = true;
 7  // ... 之後再 Get.put 自己需要的東西
 8});
 9
10tearDown(() {
11  Get.reset();
12});

把這個 pattern 加到所有 widget test 與 controller test 的 setUp 之後，全 suite 連跑 5 次：

1Run 1: All tests passed!
2Run 2: All tests passed!
3Run 3: All tests passed!
4Run 4: All tests passed!
5Run 5: All tests passed!

5/5 全綠，flakiness 消失。

為什麼 tearDown 的 reset 不夠

理論上 tearDown 已經 Get.reset() 了，下個 test 的 setUp 看到的應該是乾淨容器——但這個推理在「同 file 內」成立、跨 file 不成立：

• 跨 file 之間 dart test runner 在 file 邊界做的事是不確定的（可能整個 isolate 重啟、也可能只是切換 group）
• 即使前一個 file 的 tearDown 跑完，跨 file 的某個 microtask / timer callback 仍可能在後一個 file 的 setUp 之前 fire
• 用 setUp 開頭的 reset 等於再保險一次、把這個邊界內的不確定性吃掉

除錯思維：flaky test 的固定診斷流程

 11. 看是不是真的 flaky
 2   - 連跑 5~10 次、計算成功率
 3   - 隨機失敗（不是 100% 也不是 0%）→ 進入 flaky 診斷
 4
 52. 找真正的失敗源頭
 6   - 看 progress line `+N -M`、找 -1 第一次出現位置
 7   - 不要直接讀 "did not complete"、那是受牽連訊息
 8
 93. 判斷是 in-file 還是 cross-file 污染
10   - 失敗的 test 單獨跑：
11     - 100% 通過 → cross-file 污染（其他 file 的殘留進來）
12     - 也會隨機 fail → in-file 污染（同 file 的 test 之間互相污染）
13
144. 補對應的隔離
15   - cross-file → setUp 開頭 Get.reset()
16   - in-file → 看是 setUp/tearDown 沒清乾淨還是 test 之間共享 mutable state

教訓

1. did not complete 不是失敗源、是被牽連訊息——往前找 -1 第一次出現的位置才是真正失敗的 test。
2. 單獨跑通過 + 全 suite fail = cross-file pollution——這是 flaky test 最常見的固定模式之一、有專屬的解法（setUp reset）、不要當成「資料時序的隨機性」隨便重跑。
3. tearDown 清不夠、setUp 也要清——任何用 GetX 的 test 應該在 setUp 開頭主動 Get.reset()、不要依賴上一個 file 的 tearDown。
4. 第一次診斷錯誤是常態、要回到證據——順著 fail 訊息修是直覺反應、但訊息可能誤導；停下來看計數欄位、單獨跑驗證、才是穩定的診斷方式。

適用範圍

這個 pattern 不限於 GetX、適用於任何在 process-scoped global state 註冊東西的框架：

• Provider 的 MultiProvider / 全域 instance
• Riverpod 的 ProviderContainer（雖然 Riverpod 設計上更鼓勵 per-test container）
• 自寫的 service locator / singleton
• 任何 static field 累積的狀態

只要框架的 state 跨 test boundary 而 dart test runner 又在同 process 跑多 file，cross-file pollution 都可能發生。setUp 開頭主動 reset 是通用防身術。

參考資料

• Dart package:test runner concurrency docs
• GetX Get.reset() source
• Flutter flutter_test binding lifecycle

事故類型：潛伏型設計缺陷、第二個訂閱者出現時才暴露 症狀：Bad state: Stream has already been listened to. 根因：在「StreamController() vs StreamController.broadcast()」這個零成本差異的選擇下、選了限制更高的單訂閱版本——當下只有一個訂閱者、限制沒曝光；新增第二個訂閱者就觸發底層型別契約。設計缺陷的本質是「在零成本差異下不必要地縮小了未來空間」、不是「沒預測到後來需求」。

事故場景

業務背景：POS 的多視角狀態同步

POS 系統本質上是「單一交易狀態 + 多個視角同步呈現」。一筆購物車的變化通常要立刻反映到：

• 收銀員操作的主螢幕
• 給顧客看的副螢幕（純顯示，看商品、總價、找零）
• 廚房或後場的出餐顯示
• 列印機（結帳當下觸發）
• 雲端同步、報表、會員紀錄

這些視角各自關心交易狀態的不同切面，但都需要在狀態變動的當下被通知。在系統設計上，這是個典型的「一個資料源、多個訂閱者」場景，本質就是事件廣播。

原始設計：一個事件來源，一個訂閱者

實作初期，「需要訂閱購物車變動」的角色只有一個——副螢幕。副螢幕在 app 啟動時就訂閱、整個 app 生命週期都在聽，純粹做主畫面的鏡像顯示。

於是負責提供「狀態變更通知」的 service 用了 dart:async 預設的 StreamController 對外發事件。事件 payload 設計成兩段資訊：

1. 當前完整商品列表（給副螢幕這類「鏡像當前狀態」的訂閱者用）
2. 這次變動的具體品項（移除或清空時為 null，預留給「需要知道改了哪一筆」的訂閱者）

第二段資訊當下沒人用，但 service 設計者保留了它，理由是「未來如果有訂閱者需要知道每次具體變動是什麼，不必再改介面」——一個合理的擴充性設計。

幾個月過去，這條 stream 只有副螢幕一個訂閱者，運作正常。

新需求：操作體驗優化

新需求出現：收銀員在尖峰時段連續掃商品，畫面更新太快會分不清剛剛動到的是哪一筆。如果是改價、改數量這類修改更明顯——數字突然變了，但視線焦點不在那一行就會錯過。

業務上希望：每次操作後，被改動的那一行在 UI 上有個視覺標記（高亮、邊框或角標都可），讓收銀員一眼確認剛剛動的是對的品項。標記停在最後一次操作的那行，直到下一次操作才轉移。

這個需求對應 service 已經備妥但尚未被消費的資訊——service 對外的事件 payload 從原始設計就分兩段：一段是「當前完整的商品列表」、另一段是「這次變動的具體品項」。第二段是當初為「需要追蹤單筆變動的訂閱者」預留的擴充欄位、過去幾個月一直沒被消費。新需求只要新增一個訂閱者讀這段資訊、再把它對應到 UI 上的視覺標記即可——介面不需要變動、payload 結構不需要調整、實作範圍只限於新增訂閱端。

第二個訂閱者觸發底層限制

第二個訂閱者寫好、進入收銀頁面當下就 throw：

1The following StateError was thrown building Obx(...):
2Bad state: Stream has already been listened to.

第一反應通常是「我哪裡寫錯了 / 是不是哪邊忘了 cancel」。檢查程式碼會發現新訂閱者寫得沒問題，副螢幕的訂閱也沒問題——問題在底層 stream 的型別契約：整個生命週期內只允許被 listen 一次。

這是 StreamController() 預設建構子的契約：建立的是 single-subscription stream、生命週期內最多承載一個 listener。副螢幕第一個訂閱後佔據了唯一的 listener 位置；新加第二個訂閱者直接違反契約、執行期 throw。

更深一層的觀察是設計層面的不一致：業務需求一直具備廣播語義（多個視角同步呈現）、技術選型卻是「單一管線」的工具。需求初期只有一個訂閱者讓限制沒有可見的影響、但限制一直存在於型別契約裡。第二個訂閱者只是觸發條件、不是根因。

兩種 StreamController 的核心差異

三組行為差異的程式碼驗證

1. 重複監聽

 1final c = StreamController<int>();
 2c.stream.listen(print);
 3c.stream.listen(print);
 4// 錯誤：Bad state: Stream has already been listened to.
 5
 6final b = StreamController<int>.broadcast();
 7b.stream.listen((v) => print('A: $v'));
 8b.stream.listen((v) => print('B: $v'));
 9b.add(1);
10// A: 1
11// B: 1

值得注意的不只是「不能同時兩個 listener」——單訂閱 stream 的限制是整個 lifecycle 只能 listen 一次。即使第一個 listener 已經 cancel()、再呼叫 .listen() 仍會違反契約 throw。要重新訂閱必須重建 StreamController。

對 POS 場景的意義：副螢幕服務在 app 啟動時就建立訂閱、且不會 cancel——換句話說、stream 在啟動時就把唯一的 listener 配額分配給副螢幕、之後沒有可釋出的空間。

2. 監聽前的事件處理

 1final single = StreamController<int>();
 2single.add(1);
 3single.add(2);
 4// 此時還沒有 listener
 5single.stream.listen(print);
 6single.add(3);
 7// 輸出：1, 2, 3 ← 之前的事件被 buffer，listener 接上後補送
 8
 9final broadcast = StreamController<int>.broadcast();
10broadcast.add(1);
11broadcast.add(2);
12// 此時還沒有 listener
13broadcast.stream.listen(print);
14broadcast.add(3);
15// 輸出：3 ← 監聽前的事件全部丟掉

這個差異對應用設計的影響：

• 單訂閱保證 listener 不漏接，適合「資料完整性 > 即時性」（檔案讀取、計算結果序列）
• broadcast 不保留歷史，適合「即時性 > 完整性」（UI 事件、狀態變更通知）

如果改成 broadcast 後，希望「新訂閱者進場時能拿到一次當下的狀態」（例如 controller 進場時想知道當前購物車內容），broadcast 本身做不到，要靠 service 自己保留 latest 或在新訂閱時手動 push 一次。RxDart 的 BehaviorSubject 內建這行為，純 dart:async 沒有。

對 POS 案例：sticky 高亮只關心未來變更，不在意歷史事件——broadcast 的丟棄行為跟這個語義一致、不造成資料缺失。但如果是「副螢幕鏡像當前購物車」這種需求，新副螢幕插入時若需要立即顯示當下狀態，就要在訂閱後手動 read 一次 cart.items。

3. Pause 行為（最反直覺）

1final single = StreamController<int>();
2final sub = single.stream.listen(print);
3sub.pause();
4single.add(1);  // 不會立刻送出
5sub.resume();
6// 輸出：1 ← 暫停期間的事件 resume 後補送

1final broadcast = StreamController<int>.broadcast();
2final subA = broadcast.stream.listen((v) => print('A: $v'));
3final subB = broadcast.stream.listen((v) => print('B: $v'));
4subA.pause();
5broadcast.add(1);
6// 輸出：B: 1   ← B 照收，A 暫存
7subA.resume();
8// 輸出：A: 1   ← A resume 後補回

單訂閱的 pause 等於「整條管線暫停」，上游 add 的資料堆在 controller 內部、記憶體會漲。Broadcast 是 per-listener 暫停，互不影響。

POS 的副螢幕場景如果搭配無界事件源（例如背景條碼掃描器）、用單訂閱且某條路徑沒 resume、會在 controller 內部累積未送出的事件、記憶體佔用持續上升——這是 production OOM 的常見來源之一。

設計缺陷為什麼在初期沒有可見影響

訂閱者單一時、限制處於沉默狀態

副螢幕訂閱寫在 service 啟動時、屬於 app lifetime 訂閱、沒有 cancel / 重新訂閱的情境。在這個訂閱模式下：

1. 副螢幕第一個訂閱 → 佔據 single-subscription 的「唯一 listener」配額
2. 沒有第二個訂閱方 → 違反契約的條件不會出現
3. 限制存在於型別契約裡、但沒有可見的影響

當訂閱者擴增到第二個時、這條 stream 的型別契約「整個生命週期只承載 1 個 listener」才開始產生可見的執行期影響。注意這裡描述的是「契約一直存在、只是沒有觸發違反條件」——不是「契約因為新需求才變成限制」。型別契約是當下選擇 StreamController() 時就確定的、訂閱者數量只決定它何時被觸發。

設計缺陷 vs 需求演化的分界

但「為什麼能算設計缺陷」這個問題值得停下來釐清——當下只有一個訂閱者、需求變了才需要多訂閱、這聽起來不像是「設計缺陷」、更像是「需求演化」。兩者怎麼分？

關鍵不是「有沒有預測到後來的需求」、是「當下的選擇是否在零成本差異下不必要地縮小了未來空間」：

本 case 落在第一格——StreamController() vs StreamController.broadcast() 是 11 字元差、零認知負擔、零維護成本差異。即使當下只有副螢幕一個訂閱者、選 broadcast 也沒付任何代價、卻保留了未來的彈性。寫成 single 不是「對當下需求的精確匹配」、是在零成本差異下不必要地縮小了未來空間——這才是「設計缺陷」這個詞要描述的事。

加上 POS 系統的領域先驗強烈指向「多視角同步」（主螢幕 / 副螢幕 / 廚顯 / 雲端 / 列印是教科書級的 pub-sub 場景）、選 single-subscription 等於假設「這個 service 不會有多訂閱需求」——這個假設跟領域常識矛盾、即使在當下也站不住。

「成本對稱性 / 可逆性 / 領域先驗」三軸框架的完整推導見 設計瑕疵還是避免過度設計？YAGNI 的真實適用條件——本 case 三軸都指向 broadcast、屬於 YAGNI 不適用的標準情境。

為什麼 IDE 與測試抓不到

• Dart 編譯器：型別簽章一樣（Stream<T>），編譯不會錯
• 靜態分析：dart analyze 不會警告 single-subscription 用法的潛在風險
• 單元測試：通常 mock 整條 stream，不會驗證真實 controller 是不是支援多訂閱
• Widget test：只跑單一頁面，不會同時掛多個訂閱模組
• 整合測試：理論上能抓，但成本高，多數專案在這層覆蓋稀疏

要在事前抓到，可行的方式：

• Lint rule：自訂規則檢查 StreamController() 預設用法，要求加註解說明「為何刻意不用 broadcast」
• Code review checklist：service 對外暴露 stream 時，預設假設要 broadcast，single 必須有書面理由
• 架構規範：直接禁用 raw StreamController 在 service 層，強制透過框架的廣播原語（Rx, BehaviorSubject, ValueNotifier）

修復決策過程

選項列舉

事故當下的選項：

為什麼選 A

POS 的這條 stream 語義就是「購物車狀態變更廣播」、多訂閱者本來就符合領域模型。選 B 會讓副螢幕服務變成轉發中樞、跟它「純顯示」的職責衝突。選 C 增加重複資料源、未來容易兩條 stream 不同步。選 D 雖然在架構層更一致、但 scope 過大、不是事故當下適合做的決定。

A 是改一行的 minimal fix，且修正了原本的設計缺陷而不是繞過它。

容易漏的細節：mock 也要改

Service 如果有 mock 實作（測試替身）、mock 端也要同步改成 broadcast。否則會出現「測試環境通過、production 仍然 throw」的不對齊狀況——單元測試（注入 mock）跟 production（真實 service）使用不同的 stream 契約、限制沒被測試覆蓋。

這是「測試環境與 production 配置不對齊」的典型陷阱。事故當下要把「修真實實作」「修 mock」當成同一件事的兩個必做動作，分開做就會漏。比較好的長期策略是把這個約束放進 code review checklist，或在 service 介面層加註解註明「實作不論真假都必須是 broadcast 語義」。

還要檢查：所有寫入路徑都有完整 emit

事故修復不只是改 stream 類型，還要回頭審視「事件 payload 的完整性」。

回到事故場景：事件 payload 第二段（這次變動是哪筆）原本沒人用，所以幾個寫入路徑可能根本沒傳。副螢幕只看第一段（完整列表），傳不傳第二段對它沒差。只有第二個訂閱者開始消費這段資訊時，遺漏才會暴露。

這是廣播設計的一個系統性風險：service 提供「為未來訂閱者保留」的擴充欄位時、這些欄位若沒有當下的消費者、缺漏不會在測試中浮現。第一個真正使用該欄位的訂閱者出現後、才會暴露出某些 mutation 路徑沒填寫該欄位。

修復清單：

• 把 single-subscription 改成 broadcast（真實實作 + mock 雙改）
• 審視所有寫入路徑，確保事件 payload 的每個欄位都正確填寫
• 確認第二個訂閱者的 dispose / cancel 邏輯
• 訂閱者進場時若需要「當下狀態」，要補一次直接讀取（broadcast 不保留歷史）

何時該選哪個

選 StreamController() 的情境

• 確定只有一個消費者，且這個契約被寫進文件 / 介面註解
• 需要保證每個事件都被消費（buffer 是 feature）
• 像 Future 但會發多個值：檔案讀取、HTTP response body chunks、long-running task 進度回報

選 StreamController.broadcast() 的情境

• 有多個訂閱者，或不確定未來會不會多
• 事件是「正在發生」的通知，錯過就算了（UI 事件、狀態變更廣播、event bus、application-level domain events）
• 不在意進場前的歷史事件（如果在意，自己保留 latestValue）

一個粗略的決策法

「如果某天有人想加第二個 listener，這在語義上合理嗎？」

• 合理 → 一開始就用 broadcast
• 不合理 → 用單訂閱，並在註解寫清楚為什麼

應用層的 service 通知絕大多數情境都偏向 broadcast；single-subscription 的甜蜜點在底層 I/O 或一次性 task 進度（兩者都有「單一消費者 + 不能漏接」的明確契約）。

對 POS 場景：service 對外暴露的「狀態變更通知」幾乎都落在 broadcast 區——POS 的本質就是多裝置 / 多視圖共享同一份交易狀態（主螢幕、副螢幕、廚顯、雲端、列印機）。

補救與替代方案

已有 single-subscription stream，想對外提供 broadcast

不用改 controller 類型，可以包一層：

1final singleStream = someController.stream;
2final broadcastView = singleStream.asBroadcastStream();
3
4// 對外公開 broadcastView，原本的 singleStream 內部仍是 single-subscription

asBroadcastStream() 把單訂閱當 source，對外提供 broadcast view。一旦呼叫過一次，後續訂閱者都拿這個 view。

注意：這個方法只能呼叫一次、第二次會 throw。實務上要保留回傳值在 service 內部做 cache。

想要「broadcast + 新訂閱拿最後一次值」

標準 dart:async 沒有這功能。要嘛自己實作：

 1class ReplayLastNotifier<T> {
 2  final _controller = StreamController<T>.broadcast();
 3  T? _latest;
 4
 5  Stream<T> get stream async* {
 6    if (_latest != null) yield _latest as T;
 7    yield* _controller.stream;
 8  }
 9
10  void add(T value) {
11    _latest = value;
12    _controller.add(value);
13  }
14}

要嘛用 RxDart 的 BehaviorSubject，內建這行為。POS 副螢幕鏡像場景特別適合 BehaviorSubject：副螢幕進場時就能立即看到當下購物車內容，不必等下一次變更。

Flutter 生態系的替代

純 StreamController 在 Flutter app 層比較少見，更常用的是：

如果你已經在用某個狀態管理框架，優先用框架的廣播原語，而不是 raw StreamController。StreamController 在 Flutter app 通常是底層 I/O service 才用（藍牙、socket、sensor）。

下一節對其中最常被混用的一組——raw StreamController 跟 GetX 的 Rx / .obs——做完整對比，因為這也是事故當下會考慮「是不是該整個換掉」的對象。

深入比較：raw StreamController vs GetX 的 Rx / .obs

先釐清：Rx 跟 .obs 的關係

在 GetX 裡，Rx<T> 是底層 reactive value container，.obs 是把任何值包成對應 Rx 子類的 syntax sugar：

1// 三種寫法本質等價
2final count1 = 0.obs;            // 推導為 RxInt
3final count2 = RxInt(0);         // 顯式建構特化子類
4final count3 = Rx<int>(0);       // 較少用，因為 RxInt 提供更多 operator overload
5
6count1.value++;  // RxInt 可直接用 ++
7count3.value++;  // Rx<int> 也行，但缺了 RxInt 的算術特化

.obs 對不同型別回傳不同特化子類：

特化子類的核心好處：原生語法的 mutation（+=、list add、string concat）都直接觸發 reactive 通知，不需要手動 notifyListeners() 或 add()。

結論：.obs 跟 Rx 不是兩個不同概念，是同一個機制的兩種建構寫法。後者多了型別推導與特化命名。

概念差異

相同任務的程式碼對比

任務：service 對外暴露一個整數狀態，UI 顯示它且當值變化時自動 rebuild。

 1// ===== Raw StreamController 寫法 =====
 2
 3class CounterService {
 4  int _value = 0;
 5  final _controller = StreamController<int>.broadcast();
 6
 7  int get value => _value;
 8  Stream<int> get stream => _controller.stream;
 9
10  void increment() {
11    _value++;
12    _controller.add(_value);
13  }
14
15  void dispose() => _controller.close();
16}
17
18// UI:
19StreamBuilder<int>(
20  stream: service.stream,
21  initialData: service.value,  // 不帶這個首次 build 是 null
22  builder: (context, snap) => Text('${snap.data}'),
23)

 1// ===== Rx / .obs 寫法 =====
 2
 3class CounterService extends GetxController {
 4  final value = 0.obs;
 5
 6  void increment() => value.value++;
 7
 8  // 不需要寫 dispose；Rx 隨 controller 生命週期自動清理
 9}
10
11// UI:
12Obx(() => Text('${service.value.value}'))

差異一目了然：

• 樣板量約 4-5 倍差距
• StreamController 要自己維護 latest value
• StreamController 要記得寫 dispose
• Obx 自動追蹤所有 .value 讀取，不需要手動 listen/cancel
• StreamBuilder 要處理 initialData 與 snap.data 為 null 的情境，Rx 沒這問題（永遠有值）

Rx 內部其實就是 StreamController + ValueNotifier

Rx<T> 底層用 StreamController.broadcast() 加上一個 _value 欄位。Obx widget 在 build 時開一個訂閱範圍，期間任何 .value getter 會被追蹤；build 結束後對應的 stream 訂閱自動建立，值變化時觸發 widget rebuild。

簡化心智模型：

 1class Rx<T> {
 2  T _value;
 3  final _ctrl = StreamController<T>.broadcast();
 4
 5  Rx(this._value);
 6
 7  T get value {
 8    RxInterface.proxy?.addListener(_ctrl.stream);  // Obx 注入的依賴追蹤代理
 9    return _value;
10  }
11
12  set value(T v) {
13    if (_value == v) return;  // ← 等值不觸發
14    _value = v;
15    _ctrl.add(v);
16  }
17}

（真實實作更複雜，但骨架是這樣。）

換句話說 Rx ≈ broadcast StreamController + ValueNotifier + 自動依賴追蹤 + 特化子類。理解這層之後，後面所有「Rx 為什麼這樣」的問題都能從這個本質推回去。

完整對比表格

Rx 的特殊行為與陷阱

1. 等值不觸發更新

1final name = ''.obs;
2name.value = '';     // 不觸發 listener（'' == ''）
3name.value = 'A';    // 觸發
4name.value = 'A';    // 不觸發（'A' == 'A'）

如果需要「每次 set 都觸發」（例如重新打 API 不管值有沒有變），用 .refresh() 或 .trigger()：

1name.refresh();              // 強制通知所有 listener，不變更 value
2name.trigger('A');           // 強制通知，且 set value

2. 物件內部變動不觸發

1final user = User(name: 'A').obs;
2user.value.name = 'B';                         // 不觸發，reference 沒變
3user.refresh();                                // 強制觸發
4user.value = user.value.copyWith(name: 'B');   // 換新 reference 自然觸發

這跟 immutable 風格（Freezed、Equatable）配合最自然，copyWith 一定產出新 reference。

3. Obx 必須讀到至少一個 .value

1Obx(() => Text('hello'))                  // warning: improper use
2Obx(() => Text('${counter.value}'))       // 正確

Obx 靠 build 期間攔截 .value getter 建立訂閱關係，build callback 內完全沒讀任何 Rx 就不知道要 subscribe 誰。

4. RxList / RxMap 的 mutation 規則

1final items = <int>[].obs;
2items.add(1);          // 觸發（RxList 重寫了 add）
3items.value.add(2);    // 不觸發（操作的是底層 List）
4items[0] = 99;         // 觸發（RxList 重寫了 []=）
5items.refresh();       // 補救

特化集合類別重寫了 add/remove/[]=/clear 等 method 讓它們自動 emit；繞過 wrapper 直接操作 .value 就會跳過這層。

5. .obs 推導出的特化型別可能不是你想要的

1final list = [1, 2, 3].obs;        // RxList<int>
2final list2 = <num>[1, 2, 3].obs;  // RxList<num> — 注意泛型推導
3
4// 自定義型別需明確
5final user = User(name: 'A').obs;  // Rx<User>，不是「RxUser」

Rx 的 worker 類型（service 之間的訂閱模式）

Obx 是 widget 自動訂閱；service 內或 controller 之間的訂閱用 worker：

 1// 每次變化都觸發
 2final disposer = ever(counter, (value) => print('changed to $value'));
 3
 4// debounce — 連續變化只取最後一次
 5debounce(
 6  searchText,
 7  (value) => searchAPI(value),
 8  time: Duration(milliseconds: 500),
 9);
10
11// throttle — 固定間隔最多觸發一次
12interval(
13  scrollPosition,
14  (value) => analytics(value),
15  time: Duration(seconds: 1),
16);
17
18// 只觸發一次後自動移除
19once(loginState, (value) => navigateHome());
20
21// 監聽多個 Rx，任一變動就觸發
22everAll([a, b, c], (_) => recompute());
23
24// 手動清理
25disposer.dispose();

這些 worker 在 GetxController.onInit 裡註冊時會被綁定到 controller 生命週期，controller dispose 時自動清；在 controller 外註冊就要自己 .dispose()。

何時選哪個

選 raw StreamController

• 寫底層 service（藍牙、socket、sensor、background isolate 通訊）
• 需要豐富的 stream operators 鏈（map/where/buffer/distinct/merge/combineLatest…）
• 對外提供的 API 不想綁特定狀態管理框架，要保持框架中立
• 需要 backpressure / pause-resume 等進階流量控制
• 跨 isolate 資料傳遞

選 Rx / .obs

• 寫 UI state 或 application state
• 已在用 GetX，沿用一致
• 需要「保留當前值 + 多訂閱者」這個常見組合
• 想要 widget 自動追蹤，不想手動寫 listen/cancel
• service 內部 latest value 與通知的樣板太多次，懶得繼續寫

把事故場景改寫成 Rx 看看

回到事故場景。如果 service 從一開始就用 reactive value container（如 Rx）來表達它的對外契約，整個問題會以另一種方式消失。

對外契約的轉變：service 不再「對外發送事件」，而是「對外暴露兩個可被觀察的狀態屬性」——當前完整的商品列表、最後一次變動的品項。訂閱方不需要 listen() 一條 stream，而是直接讀取屬性的當前值，並且系統保證屬性變化時觀察者會被通知。

在這個契約下回頭看每個訂閱方的需求：

• 副螢幕（鏡像當前商品列表）：只關心「列表屬性」變動，不在乎是哪一筆變動。它建立一個對列表屬性的觀察，每次變動就重畫
• 收銀主畫面（最後變更項標記）：只關心「最後變動屬性」，每次變動就更新高亮哪一行
• 未來的訂閱方（KDS、列印、雲端、analytics）：各自選關心的屬性建立觀察

兩個訂閱者觀察的是不同屬性，互不干擾；同一個屬性也允許多個觀察者（reactive value 天生是廣播語義）。

事故的兩個技術問題在這個契約下自動消失：

1. single vs broadcast 的選擇問題不存在——reactive value 沒有「單訂閱版本」，每個觀察者天生並存
2. 進場拿不到歷史事件的問題不存在——觀察者進場時可以直接讀屬性的「當前值」，不必等下一次變動

更深一層的觀察：raw stream 是「以時間軸上的事件為一等公民」的工具，適合「事件本身就是有意義的（log、命令、訊息）」場景；reactive value 是「以狀態為一等公民」的工具，適合「下游關心的是當前是什麼，不是過去發生了什麼」場景。POS 多視角同步的本質是後者——副螢幕關心的是「現在購物車裡有什麼」，不是「過去 5 分鐘掃進了哪些商品的時序」。

把這個認知一般化：當業務語義是「多個視角共享當前狀態」時，工具應該是 reactive value（Rx / ValueNotifier / BehaviorSubject）；當業務語義是「事件流的時序」時，工具才是 stream。本案的根因是「業務語義（共享狀態）」跟「工具語義（事件流）」錯配；single-subscription 是錯配關係下第一個被觸發的契約限制、但即使換成 broadcast、仍會在「進場拿不到歷史事件」這個層次暴露語義錯配。

是否該全面改寫成 Rx

事故當下不該。理由：

1. scope 控制：事故修復原則是 minimal change，StreamController() → .broadcast() 一字之差就解決
2. 回歸風險：把 service 介面從 Stream<T> 改成 Rx<T>，所有訂閱方（副螢幕、UI、未來的 KDS / 雲端同步）都要改 listen 方式
3. 耦合代價：如果 service 介面原本是 framework-neutral 的（純 dart:async），改 Rx 等於把 GetX 綁進公開 API，未來要換框架成本變高
4. 測試成本：改 Rx 之後，所有針對該 service 的測試都要改 mock 方式

該重構的時機：

• 整個系統已經 implicit 綁 GetX，介面 framework-neutral 的成本沒實質效益
• 新增 service 時直接用 Rx，舊的 stream-based service 等下次大改一起換
• 發現自己重複寫「_latest + StreamController.broadcast + getter + emit + close」的樣板太多次，Rx 是現成解
• 整理技術債的專屬 sprint，可以系統性換掉

事故修復應該專注 minimal fix；架構改造是另一張單。

除錯思維

Bad state: Stream has already been listened to. 的根因落在 stream 定義端的型別契約、不在訂閱端。檢查順序：

1. 這條 stream 是 single-subscription 還是 broadcast？
   • 從定義端確認（StreamController() vs StreamController.broadcast()）、訂閱端只承載限制、看不出契約類型
2. 若是 single、選 single 的理由有書面記錄嗎？
   • 介面註解 / 設計文件有記錄 → 看理由是否仍成立
   • 沒有記錄 → 屬於「用了預設建構子、沒做選擇」、回到當下三軸判斷
3. 多訂閱在語義上合理嗎？
   • 合理 → 改 broadcast、屬於修正型別契約跟業務語義對齊
   • 不合理 → 第二個訂閱者的需求要重新設計（透過第一個 listener 轉送、或拉新 stream）

把「這條 stream 該不該支援多訂閱」做為設計階段的明確決策、判斷成本（跑三軸）落在當下、且不依賴未來需求是否實際出現。

延伸：POS 場景的多訂閱模式

POS 系統本質上就是「中央交易狀態 + 多視圖/多裝置鏡像」，是 broadcast stream 最自然的應用領域。常見訂閱者：

設計階段先假設「會有多個訂閱者」、「未來訂閱者數量會增加」、「每個訂閱者只關心事件的一部分屬性」——這正是 broadcast 的典型語義；之後新功能要訂閱、設計上會自然容納。

對應的設計建議：

1. Service 對外的事件 stream 預設 broadcast——single-subscription 視為例外、要在介面註解書面說明
2. 事件 payload 設計成 record 或 sealed class——包含「是什麼變動 + 變動的詳細資料」、讓不同訂閱者各取所需
3. 不要假設訂閱者之間的觸發順序——broadcast 的 listener 之間沒有保證順序、訂閱者要假設彼此獨立
4. 進場時若需要初始狀態、提供 currentValue getter——broadcast 不保留歷史、用 explicit getter 補這個缺口

參考資料

• Dart StreamController API doc
• Dart StreamController.broadcast constructor
• Dart Stream.asBroadcastStream method
• Dart language tour - Asynchronous programming: streams
• RxDart BehaviorSubject doc

關聯 Ticket：0.2.0-W5-007 決策結論：移除 freezed，採用 json_serializable + Equatable

我設定了一個新的需求開了一個專案，我沒有專門指定開發的框架或者細節，我只有很簡單的先建立我需求的 spec 文件，這個文件當然並不完整，我是希望先讓AI做一個 原形，我會在 prototype 符合我的需求動起來之後再介入去調整設計。

我的初始技術規範就只有我要用 flutter 去寫，所以AI就動了，但是在中間我發現 AI使用了 Freezed ，我並不喜歡在我 build 之外還要做一次 code generation 的動作，所以我就跟AI討論一次關於 Freezed 這種做法的必要性，至少在原形階段我覺得單純一點的 model 檔案沒有什麼不好，也不大會出錯，整體討論下來我選擇 捨棄 已有的 Freezed 程式碼，重構成更簡易的 版本，但是我覺得這個評估還是很有價值，所以讓AI重新整理了一次討論的內容作為備查。

1. Freezed 是什麼

Freezed 是 Dart 的自動程式碼產生（code generation）套件，專門用來幫你自動生成資料類別（data class）裡那些重複的樣板程式碼（boilerplate），包括：

• copyWith：複製一份物件，但可以只改其中幾個欄位，常用在狀態管理時產生新狀態
• == / hashCode：值相等比較（value equality），讓兩個內容相同的物件被判定為「相等」
• toString：把物件轉成易讀的字串，方便除錯
• fromJson / toJson：JSON 序列化與反序列化，搭配 json_serializable 使用，處理前後端資料交換
• 聯合型別（Union types）/ 密封類別（sealed class）：用 @freezed 的多建構子語法，實現型別安全的多態模式

解決的核心問題：Dart 的類別預設是可變的（mutable），而且比較兩個物件時只看記憶體位址是否相同（identity equality），不會比較欄位內容。如果要手刻一個有 10 個欄位的不可變資料物件（immutable value object），大約需要 80-120 行程式碼，而且每次修改欄位都要同步更動 6 個地方（欄位宣告、建構子、copyWith、==、hashCode、toJson），非常容易漏改出錯。

2. 優缺點分析

優點

缺點

3. 適用場景判斷表

4. 替代方案比較

方案 B 詳細說明（本專案推薦）

• JSON 序列化：保留 json_serializable（10 個模型仍需 fromJson / toJson），build_runner 僅用於 JSON
• Value equality：使用 Equatable 套件，繼承 Equatable 並宣告 props 即可，零 code generation
• copyWith：僅 2 個 State 類別（SessionListState、ConversationState）需要，手寫工作量極小
• Immutability：使用 final 欄位 + 命名建構子，Dart 語言層級保證

方案 D 補充說明（Dart 3 原生特性）

Dart 3.0+ 引入的原生特性可部分替代 freezed：

5. 與狀態管理框架的關係

Riverpod 的 Value Equality 機制

常見誤解：「Riverpod 需要 freezed 才能正確判斷狀態變更」。

事實釐清：

1. Dart 預設是 identity equality（比較記憶體位址）。兩個欄位完全相同的新物件，== 仍為 false
2. Riverpod 在 state = newValue 時使用 == 判斷是否通知 listener rebuild。相同則不通知
3. Riverpod 本身不做任何額外 equality 優化，完全依賴物件自身的 == 運算子

此專案的實際影響

在本專案中，不使用 value equality 的影響極小：

結論：Equatable 零 code generation 即可解決 value equality 需求。在本專案場景下，甚至完全不處理也感受不到效能差異。

6. 決策流程

 1是否需要 freezed?
 2    |
 3    v
 4模型數量 > 50?
 5    +-- 是 --> 強烈建議使用 freezed
 6    +-- 否 ↓
 7    |
 8使用 union types / sealed class?
 9    +-- 大量使用 --> 建議使用 freezed（或 Dart 3 sealed class）
10    +-- 未使用 ↓
11    |
12欄位頻繁變動?
13    +-- 是 --> 建議使用 freezed（減少同步維護）
14    +-- 否 ↓
15    |
16需要深層巢狀 copyWith?
17    +-- 是 --> 建議使用 freezed
18    +-- 否 ↓
19    |
20需要 JSON 序列化?
21    +-- 是 --> json_serializable 即可
22    +-- 否 ↓
23    |
24需要 value equality?
25    +-- 是 --> Equatable 或手寫 ==
26    +-- 否 --> 完全不需要 freezed

7. 本專案評估結論

現況盤點

評估對照

決策

移除 freezed，採用方案 B：保留 json_serializable 處理 JSON 序列化，使用 Equatable 處理 value equality，手寫 copyWith（僅 2 個 State 類別）。

理由：freezed 在本專案中只用到最基礎功能（copyWith、==、JSON），全部可被更輕量的方案替代。移除後減少 build_runner 依賴範圍、消除生成檔案膨脹、降低版本耦合風險。

8. 遷移檢查清單

準備階段

• 確認所有 @freezed 類別清單（12 個）
• 備份現有生成檔案
• 確認 json_serializable 獨立使用的配置方式

資料模型遷移（10 個）

• 移除 @freezed 註解，改為 @JsonSerializable + final class
• 保留 part '*.g.dart'（json_serializable 仍需要）
• 移除 part '*.freezed.dart'
• 繼承 Equatable，宣告 props
• 手寫建構子（const 建構子 + final 欄位）
• 確認 fromJson / toJson 正常運作

UI State 遷移（2 個）

• 同上資料模型遷移步驟
• 手寫 copyWith 方法
• 確認 Riverpod 狀態更新行為正確

清理階段

• 刪除所有 .freezed.dart 生成檔案
• 從 pubspec.yaml 移除 freezed 和 freezed_annotation 依賴
• 執行 dart run build_runner build 確認 json_serializable 正常
• 執行全量測試確認無回歸
• dart analyze 0 issues

參考資源

• freezed 套件
• json_serializable 套件
• equatable 套件
• Dart 3 Patterns and Sealed Classes

Last Updated: 2026-03-26 Version: 1.0.0

2026-03，開發線上點單多廚房印表機列印功能。 寫了 28 個測試，全部通過，上實機後陸續發現四個 Bug。

發生了什麼事

功能的核心流程：

1收到追加點單
2  → 把品項分派到對應的廚房印表機
3  → 組裝收據內容（標題、品名+數量、備註等）
4  → 逐行列印
5    → 單行文字（標題、桌號）
6    → 多欄表格（品名 + 數量）

上實機後，四個 Bug 依序出現——因為它們在同一條執行路徑的不同深度，每修一個，程式才能走到下一個：

1Bug 1（印表機內部元件未初始化）
2  ↓ 修好，程式碼走得更遠
3Bug 2（品項分派邏輯錯誤，全部送到同一台）
4  ↓ 修好，兩台印表機都有被呼叫
5Bug 3（多欄表格的欄位寬度不符合規定）
6  ↓ 修好，表格列印通過驗證，繼續往下
7Bug 4（空行觸發第三方 library 的越界錯誤）

為什麼一次只能發現一個 Bug

四個 Bug 都在同一條執行路徑上，只是深度不同。程式走到第一個錯誤就中斷了，後面的都被遮蔽。

而測試沒有發現這些問題，是因為測試沒有走過這條完整路徑。

1真實路徑：  接收訂單 → 組裝收據 → 列印中心 → 表格列印/文字列印 → 印表機底層
2測試路徑：  接收訂單 → 中斷（手動構造結果，後面都沒跑）
3
4後來補了模擬元件：接收訂單 → 模擬收據產生器 → 列印中心 → 模擬印表機 → 底層
5                                  ↑
6                           但模擬的收據只有純文字行
7                           → 文字列印有被覆蓋，表格列印沒有
8                           → Bug 3, 4 仍然隱藏

這次的問題在測試覆蓋的路徑深度。

回顧：這次遇到的五個事故

1. 測試的是「手動構造的結果」，不是「程式的行為」

怎麼發現的： 實機上兩台廚房印表機只有一台收到品項，另一台完全沒動。但測試裡「品項分派邏輯」的測試案例是通過的。

怎麼找到原因的： 回頭看測試程式碼，發現測試裡的分派結果是手動寫死的，不是由分派邏輯算出來的：

1test('品名長度奇數分配到第一台', () {
2  final result = OnlineOrderPrintResult(
3    itemPrinterMapping: {'item-1': 'kitchen-2'}, // 寫死的值
4  );
5  record.applyPrintResult(result);
6  expect(record.kitchenItemPrintJobs['item-1']!.printerId, 'kitchen-2');
7});

這個測試驗證的是「把結果存進去再讀出來，資料有沒有一致」，但品項分派的程式碼從頭到尾沒有被執行過。測試名稱寫的是分派邏輯，實際測的是資料儲存。

怎麼修的： 改成從入口方法開始呼叫，讓品項分派的邏輯實際跑一遍。跑完之後 Bug 2 就出現了——分派邏輯的 fallback 條件寫錯，所有品項都被送到同一台。

2. 只測了子類別自己的方法，沒測從父類別繼承的方法

怎麼發現的： 實機上廚房印表機列印全部失敗，log 顯示內部元件未初始化的錯誤，但測試裡模擬印表機的初始化和列印測試都是通過的。

怎麼找到原因的： 比對測試和實際程式碼的呼叫路徑。測試裡呼叫的是模擬印表機自己覆寫的「送出資料」方法（改成什麼都不做），但實際列印時上層呼叫的是從父類別繼承的「組裝列印指令」方法，這個方法內部依賴一個需要初始化的元件。測試覆蓋到的方法，和實際執行路徑走到的方法不是同一個。

怎麼修的： 在測試中加入對繼承方法的測試——初始化後呼叫「組裝列印指令」確認不報錯，以及未初始化時呼叫確認會拋出錯誤。同時修正模擬印表機的初始化方法，補上內部元件的建立。

3. 斷言只檢查「有沒有」，沒檢查「對不對」

怎麼發現的： 修完 Bug 1 和 2 之後重跑測試，整合測試通過了。但看 log 發現廚房 1 和廚房 2 的列印結果都是 false（失敗），和測試通過的結果矛盾。

怎麼找到原因的： 回頭看斷言，發現寫的是 containsKey：

1expect(result.kitchenResults.containsKey('kitchen-1'), isTrue);

這個斷言只檢查「有沒有這台印表機的結果」，不管結果是成功還是失敗。列印在 try-catch 裡失敗後回傳 false，但 key 存在，所以斷言通過。

怎麼修的： 改成直接檢查值 expect(result.kitchenResults['kitchen-1'], isTrue)。改完之後測試立刻失敗，顯示列印結果確實是 false。這才發現測試環境缺少收據產生器的依賴，列印路徑在組裝收據的步驟就斷了，被 try-catch 吞掉回傳 false。

4. 模擬元件的回傳資料只覆蓋了部分分支

怎麼發現的： 修完 Bug 1、2，也修正了斷言（坑 3）之後，測試全過，列印結果也都是 true。但上實機測試時，廚房印表機仍然全部失敗，log 顯示「欄位寬度總和必須等於 12」。

怎麼找到原因的： 測試環境和實機的差異在於收據的內容。實機用的是真實的廚房收據模板，包含多欄表格（品名+數量）。測試用的是模擬的收據產生器，只回傳一行純文字：

1class FakeReceiptBuilderService extends ReceiptBuilderService {
2  Future<List<ReceiptLine>> buildReceiptLines(...) async {
3    return [ReceiptLine.singleLine(data.title)]; // 只有標題
4  }
5}

純文字走的是「文字列印」，多欄表格走的是「表格列印」——這是兩條不同的分支。模擬的資料只觸發了文字列印，表格列印從未被測試執行過。

• 純文字列印有被覆蓋 → 沒問題
• 多欄表格列印沒有被觸發 → Bug 3 仍然隱藏
• 空行列印沒有被觸發 → Bug 4 仍然隱藏

怎麼修的： 在印表機的表格列印方法中加入自動正規化，將欄位比例換算為符合 library 要求的總和 12。這是適配層的修復，所有收據模板都不需要修改。

5. 第三方 library 的地雷——前面都做對了才踩到

怎麼發現的： 修完 Bug 3 之後再上實機，廚房印表機仍然失敗，但錯誤訊息不同了——從「欄位寬度總和必須等於 12」變成「RangeError: Valid value range is empty: 0」。

怎麼找到原因的： 從 log 看到列印標題和桌號成功（兩次資料送出），在第三行（空行）就失敗了。追蹤到第三方 library 的原始碼，發現它在解析文字時會取第一個字元來判斷是否為中文字，但沒有處理空字串的情況，直接對空字串取 text[0] 導致越界。

這個問題一直存在，但之前 Bug 3 擋在前面（程式在表格列印就失敗了，走不到後面的空行列印），前三個 Bug 都修好之後，執行路徑才真正打通，觸發了這個潛在問題。

從另一個角度看，能走到 Bug 4 代表前面的修復都是有效的。

怎麼修的： 在呼叫 library 之前加了空字串的前置檢查，遇到空字串時改用換行指令代替，繞過 library 的問題。

6. try-catch 的範圍太大，把程式碼 bug 和硬體故障混在一起處理

怎麼發現的： 回顧整個除錯過程，Bug 1、3、4 都有一個共同特徵——錯誤被 try-catch 吞掉，回傳 false，沒有任何明顯的異常。在測試中，缺少依賴的情況也被同樣的 try-catch 吞掉，測試照樣通過。

怎麼找到原因的： 看列印方法的 catch 區塊：

 1Future<bool> _printKitchenReceipt(...) async {
 2  try {
 3    // 組裝收據資料
 4    // 組裝收據行
 5    // 呼叫印表機列印
 6    return true;
 7  } catch (e) {
 8    debugPrint('failed: $e');
 9    return false;
10  }
11}

catch (e) 攔截了所有錯誤，不區分類型。但這裡面混了兩種性質不同的錯誤：

• 印表機故障（連線逾時、無紙、裝置離線）→ 執行期的預期狀況，應該攔截，回傳失敗讓 UI 顯示重印按鈕
• 程式碼 bug（未初始化的元件、欄位寬度不合法、空字串越界）→ 開發階段就該被發現的問題，不應該被靜默吞掉

四個 Bug 裡有三個屬於後者，全部被同一個 catch (e) 攔住，在開發和測試階段都沒有任何異常跡象。

怎麼修的： 做了三件事：

1. 定義 PrinterException，專門代表印表機硬體/連線錯誤
2. 在列印中心（IO 邊界）把印表機拋出的 Exception 包成 PrinterException，但不攔截 Error（程式碼 bug）
3. 列印方法改為 on PrinterException catch，只處理印表機故障

改動前後的對比：

 1// 改動前：所有錯誤都被吞掉
 2try {
 3  final lines = await receiptBuilder.buildReceiptLines(data, template);  // ← 出錯也被吞
 4  await printCenter.printReceiptLines(lines: lines, printer: printer);   // ← 出錯也被吞
 5  return true;
 6} catch (e) {
 7  return false;
 8}
 9
10// 改動後：資料準備不在 try 裡，只攔截印表機錯誤
11final lines = await receiptBuilder.buildReceiptLines(data, template);  // ← 出錯直接拋出
12
13try {
14  await printCenter.printReceiptLines(lines: lines, printer: printer);
15  return true;
16} on PrinterException catch (e) {  // ← 只攔截印表機故障
17  return false;
18}

改完之後，測試裡缺少依賴的情況不再被吞掉——之前有一組測試預期列印結果是 false（因為缺收據產生器被 catch 吞掉），現在補上依賴後預期改為 true，測試驗證的是真正的列印行為。

從這次經驗歸納的測試方法

一、從呼叫路徑出發，而非從程式碼結構出發

這次犯的最大錯誤是按照「這個 class 有哪些方法」來分配測試，結果每個方法各自通過，但串在一起就出問題。後來改成按「使用者操作觸發了什麼路徑」來規劃：

 1使用者操作                    要測試的完整路徑
 2─────────                    ──────────────
 3追加點餐送出     →  handler.printAppendedOrder
 4                      → _buildItemPrinterMapping  ← 分派邏輯
 5                      → buildReceiptLines          ← 收據組裝
 6                      → printReceiptLines           ← 實際列印
 7                      → printText / printRow        ← 印表機操作
 8
 9點擊重印按鈕     →  retryItemKitchenPrint
10                      → printAppendedOrder(kitchenItemIds: {itemId})

按路徑規劃之後，每個測試案例都會走過完整的鏈路，中間環節的問題自然會被觸發。

二、整合測試與單元測試的分工

這次的六個坑裡，有四個（坑 1、3、4、6）屬於「元件之間銜接」的問題，單元測試各自通過但串接失敗。回頭看分工：

 1                    單元測試                     整合測試
 2─────────────────────────────────────────────────────────
 3測什麼？          單一方法的輸入輸出             多個元件串接的結果
 4假設什麼？        其他元件是正確的               驗證元件之間的銜接
 5能抓到什麼 Bug？  演算法邏輯錯誤                 初始化遺漏、依賴缺失、
 6                                                介面不匹配、狀態傳遞錯誤
 7本案例中          KitchenPrinterConfig           printAppendedOrder +
 8                  .handlesProduct                PrintCenter + FakePrinter +
 9                  → 匹配邏輯正確                 ReceiptBuilderService
10                                                → 端到端路徑正確

這次的經驗是：功能涉及多個元件協作時，只有單元測試是不夠的。整合測試才能抓到元件之間的銜接問題。

三、替 try-catch 設計專門的測試

try-catch 在這次經驗裡反覆出現——Bug 1、3、4 被它吞掉，坑 3 的斷言因為它而失效，坑 6 則是根本性的設計問題。

回顧後歸納的三個對策：

• 斷言成功路徑的值：不只檢查「沒拋錯」，要檢查回傳值是 true。坑 3 就是因為只檢查 key 存在，沒檢查值
• 提供完整的依賴：讓 try 區塊能完整執行，而非依賴 catch 來「通過」測試。坑 3 的根因就是缺少收據產生器
• 寫專門的失敗測試：故意製造失敗條件（如模擬印表機拋出 PrinterException），驗證錯誤處理行為符合預期

四、Fake / Mock 的設計原則

1                    Fake（假實作）               Mock（模擬物件）
2─────────────────────────────────────────────────────────
3適用場景          需要跑通完整路徑               只需驗證互動次數/參數
4本案例            FakeReceiptBuilderService      不適用（需要驗證端到端結果）
5                  FakePrinterAdapter

這次 FakePrinterAdapter 的設計漏掉了父類別繼承方法依賴的內部狀態（坑 2），FakeReceiptBuilderService 的回傳資料只覆蓋了部分分支（坑 4）。後來整理出設計 Fake 時的確認項目：

• 繼承/實作的方法中，有哪些是上層呼叫者實際會用到的？
• 這些方法依賴哪些內部狀態（如 late 變數）？
• Fake 的初始化是否正確建立了這些內部狀態？
• Fake 回傳的資料是否足以讓下游所有分支都被觸發？

之後可以改善的地方

寫測試時

• 測試應從入口方法開始驅動，讓中間的邏輯實際執行，避免手動構造中間結果
• 使用模擬子類別時，確認上層實際呼叫到的繼承方法也有被測試覆蓋
• 斷言驗證值本身，而非只驗證存在性（containsKey → 直接檢查值）
• 設計模擬元件的回傳資料時，先確認下游有哪些分支，確認回傳資料能觸發這些分支
• 回傳資料中加入邊界值——空字串、空列表等

修 Bug 時

• 修完後確認有測試會實際走到修改的程式碼，否則測試通過不代表修改生效
• 沿著執行路徑往下看——之前被擋住的程式碼現在可以執行了，那些區段可能存在未發現的問題
• 如果修改讓新的資料流入第三方 library，檢查那些資料是否有 edge case

設計 try-catch 時

• 區分「預期的執行期錯誤」和「程式碼 bug」，只攔截前者
• 定義專用的 exception 類型（如 PrinterException），在 IO 邊界包裝，上層只 catch 這個類型
• 資料準備、邏輯運算等步驟不要放在 try-catch 裡面，讓錯誤直接拋出

自我檢查清單

寫完測試後可以對照的問題：

1. 這個測試有走過真實的呼叫路徑嗎？還是只測了資料搬運？
2. 斷言是驗證「值」還是只驗證「存在」？
3. 所有依賴都有提供嗎？缺少的依賴會不會被 try-catch 吞掉？
4. 模擬子類別覆寫的方法之外，繼承的方法有被測到嗎？
5. 模擬元件回傳的資料有觸發下游的所有分支嗎？
6. 邊界值（空字串、空列表、null）有出現在測試資料中嗎？
7. try-catch 的範圍是否只包含 IO 操作？資料準備和邏輯運算是否在 try 外面？
8. 有寫反向測試（故意觸發錯誤）來確認理解了 Bug 的根因嗎？

本案例的最終測試結構

 128 tests
 2
 3無廚房印表機時的基本行為（4 tests）
 4  └── 基本的 handler 行為，不需要廚房印表機
 5
 6OnlineOrderRecord 模型（7 tests）
 7  └── 單元測試：狀態管理、applyPrintResult
 8
 9FakePrinterAdapter（6 tests）
10  ├── init / sendBytes — 基本功能
11  ├── printText after init — 驗證內部元件初始化（抓 Bug 1）
12  └── printText without init — 反向驗證
13
14KitchenPrinterConfig（2 tests）
15  └── 單元測試：品名匹配邏輯
16
17品項分派邏輯 — 整合測試（4 tests）     ← 全部重寫
18  ├── 2 台空 mapping → odd/even 分配     抓 Bug 2
19  ├── 1 台空 mapping → fallback
20  ├── 明確 mapping 優先匹配
21  └── kitchenItemIds 篩選
22  （全部透過 printAppendedOrder 驅動，有 FakeReceiptBuilderService）
23
24PrintCenter 廚房印表機管理（5 tests）
25  └── 註冊、移除、初始化、向後兼容

最終的修復