觸發場景：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 的「背景查詢書籍資料」子系統，在兩個月內走了兩輪「膨脹 → 大砍」：第一輪把大系統設計砍成一個純狀態追蹤器、第二輪把三個並存的實作版本砍回一個 疑問來源：第一輪已經用力砍過偽需求了，為什麼同一個子系統還會再膨脹一次？ 整理目的：記下兩輪膨脹各自的機制、以及「真需求 vs 偽需求」的可操作檢驗法 本文邊界：素材是該專案 v0.4.1 與 v0.5.2 的重構記錄；量化數字（874 → 250 行等）出自 log 自報、未經獨立重算，本文引用時只取數量級意義

第一輪膨脹：設計期想像出來的需求

初版的異步查詢設計把它當一個大系統做：優先級佇列、重試策略、九種事件類型、Isolate 執行、三層快取。每一項單獨看都「像是背景查詢系統該有的」。

審查砍掉它們的依據不是「以後再說」，而是逐條檢驗後發現多數能力已經有別層在做：

• 重試策略——API 實作層（GoogleBooksApiImplementation）已經處理
• 格式轉換——三層資料模型（DTO → EnrichmentData → Metadata）已經處理
• UI 非阻塞——統一 API 架構本身就是非同步的、不需要額外機制

砍完之後真需求只剩兩個：查詢狀態追蹤跟查詢取消。落地成一個 QueryTracker：一個 Map<String, SimpleQueryState>、一個 Map<String, Completer>、四個狀態值。這是第一輪的教訓形態——設計期的偽需求長得像完備性（「系統該有的都列上」），檢驗法是逐條問「這個能力在這個架構裡、已經有哪一層在負責？」答案存在，這條就是偽需求；把它做進來不只是浪費、還會製造兩層之間的職責衝突（兩層都重試 = 重試次數相乘）。

第二輪膨脹：迭代期不刪的舊版本

一個版本之後（v0.5.1），同一個子系統又膨脹了、但形態完全不同：Scanner 的查詢服務出現三個並存的實作版本（enhanced、integrated、v1）、一個 AsyncQueryManager 帶著回調地獄、查詢狀態在多個層級各自追蹤、資料所有權混亂。

這輪的成因與想像力無關——它是迭代的沉積：每次改進都新開一個版本、舊版本「先留著以防萬一」、狀態追蹤跟著每個版本各長一份。沒有人設計出這個複雜度，它是不刪除的累積結果。

第二次收縮（v0.5.2）的修法對準這個機制：BookQueryResult 成為查詢狀態的單一真相來源、BookQueryService 取代 AsyncQueryManager、三個實作統一成一個、回調改 Future。log 自報的規模：約 874 行減到約 250 行、核心類別 7 個減到 3 個、移除 12 個舊檔案；重構後的新架構測試 78 個全數通過。

兩輪機制不同、對策也不同

把兩輪並排，能看出「過度設計」這個標籤蓋住了兩種需要不同對策的問題：

第一輪的警訊出現在設計文件裡（能力清單長於操作清單）；第二輪的警訊出現在檔案系統裡（同名服務帶 enhanced / v1 / unified 後綴並存）。第二輪也解釋了「砍過一次為什麼不免疫」——第一輪的對策防的是想像，防不了沉積。

檔名後綴是第二輪的早期訊號

第二輪膨脹在檔名上留下了可 grep 的痕跡：enhanced_scanner_book_info_service、..._v1、重構後又出現 ..._unified。把版本狀態編進檔名，意味著「哪個是現役版本」這個資訊只存在人的記憶裡——三個檔案都在、都能被 import、新程式碼引用哪個全憑作者當下的認知。同專案更早的重構也清過一批同型的 _simple / _equatable 後綴。訊號的用法：檔名裡出現版本形容詞的當下，就把「刪除舊版」排進同一輪工作，而不是等它長到三個版本。

相關閱讀

• 概念地基：DDD 領域驅動設計指南 的「從操作推導領域」——真需求清單的來源是使用者操作、不是系統完備性想像
• 上游事件：兩個 domain 各自實作同一個 API service——本文的統一 API 架構正是那次架構債修正的產物，兩篇合起來是 v0.4 架構稽核的完整弧線
• 同型原則：#77「現在不決定」是合法選項——設計期對想像需求的正確處置是「延後 + 條件」、不是先做起來放
• 後續案例：一行查詢放哪、一個測試留不留——同樣是查詢層的取捨，這次的膨脹方向是「為一個 .where 開一個空殼 service」，判準是「查詢誰擁有的資料就掛給誰」

觸發場景：Flutter 書籍管理 App 的錯誤處理系統重構。起點是一套公認過度設計的系統（雙目錄、包裝器、adapters），重構目標寫得斬釘截鐵：「完全放棄複雜設計、回歸原生 Dart Exception + ErrorCode、移除 80% 程式碼、零學習成本」。三個小版本後，一個帶五個欄位、五個工廠方法、JSON 序列化的 AppException 基類完工——階層回來了 疑問來源：這是重構失敗嗎？還是「回歸原生」這個目標本身有問題？ 整理目的：記下「砍掉的實作」跟「實作回應的需求」是兩回事、以及怎麼在砍之前把兩者分開 本文邊界：素材是該專案 v0.9.0 的重構計畫與 v0.9.6 的實作記錄；效能數字（< 0.1ms、< 200 bytes）為 log 自報

被砍的東西、跟砍它的理由

舊系統的過度設計是實錘的，重構計畫列的證據都站得住：

• 雙重系統並存：兩個目錄各有一個 app_error.dart、互相依賴、責任不明
• 無資訊的欄位：StandardError 是 BusinessLogicError 的薄包裝，businessRule 欄位永遠是固定值 'LEGACY_STANDARD_ERROR'——欄位存在、但永遠同值，等於沒有這個欄位
• 解不存在問題的機能：錯誤物件的深度複製與循環參照處理、多餘的 ErrorAdapters 轉換層

新架構的設計範例極簡：一個 ErrorCode enum、幾個 implements Exception 的輕量類別，code 加 message 兩個欄位。目標指標全是刪減向的：程式碼 -80%、建立時間、記憶體、零學習成本。

三個版本後：階層原地重生

v0.9.6 交付的 AppException 長這樣：errorCode、userMessage、context、timestamp、stackTrace 五個欄位；withStackTrace、wrap 加五個分類便利工廠（validation / network / business / storage / platform）；完整的 toJson / fromJson；從 errorCode 衍生 category 與 isRecoverable。之後的版本再從它派生出五個分類子類、配上分類一致性的建構不變式。

對照 v0.9.0 的口號，這是違規；對照需求，每一個「長回來的東西」都有名有姓的消費者：

需求不死、只是換宿主。 舊系統被砍掉時、這些需求沒有跟著消失，它們安靜地等著，在新架構的第一批真實使用裡逐個把自己長回來。

這不是繞回原點——但成本可以更低

重生的版本跟舊系統不等價：沒有雙目錄、沒有薄包裝、沒有 adapters、沒有深拷貝。全砍再重長的過程實際上完成了一次需求過濾——有消費者的機能重生了、沒有的死透了。從結果看，這比在舊系統上修修補補乾淨。

但同樣的過濾有更便宜的做法：砍之前對舊系統逐機能問「這個機能有沒有真實的消費者？」——businessRule 固定值沒有（砍）、深拷貝沒有（砍）、userMessage 有 UI 在用（留、換宿主）、序列化有 Chrome Extension 在吃（留）。盤點的產物是一張「保留需求清單」，新架構從第一天就對著清單設計，不用等真實使用把需求一個個撞回來——這個專案為這輪錯誤系統遷移付出了整個中版本、幾十個子版本的 migration 工作量，其中一部分就是「長回來」的返工。

口號式目標不可驗收、需求清單可以

「回歸原生、零學習成本、砍 80%」作為重構目標的問題在驗收：v0.9.6 的 AppException 算不算違反「零學習成本」？五個工廠方法算不算「原生」？口號沒有判準，於是重生過程既沒有被擋下（沒人能說它違規）、也沒有被承認（文件仍然掛著回歸原生的旗）——方向的實質轉彎沒有留下決策記錄。

換成需求清單做目標（「錯誤系統要服務：UI 文案、跨平台序列化、分類路由；不服務：深拷貝、adapter 轉換」），每一次擴充都可以對表：在清單上、做；不在、先補清單再做。同一個結果、但每一步有據可查——這跟 VO 封裝擺盪的收束是同一個藥方：把邊界寫成決策記錄，下一任重構者才不會從自己撞到的那一面再推一次極端。

判讀徵兆

• 重構目標以口號形式出現（回歸原生、極簡、零依賴）而沒有「保留哪些需求」的清單——重生已在路上，差別只是有沒有人記錄它
• 被砍系統裡有固定值欄位、無人呼叫的轉換層——真該砍的部分，砍之前留一行「為什麼它沒有消費者」
• 新架構上線後前幾個版本連續「補回」被砍的機能——每一筆都是需求盤點的漏項，把它們補進當初缺席的清單
• 效能目標（< 0.1ms、< 200 bytes）當重構主訴求——先確認錯誤建立真的在熱路徑上，否則這是拿好量的指標代替難量的設計問題

相關閱讀

• 同專案的擺盪家族：VO 封裝擺盪——封裝政策的來回、本文是抽象層級的來回，共同根因都是邊界沒有決策記錄
• 重生後的階層怎麼運作：Exception 型別綁 ErrorCategory 的建構不變式——本文的 AppException 家族在後續版本的分類不變式實戰
• 過度設計的姊妹篇：異步查詢系統的過度設計震盪——那篇砍的多數是偽需求所以砍得掉；本文砍的混著真需求所以長回來，兩篇合起來是「砍之前先分真偽」的完整論證