這條判準值得成章，因為它跟一個直覺衝突：觀測出口的需求完全來自消費端——是 UI 框架想觀察、domain 自己沒有這個需要。「誰需要就放誰那層」的直覺會把 Stream 出口做進 presentation 的某個 service，讓 domain 保持「純淨」；本章論證這個直覺用錯了判準的位置。

案例：六個視圖、兩種補償、一個缺口

一個書庫管理 App 的 repository 是純 Future pull 介面。盤點 presentation 層讀書庫資料的六個衍生視圖，只有一個有 reactive 機制（且僅涵蓋部分路徑），其餘全靠命令式載入加補償：

根因是同一個：repository 沒有變更通知出口，六個視圖各自在圖外解「怎麼知道資料變了」這一題，解出兩種補償策略（導航返回點重載、經 EventBus——行程內的發布／訂閱事件匯流排——的 domain event 橋接）、職責交叉且涵蓋不完整。補償演進的完整記錄在 ref.watch 觀察的是 provider 圖、不是資料庫；本章從這個案例抽三層歸屬的判準。

契約層：歸屬由介面語言決定、不由需求來源決定

契約是那一行介面宣告：

1Stream<List<Book>> watchBooks();

它該放 domain repository 介面、還是該為了「不污染 domain」放外層？判準是逐一檢查簽名裡的型別屬於哪種語言：

語言標準庫的非同步原語跟 domain 的關係、和 Future 完全等價：repository 介面回 Future<List<Book>> 從來沒人覺得是洩漏，Stream 是同一個標準庫裡「多值版的 Future」、地位等同。watchBooks() 全句只用標準庫加 domain entity——它說的是 domain 的語言，放 port 所在的 domain 介面，跟 getAllBooks() 形成 pull／push 對稱。

這裡就是與直覺衝突的位置。需求從消費者出發、決定介面該不該存在；介面放哪一層、由表達語言決定。兩個問題常被壓成一個：

• 「UI 想觀察資料」是消費端需求——它回答「要不要有 watchBooks()」。介面設計本來就該從消費者需求出發，port 的形狀由呼叫方的需要定義。
• 「watchBooks() 歸誰」是歸屬問題——它由簽名語言回答。簽名說 domain 的語言，介面就是 domain 的；哪天簽名裡出現 AsyncValue<List<Book>>（框架型別），才是把消費端的語言帶進了 domain、才需要擋。

用需求來源判歸屬會兩頭錯：把說 domain 語言的介面推到外層，domain 的資料能力（「我管理的資料變了、我能告訴你」）散落到 infrastructure 或 presentation 的 service 裡；或者反過來，以「需求是 domain 相關」為由把帶框架型別的介面塞進 domain。

契約層還有一個二擇：放既有 repository 介面、還是抽獨立的查詢 port？本案放既有介面——讀需求只有「完整書單流」一條、六個視圖都能從書單流投影，為一個方法抽 port 是介面碎片化。這個「何時該抽」的判準有自己的一章：讀模型的升級判準。讀 port 一旦抽出，仍屬契約層的延伸——簽名同樣只用 domain 語言，機制層與組裝層的三分模型對它同樣適用。

語言歸屬判準處理的是「詞彙是否洩漏」這一種反對意見。DDD 文獻裡存在另一派更根本的立場：即使簽名純淨，Repository 模式在 Evans / Vernon 的原始定義裡是集合式存取，reactive 訂閱能力本質上服務查詢端、屬於讀側的關注點，不論詞彙是否純淨都不該掛在寫側 aggregate 的 repository 介面上。這個立場涉及讀寫分離的組織方式（讀 port 何時值得獨立、CQRS 階梯的升級判準），跟詞彙判準各自回答不同的問題：詞彙判準回答「語言有沒有洩漏」，讀寫分離判準回答「職責該不該分離」。本章只處理前者；後者見 讀模型的升級判準。

機制層：變更偵測是 adapter 的實作細節

機制層回答「怎麼知道資料變了」。這層的語言是 controller、資料庫 hook、交易——全是 infrastructure 詞彙，所以歸 adapter。本案的二擇：

本案選寫入點 emit：repository 在每個實際執行寫入的方法尾端發出最新書單。它的維護成本（新增寫入方法要記得掛 emit）留在單一類別內部、被測試釘住；update hook 的 false positive 則會流出去變成消費端的雜訊。關鍵的架構事實是：這整個表格的內容都不出現在契約層——選哪個、換哪個，介面簽名一個字不動。這正是三分成立的證據：機制可替換、契約穩定。

組裝層：框架型別止步的位置

組裝層把 domain 的 Stream 翻譯成框架的觀察原語。本案是 Riverpod 的 StreamProvider：

1final watchBooksProvider = StreamProvider<List<Book>>((ref) async* {
2  final repository = ref.watch(bookRepositoryProvider);
3  yield await repository.getAllBooks(); // 訂閱當下先給當前值
4  yield* repository.watchBooks();       // 再轉接後續變更
5});

StreamProvider、Ref、AsyncValue 這些框架型別在這層第一次出現、也只在這層出現。組裝層同時吸收「呈現需求」性質的行為——訂閱當下要先看到當前值，是消費端的需要、不是「變更通知」語意的一部分，所以那兩行 yield 住在這裡而非 repository 裡。組裝層的其他責任（誰插上誰、插上了沒有的證言）見 組裝層的可達性；本案的 Flutter 實作細節見 StreamProvider 包 repository watch stream。

三分總表

三列共用同一條判準：看那一層的產出用什麼語言說話。這條判準的機械性有明確範圍——它機械地回答「一個已寫好的簽名該歸哪一層」：打開簽名、逐型別問「這是誰的詞彙」，答案不依賴對「純淨」的品味爭論。它不回答「一段新行為該寫進哪一層」（如初始值那兩行 yield）——那是語意歸屬決策，要判斷行為屬於誰的語意，跟機制層選 emit 時機一樣是設計判斷、不是型別檢查。把兩者混為一談、以為整篇的歸屬都能靠型別自動判定，正是這條判準最容易被過度推廣的地方。

邊界

觀測出口通知的是「資料現在長什麼樣」；domain event 記錄的是「發生過什麼業務事實」。兩者正交、互不取代——本案落地觀測出口時，既有的事件發布點零改動。這個正交性有一個架構前提：狀態存在獨立的資料庫、事件只是旁支通知。event-sourced 架構下狀態由事件重建、沒有獨立持久化的當前值，機制層要生出 watchBooks() 只能訂閱同一條事件流做投影——那時變更偵測與 domain event 不再是兩條獨立管線、「零改動」的論證不成立。把 event 借用成刷新訊號的代價、以及兩種載體的選用判準，見 domain event 與狀態流。

下一步

三分的判準確定之後，下一個問題通常是「要不要抽讀 port」——先讀 讀模型的升級判準 再做這個決策。還沒建觀測出口、仍在用事件或導航補償的話，回頭讀 domain event 與狀態流 先確認載體選擇，確認要用狀態流再進本章。

• 補償演進與 Riverpod reactive 邊界的案例全文 → ref.watch 觀察的是 provider 圖、不是資料庫
• 機制層與組裝層的實作點（broadcast、初始值、dispose）→ StreamProvider 包 repository watch stream

這個查詢回傳的是讀的形狀、還是 aggregate 的形狀？

回傳 aggregate 形狀（entity 或 entity 集合）的查詢屬於 repository；回傳讀的形狀（統計值、扁平列表、跨 aggregate 拼裝）的查詢是讀模型的候選。問句每次新增查詢方法時問一次，答案累積起來就是五訊號的量測值。

階梯：四階與每階的代價

每一階都比上一階多買一種能力、也多付一種持續成本。第一階的能力是簡單：所有讀需求共用一條資料通路，消費端各自把 aggregate 形狀折成自己要的樣子。第二階買到介面隔離：讀需求多到 repository 介面開始臃腫時，把查詢集合抽成獨立 port，寫側介面回到精簡。第三階買到形狀與效能的自由：讀的形狀在儲存或快取層物化，查詢不再每次從 aggregate 折算。第四階買到讀寫各自極致最佳化，代價是最終一致性進入系統語意——畫面可能短暫顯示舊值、而且這是設計內行為。

階梯的方向性很重要：每一階的介面簽名對消費端穩定。從第一階爬到第二階時，查詢方法從 repository 介面遷到讀 port、簽名不變、呼叫端只改注入來源。這讓「先停在低階」是安全決策而非技術債——升級路徑不會被低階選擇堵死。

五訊號

以下五個訊號涵蓋技術與效能維度、各自獨立量測，每個訊號指向階梯上的一個目標階：訊號一指向第二階（介面隔離）、訊號二指向第三階（形狀物化）、訊號三與訊號四指向第三階（獨立快取與新鮮度分級）、訊號五指向第三到第四階（獨立演進延伸到讀寫分離）。命中越多、且指向的階越高，往上爬的理由越強。但爬幾階沒有可套的公式：本章案例只完整走過「零命中、停第一階」這一個決策，多訊號命中時的爬升幅度要按每個訊號背後的業務代價個案衡量，而不是把命中數當分數累加。技術訊號之外還有一類驅動——組織與團隊擁有權邊界——性質與這五個正交，單獨成段在五訊號之後。

訊號一：讀需求增生

專用查詢方法累積到三條以上、且形狀彼此不同（一條回統計、一條回扁平列表、一條回分頁切片），repository 介面開始為讀需求膨脹。這是「第一階 → 第二階」的典型訊號：查詢集合已經大到值得一個自己的介面。三條是硬性起點：達到三條就把「介面裡讀方法與寫方法的比例」列入下次 review 的觀察項。讀方法數量超過寫方法的兩倍時，介面已經在為讀側服務——這是這個訊號的行動門檻。

訊號二：讀的形狀偏離 aggregate 形狀

自檢問句的直接輸出。統計值（總數、分組計數）、跨 aggregate 的拼裝（書 + 借閱人 + 標籤樹的合成畫面）、為排序或搜尋而反正規化的扁平投影——這些形狀讓消費端的「自行投影」從幾行 map 長成一段業務邏輯。投影邏輯值得有自己的家（第三階），而不是散在每個 ViewModel 裡各寫一份。

訊號三：讀寫負載特性分歧

讀高頻寫低頻（商品目錄）或寫高頻讀低頻（事件記錄）到同一模型無法同時服務兩邊時，讀側需要自己的快取或儲存策略。分歧要用量測支撐——「感覺查詢很多」不是訊號，慢查詢記錄和快取命中率才是。這個訊號沒有通用閾值：「命中率低到多少該行動」由服務的 SLA 決定（電商結帳頁和內部報表的容忍度差一個數量級），量測工具對了就夠用、門檻要帶服務脈絡才有意義。

訊號四：讀側可接受的新鮮度不同

報表可以慢十分鐘、交易畫面必須即時——同一份資料的不同讀者對「多舊算舊」的答案不同時，用一個模型服務所有人會被最嚴格的需求綁架。新鮮度分級是第三、四階才買得到的能力：投影可以有自己的更新節奏。

訊號五：讀模型需要獨立演進

不同消費者要不同版本的視圖（對外 API 的公開形狀 vs 內部畫面的完整形狀）、或讀形狀的變更頻率遠高於 aggregate 本身。讀側從此有自己的版本生命週期，跟 aggregate 綁在一起只會互相拖累。

技術訊號之外：團隊與交付邊界

五個訊號涵蓋技術與效能維度。另一類常見且獨立的升級驅動是組織邊界：讀側與寫側由不同團隊擁有、需要獨立部署節奏與獨立資料契約。即使五個技術訊號全部零命中，團隊自治的壓力仍可能合理地把系統推上第三或第四階——讀側的模型、儲存、部署由另一個團隊全權管理，Conway’s Law 讓組織結構成為架構的驅動力，跟負載分歧或形狀偏離這類技術維度完全正交。本章不展開組織驅動（涉及團隊拓撲與交付流程），只在此標記它的存在：把五訊號當成升級的全部理由，會漏掉組織維度的命中。

階梯的適用範圍

四階假設在單一 bounded context 內操作。跨服務聯合讀模型（報表服務訂閱多個 domain 的事件建置共享視圖）引入的關注點——跨服務事件契約穩定性、schema 演進、跨信任邊界的最終一致性——不是「多買一種能力」可概括，超出本階梯的覆蓋範圍。

案例：停在第一階的決策

書庫管理 App 為 repository 補了觀測出口 watchBooks()（背景與三層歸屬見 觀測出口的職責三分）。落地時面對的正是本章的二擇：watchBooks() 放既有 repository 介面、還是抽一個獨立的讀 port？

用五訊號量測當時的狀態：

五訊號零命中、自檢問句答「aggregate 的形狀」——結論是停在第一階：watchBooks() 進既有 repository 介面、與 getAllBooks() 形成 pull／push 對稱，各衍生視圖在 ViewModel 層各自投影（統計頁算總數、待補完列表過濾欄位缺漏）。抽讀 port 在此刻是為一個方法建一個介面、買不到任何一階的能力、只付碎片化的成本。

決策同時綁了升級 trigger：推送型讀需求增生（專用統計投影、分頁查詢流之類累積到三條）時再抽讀 port，屆時 watchBooks() 遷入讀 port、簽名不變、呼叫端只改注入來源。「停在低階」與「記錄何時升級」是同一個決策的兩半——少了後半、低階會在訊號早已命中之後仍靠慣性維持。

判準防的兩種錯

五訊號同時防兩個方向的失誤，兩邊在真實專案都常見：

太早抽：還沒有第二條讀需求就先建讀 port、投影層、甚至讀寫分離骨架——每一層都是要餵養的抽象。訊號零命中時的高階結構，日常成本是每個新查詢都要穿過多一層介面、而買到的能力沒有消費者。

太晚抽：repository 介面長滿 getBooksGroupedByTag()、getMonthlyStatistics()、searchWithPagination()——每條都「只是加一個方法」，直到介面的讀方法數量淹過寫方法、每個 mock 都要 stub 幾十個查詢。訊號早已命中、但沒有量測動作讓命中被看見。自檢問句的價值就在這裡：它把「要不要升級」從一次性的架構辯論、變成每次加方法時的例行量測。

下一步

停在第一階之後要落地觀測出口，歸屬判準見 觀測出口的職責三分。第四階需要事件作為同步載體——載體選用判準見 domain event 與狀態流。太晚抽的日常代價（介面臃腫、mock 爆炸）有實證：mock 55 個方法只用 5 個。術語定義見 Read Model。

概念位置

read model 是 CQRS 讀寫分離的讀側，與 aggregate root 的寫側形成互補：aggregate 守一致性邊界、read model 服務讀的形狀。它的存在不以 CQRS 全套為前提——讀側是一道階梯：消費端自行投影、讀 port 抽離（獨立的 port）、專用投影、事件同步的獨立儲存，每一階都是 read model 概念的某種深度。低階的 read model 可以只是 ViewModel 裡幾行 map；高階的 read model 有自己的儲存與更新節奏，接受與寫側的最終一致性。階梯橫跨 ephemeral（ViewModel 內聯投影，沒有獨立生命週期）到 durable（獨立儲存、事件同步），但各階共享同一個設計責任——「讀的形狀由讀需求定義、不由 aggregate 形狀決定」——因此視為同一概念的深度變體。

可觀察訊號

repository 介面長出回傳統計值、分頁切片、反正規化投影的方法，是讀的形狀開始混進 aggregate 介面的訊號。反向的訊號同樣可觀察：還沒有第二條讀需求就先建投影層，抽象沒有消費者、每個新查詢多穿一層介面。

設計責任

read model 定義「讀側要什麼形狀」，升級到哪一階由訊號決定、不由架構偏好決定——五個升級訊號（讀需求增生、形狀偏離、負載分歧、新鮮度分級、獨立演進）與階梯各階的代價，教學層展開見 讀模型的升級判準。

概念位置

觀測出口的契約層是一種 port：簽名只用語言標準庫與 domain entity、放 domain repository 介面，與 pull 方法形成對稱。機制層（broadcast controller、寫入點 emit）歸 adapter；組裝層（框架 provider 包裝）歸 DI／presentation。三層歸屬的完整判準與「需求來源不決定歸屬」的推導見 觀測出口的職責三分。

可觀察訊號

repository 缺觀測出口時，每個衍生視圖各自解「怎麼知道資料變了」：導航返回點補 reload、EventBus 橋接刷新、多個視圖各自維護 load 時機。補償策略的交叉與涵蓋缺口是這個能力該補的訊號。

設計責任

觀測出口讓「資料變更」成為可訂閱的一級節點，涵蓋面等於寫入操作的集合——emit 掛在寫入方法尾端、新路徑自動涵蓋。它通知「現在是什麼」、不記錄「發生了什麼」——後者是 domain event 的責任，兩者正交。落地的實作點（broadcast、初始值、dispose）見 StreamProvider 包 repository watch stream。

概念位置

repository 預設是 pull 介面：呼叫端主動問「現在的資料長怎樣」，一次拿到一份 aggregate 形狀的答案。它不天生具備「資料變了通知我」的推送能力——這條能力屬於 observation outlet，是 repository 介面之上的另一層職責，需要另外設計才會出現。

可觀察訊號

repository 介面開始長出 getMonthlyStatistics()、searchWithPagination() 這類回傳統計值或反正規化形狀的方法，是讀的形狀混進 aggregate 介面的訊號——查詢集合已經大到值得思考該不該抽獨立的讀側介面，量測與升級路徑見 讀模型的升級判準。

設計責任

repository 的設計責任是守住 aggregate 一致性邊界的存取入口，不是最佳化每一種讀需求的效能與形狀——後者是 read model 的責任。repository 是否該同時扛下變更通知，判準不是「需求來自誰」而是介面用什麼語言表達，完整推導見 觀測出口的職責三分。

概念位置

CQRS 是一道讀側設計階梯的頂端、而非二選一的開關。讀側的設計從「消費端自行投影 aggregate 形狀」開始，中間經過「抽獨立讀 port」「查詢形狀專用投影」，到頂端才是 CQRS 全套——讀寫獨立儲存、由 domain event 同步讀模型。多數專案的正確位置在階梯低處、不是頂端，升級由訊號驅動而非架構偏好。

可觀察訊號

讀寫分離的討論從「查詢方法該不該搬出 repository」，逐漸變成「讀模型需不需要自己的儲存、能不能接受跟寫側短暫不一致」，是逼近階梯頂端的訊號——第四階的代價是最終一致性進入系統語意，畫面可能短暫顯示舊值，而這是設計內行為，不是 bug。

設計責任

要不要上 CQRS 全套，不看「這個模式聽起來很適合」，看五個具體訊號（讀需求增生、形狀偏離、負載分歧、新鮮度分級、獨立演進）是否命中——本卡只回答「CQRS 是什麼、階梯怎麼分階」，訊號的完整推導與升級路徑是 讀模型的升級判準 這篇的內容，要判斷自己的專案該停在哪一階、讀那篇。

觸發場景：書庫管理 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 進效能優化階段（UC-08）的現況盤點，抓到一個 P0：getAllBooks() 對 1000 本書發出 1001 次 SQL 查詢、耗時約 2 秒；推算 10000 本書要 20 秒、UI 完全卡死 疑問來源：沒有人寫過「對每本書查一次資料庫」這種程式碼——這個 N+1 是怎麼長出來的？ 整理目的：記下 N+1 在 ORM 之外的手寫形態（async mapper）、修法的結構、以及為什麼它在開發期永遠感覺不到 本文邊界：素材是該專案 v0.19.0 的 Phase 0 評估記錄；耗時數字是該記錄的影響評估、量級可信

形成：兩個各自合理的函式、組合出災難

問題程式碼拆開看，每一半都寫得很自然：

 1// 單筆轉換：把一列 DB map 轉成 Book——順便把它的 tags 查出來
 2Future<Book> _mapToBook(Map<String, dynamic> map) async {
 3  final db = await _database;
 4  final tagResult = await db.query('book_tags', ...);   // 每本書一次
 5  ...
 6}
 7
 8// 列表查詢：撈全部、逐筆轉換
 9Future<List<Book>> getAllBooks() async {
10  ...
11  return Future.wait(result.map((map) => _mapToBook(map)));
12}

_mapToBook 單看合理——Book 有 tags、轉換時補齊關聯是「完整的轉換」；getAllBooks 單看也合理——每筆都用同一個轉換函式、Future.wait 還做了並行。N+1 不存在於任何一行、它存在於組合：一個做 IO 的轉換函式、被一個列表方法乘以 N。

結構性的病灶是mapper 做了 IO。轉換函式的職責是「資料形狀的映射」，把查詢塞進去的那一刻，它的成本從 O(1) 記憶體操作變成一次網路 / 磁碟往返——而呼叫端從簽名上看不出來（回傳本來就是 Future、多一次 await 沒有任何警訊）。

為什麼開發期永遠感覺不到

影響評估的三個數字說明了它的隱身機制：100 本約 200ms、1000 本約 2 秒、10000 本約 20 秒。開發跟測試用的資料集是幾十本——200ms 以下、混在正常的載入時間裡無法察覺。N+1 的惡化是使用者資料量的線性函數，寫下它的人永遠不會遇到它爆炸的那天，遇到的是半年後書最多的那批使用者。

這也解釋了為什麼它由效能盤點抓到、而不是被任何測試抓到：功能測試的資料量跟開發期一樣小，而「查詢次數」不在任何斷言的守備範圍——除非專門寫「操作 X 的 SQL 次數 ≤ K」這種預算型測試。

修法：IO 上移、mapper 變純

修法的設計把查詢次數從 N+1 收斂到 2：

 1Future<List<Book>> getAllBooks() async {
 2  // 1. 一次撈所有書
 3  final books = await db.query('books', orderBy: 'added_date DESC');
 4
 5  // 2. 一次撈所有標籤（IN 批次）
 6  final bookIds = books.map((b) => b['id']).toList();
 7  final allTags = await db.query('book_tags',
 8    where: 'book_id IN (${bookIds.map((_) => '?').join(',')})',
 9    whereArgs: bookIds);
10
11  // 3. 記憶體組裝
12  final tagsByBookId = _groupTagsByBookId(allTags);
13  return books.map((b) => _mapToBookWithTags(b, tagsByBookId)).toList();
14}

結構上的重點勝過次數本身：IO 全部上移到列表方法、轉換函式變純——_mapToBookWithTags 收「這本書的列」跟「查好的 tags 索引」、不碰資料庫。純轉換函式拿回了三個性質：成本可預期（呼叫 N 次就是 N 次記憶體操作）、可單獨測試（餵 map 斷言 Book）、且結構上不可能再退化成 N+1——它沒有 db 可查。這跟 pure function 領域計算是同一個藥方在資料層的應用：IO 在邊界、計算（轉換）在核心。

伴生發現：能力早就存在、預設路徑不經過它

同一次盤點還抓到第二個 P0——allBooksProvider 直呼 getAllBooks() 全量載入、記憶體隨書量膨脹。反直覺的是修這個問題不用寫新能力：repository 早就有 getBooks(limit, offset) 分頁方法、批次新增也有、快取系統也完整。能力都在、只是 UI 的預設路徑（allBooksProvider）不經過它們。

「有能力」跟「預設路徑用它」是兩回事——provider 是所有畫面拿書的入口、它選全載、分頁能力就是死碼。這是工具的預設行為決定使用者習慣的資料層版本：要讓分頁被用、要嘛預設 provider 就是分頁的、要嘛全載入口加上明確的成本標記，靠「大家記得用分頁版」跟靠任何慣例一樣不可靠。

判讀徵兆

• mapper / 轉換函式的簽名是 async——最便宜的掃描：rg "Future<\w+> _mapTo" lib/，每個命中都問它裡面的 await 在等什麼
• 迴圈或 Future.wait 裡呼叫「單筆處理」函式、而該函式含查詢——N+1 的標準組合形
• 某操作的耗時隨資料量線性惡化、但單筆操作很快——次數問題、不是單次效能問題
• repository 有分頁 / 批次 API、但 provider / service 層的預設入口全量載入——能力與預設路徑脫節

相關閱讀

• 同藥方的領域計算版：「該收多少錢」抽成 pure function——IO 在邊界、核心保持純，資料層與領域層各一個現場
• 預設路徑的原則：工具的預設行為決定使用者習慣——分頁能力閒置的機制跟工具預設值是同一件事
• 查詢預算的守法：紅燈在量什麼——效能特性要用專門的量測管道守、不是塞計時斷言進單元測試

觸發場景：Flutter 書籍管理 App 要幫 SyncReadinessService 寫測試，mock 設置一路撞牆：四個依賴共 55 個方法要配置、漏配就 MissingStubError、mockito 的嵌套 when 又有語法限制——而這個 service 實際呼叫的方法只有 5 個 疑問來源：測試這麼難寫，是測試工具的問題、還是被測物的問題？ 整理目的：記下「mock 負擔」作為介面設計探針的判讀方式、以及 Port 介面（ISP）的落地步驟 本文邊界：素材是該專案 v0.18.6 的重構計畫（含依賴盤點數字與 wave 拆分）；Port 是 hexagonal architecture 的用語、這裡取其「消費端定義的窄介面」語意

依賴盤點：91% 的 mock 配置是浪費

寫不動測試的第一步是把依賴攤開來數。SyncReadinessService 的建構子收四個依賴，逐一盤點方法數與實際使用：

合計 55 個方法、用 5 個。mock 這個 service 的依賴，等於為 50 個永遠不會被呼叫的方法做配置決策——每個都可能漏（MissingStubError）、每個都是測試檔的噪音。ChangeTracker 更直接：10 個方法、零使用，這個依賴純粹是建構子沿著前例複製來的。

數字本身就是診斷：mock 負擔正比於介面寬度、不正比於被測物的複雜度。測試難寫的根因不在 mockito、在被測物宣告的依賴遠寬於它需要的能力。

往上追：一個 Repository、五種職責

SyncRepository 的 23 個方法拆開看是五種職責：變更記錄管理（6）、同步任務管理（6、預留給 UC-08）、衝突解決（5）、離線佇列（4、預留 UC-09）、同步統計（2、預留 UC-10）。五分之三是為未來 use case 預留的投機式方法——現在沒有人呼叫、但每個消費者都被迫認識它們。

這是介面隔離原則（ISP）教科書式的違反現場，而它的第一個受害者是測試：生產程式碼呼叫方法時不在乎介面還有幾個方法、mock 卻要面對整個介面。測試是第一個被迫「完整消費」介面的客戶，所以介面過寬的痛總是先在測試爆。

修法：消費端定義的窄介面

重構的核心動作是抽 Port——從消費者的實際需求出發定義介面、而不是從資料來源的能力出發：

 1/// 從 SyncRepository 的 23 個方法中抽取實際需要的 2 個
 2abstract class SyncQueryPort {
 3  Future<List<ChangeRecord>> getPendingChanges({int? limit});
 4  Future<List<ConflictResolution>> getPendingConflicts({int? limit});
 5}
 6
 7/// 從 BookRepository 的 16 個方法中抽取實際需要的 1 個
 8abstract class BookQueryPort {
 9  Future<List<Book>> getAllBooks();
10}

三個配套讓改動保持小：

• Repository 實作 Port、原介面不動：abstract class SyncRepository implements SyncQueryPort——既有實作自動滿足新介面、其他消費者不受影響
• Service 建構子改收 Port：依賴從 55 個方法縮到 5 個、ChangeTracker 直接移除；測試 mock 的對象變成 2 方法與 1 方法的小介面
• 預留方法標記啟用時機：// TODO(UC-08): 實際同步功能時啟用——投機式方法不刪（設計已評估過）、但每個都有名字跟啟用條件，下次盤點時「這是預留還是死碼」有據可查

值得注意方向性：Port 放在消費端的 domain 目錄（synchronization/ports/、library/ports/），因為它表達的是「這個 domain 需要什麼能力」、不是「Repository 提供什麼」。同一個 Repository 未來可以實作多個不同消費者的 Port，各自窄、互不牽連。

判讀徵兆

• mock 設置的行數超過測試本體——先數被測物依賴的介面方法數 vs 實際呼叫數
• MissingStubError 反覆出現——每一次都是「介面要求你認識的方法」跟「你實際關心的方法」的差距
• 建構子的某個依賴在整個 class 內零呼叫——複製前例的沉積、直接刪
• 介面裡一半以上的方法標著「未來會用」——預留可以，但要有 TODO 加啟用條件，否則每個消費者與 mock 永遠陪葬

「測試很難寫」在這個 case 裡是禮物：它比任何架構審查都早、都具體地量化了介面設計的問題（91% 這個數字就是證據）。把測試痛當成噪音硬吞（寫更肥的 mock helper）、跟把它當探針回頭修介面，是兩條分岔路——同專案的 mock 基礎設施過度工程正是前一條路的下場。

相關閱讀

• 概念地基：DDD 領域驅動設計指南——service 與 repository 的邊界、以及分工表裡「domain 持有的是能力需求」
• 硬吞測試痛的反面教材：1101 行自建測試基礎設施——mock 難寫的兩種回應：修介面（本文）vs 蓋更大的 mock 系統（該篇）
• 投機式預留的另一形態：過度設計震盪——那篇的迭代期沉積跟本文的預留方法同源，差別是 Port 案例的預留有 TODO 加啟用條件、不是無主地放著

觸發場景：Flutter 書籍管理 App 的資料庫整合測試全面失敗，錯誤訊息：Invalid argument 整合測試作者 with type BookAuthor. Only num, String and Uint8List are supported——所有涉及 SQLite 的 CRUD 操作都掛 疑問來源：同一個 map 裡 id 跟 title 都存得進去，為什麼 author 炸了？ 整理目的：記下 value object 跨持久化邊界的轉換責任、以及 toString/fromString 這條隱性契約的風險 本文邊界：素材是該專案 v0.10.6 的修復規劃記錄；sqflite 的型別限制是 SQLite 本身的特性、不是套件的設計選擇

錯誤現場：三個欄位、兩種寫法

炸點在 repository 把 entity 轉成資料庫 map 的方法：

1Map<String, dynamic> _bookToMap(Book book) {
2  return {
3    'id': book.id.toString(),        // BookId → String，存得進去
4    'title': book.title.toString(),  // BookTitle → String，存得進去
5    'author': book.author,           // BookAuthor 物件直接塞 → 炸
6    ...
7  };
8}

sqflite 底下的 SQLite 只接受 num、String、Uint8List 三種型別。BookAuthor 是帶內部狀態的 value object（作者清單、譯者），直接放進 map 就是把一個 Dart 物件遞給不認識它的儲存引擎。錯誤訊息其實說得很清楚——難的不是修，是這個錯誤揭露的責任問題：誰負責把領域型別拆成儲存型別？

責任歸位：轉換發生在 repository 邊界

修法本身一行：'author': book.author.toString()；讀回的方向 _mapToBook 已經在用 BookAuthor.fromString(map['author']) 重建。架構上這是 adapter 的職責放在 repository 層——domain 的 value object 不知道 SQLite 存在、SQLite 不知道 value object 存在，兩個世界的轉換集中在 I/O 邊界的 _bookToMap / _mapToBook 一對方法裡。

這個歸位讓錯誤的形態變得可預測：每個新的 VO 欄位都要在這對方法裡出現一次，漏掉序列化端會炸 Invalid argument（吵、好抓）、漏掉反序列化端會在讀取時炸型別轉換（也吵）。真正安靜的坑在第三種情況——兩端都寫了、但不對稱。

隱性契約：toString 與 fromString 的對稱性沒人強制

用 toString() / fromString() 當序列化通道，工作的前提是 fromString(x.toString()) == x——而這條契約沒有任何機制在守。修復記錄自己就把風險寫進了已知限制：複雜物件轉字串可能遺失部分內部狀態、未來需要更精細的序列化機制。

具體的斷裂點兩種。其一，toString() 的本業是除錯表示，哪天有人為了 log 可讀性把格式改成 BookAuthor(name: ...)，資料庫裡從此存進去的是新格式、舊資料用新 fromString 讀不回來——兩個消費者（除錯與持久化）寄生在同一個方法上、變更理由不同步。其二，格式本身有損：這個專案的 BookAuthor 把多作者序列化成「作者1, 作者2」、譯者成「作者 (譯者 譯)」——作者名字裡出現逗號或括號時，roundtrip 就不再對稱。

正解方向修復記錄也留了：語意明確的序列化介面（toDbValue() / 專用 Serializable、或 JSON 結構化），讓「持久化格式」成為一個有自己名字、自己測試、自己變更理由的東西。過渡期至少要補上對稱性測試——對每個 VO 斷言 fromString(v.toString()) == v、含邊界值（空作者、多作者、含譯者），把隱性契約變成會紅的測試。

判讀徵兆

• Invalid argument ... with type X. Only num, String and Uint8List are supported——X 就是漏轉換的 VO、去 _toMap 系方法找它
• repository 的 map 轉換裡混用「物件直接放」跟「.toString()」兩種寫法——前者是還沒炸的候選
• toString() 同時服務除錯輸出跟持久化 / 快取 key——語意寄生，兩個消費者遲早有一個要改格式
• VO 有 fromString 但測試裡沒有任何 roundtrip 斷言——對稱契約處於未驗證狀態

相關閱讀

• 出口語意的原則版：VO 封裝擺盪——那篇論證「原始值要有語意明確的官方出口」，本文是 toString() 被當出口用的實際風險清單
• 持久化邊界的另一面：功能完成卻從未持久化——那篇是欄位沒進出邊界、本文是進了邊界但轉換錯誤，roundtrip 測試同時守住兩者
• 概念地基：DDD 領域驅動設計指南 的 entity 持久化邊界章節

觸發場景：Book entity 換成 tag-based 結構後（Deprecated Getter Facade 那次），接下來要派發消費端遷移的 ticket——把 book.author 改成 book.getPrimaryTag("author")。派發前的設計一致性檢查攔下了它：這個改動上線後，enrichment、export、CSV 全部會靜默失效 疑問來源：facade 遷移做完了、資料 backfill 的 ticket 也排了，消費端遷移為什麼還是危險的？缺了什麼？ 整理目的：記下資料遷移的「三段通路」檢查、fixture 假綠的機制、以及依賴圖作為推導訊號的失效方式 本文邊界：素材是該專案 v0.32 的分析 ticket（含獨立重驗的證據鏈）；被攔下的事故沒有真的發生——這是一次派發前攔截的記錄

缺口：新 API 的資料從哪來？

檢查的起點是一個樸素的問題：消費端改用 getPrimaryTag("author") 之後，這個方法讀的 bookTags 集合、內容從哪來？grep 的答案是不從任何地方來——repository 的 _mapToBook 建構 Book 時完全沒提 bookTags，欄位恆為預設 const []。從 SQLite 載入的每一本書，tag API 都回空。

而計畫裡確實有兩張看起來相關的 ticket，逐一確認 scope 後都不覆蓋這個缺口：

資料模型遷移的通路有三段：寫入（backfill 讓新結構有資料）、讀出（讀取路徑把新結構載進物件）、消費（呼叫端改用新 API）。這個計畫排了第一段跟第三段、第二段整段缺席——不是排錯順序、是沒有任何 ticket 認領它。缺口安靜的原因跟持久層靜默丟欄位同構：每張存在的 ticket 都會被檢視、不存在的 ticket 沒有形狀可供檢視。

假綠機制：fixture 不走真實資料通路

更危險的是這個缺口測試抓不到。消費端的 unit test fixture 自己 Book(...) 建物件——遷移後 fixture 跟著改、建的時候直接帶上 bookTags，於是 getPrimaryTag 在測試裡有資料、斷言全過。真實環境的 Book 從 SQLite 經 _mapToBook 載入、bookTags 恆空——測試世界跟真實世界走不同的資料通路，測試通過證明的只是「如果資料有進來、邏輯是對的」，而資料沒進來。

這是假綠家族裡最結構性的一種：不是 mock 遮蔽、不是斷言過時，是 fixture 的建構方式繞過了真實系統的組裝路徑。守住它的測試必須走完整通路——寫進 SQLite、經 repository 讀出、斷言 tags 存在——也就是整合層的 roundtrip，unit fixture 結構上無能為力。

依賴圖是推導、ready 是推導的推導

第二個結構性缺陷在計畫層。盤點八張消費端遷移 ticket 的 blockedBy：五張只列了 W1-002（entity 重寫）——它們的「前提」只記錄了時序直覺（core entity 要先改），沒記錄語意前提（我改用的 API 要真的有資料）。而 dashboard 判定 W2-008「ready 可派發」，依據就是這張不完整的 blockedBy。

訊號鏈是這樣失真的：語意前提沒被列進 blockedBy → blockedBy 齊了 → ready 亮綠燈 → 派發。每一步推導都正確、第一步的輸入就缺了。這跟 #221 規則存在 vs 規則涵蓋同構：ready 訊號的可信度上限是依賴圖的完整性，圖不完整時 ready 的綠跟「沒檢查」的綠長一樣。修正也對準這裡：補建 read-path ticket、七張 ticket 的 blockedBy 補上資料通路前提、wave 重排序（讓 tag API 回真資料的工作先於所有消費端遷移）。

流程上還有一筆值得記：這次分析被要求獨立重驗——「勿盲信 PM 行號、重跑 grep / 讀檔」，五項證據全部重新驗證。攔截的品質靠的不是第一個發現者的正確、是第二雙眼睛用自己的指令重跑一遍。

判讀徵兆

• 遷移計畫的 ticket 清單裡，寫入（backfill / migration script）跟消費（API 呼叫端改寫）都有、讀取路徑（mapper / repository 載入）沒有獨立條目——逐段問「新結構的資料怎麼進物件」
• 新 API 在測試全綠、實機回空值 / 預設值——查 fixture 的建構方式是否繞過真實組裝路徑
• blockedBy 全是「結構上游」（entity、schema）而沒有「資料上游」（backfill、注入）——依賴圖記了時序、沒記語意
• grep 新欄位名在 repository / mapper 檔案零命中——讀取路徑還不知道這個欄位存在，消費端遷移是空中樓閣

相關閱讀

• 上一章：Deprecated Getter Facade——facade 讓編譯過了，本文是「編譯過了之後、資料通路要自己驗證」的實錄
• 同構的持久化盲區：功能完成卻從未持久化——那篇缺寫入段、本文缺讀出段，三段通路各有各的靜默缺法
• 原則層：#163 多階段流程的 artifact 欄位契約——「下游宣稱以上游為輸入」要欄位層級可推導，blockedBy 的語意前提就是 ticket 系統的欄位契約