這條判準值得成章，因為它跟一個直覺衝突：觀測出口的需求完全來自消費端——是 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

概念位置

port 跟一般 interface 的差別在歸屬與語言：宣告在領域層、以領域概念命名（BookRepository 而非 SqliteClient）、方法簽名只用領域型別。介面本身是型別層的約束載體——它強制了「呼叫方看不見技術細節」，與 invariant 的型別層強制同一個機制。

可觀察訊號

介面檔案位於 domain 目錄、簽名沒有框架型別，是 port 健康的訊號。介面裡出現 DatabaseConnection、HttpClient 這類技術型別時，port 已被實作細節滲透——呼叫方被迫認識它不該認識的層。

設計責任

port 定義「領域需要什麼」，不保證「有人供給它」——宣告了介面、沒有實作被插上，在 mock 測試裡不會有任何紅燈。供給的驗證屬組裝層，教學層展開見 組裝層的可達性。port 的歸屬判準（逐型別問「這是誰的詞彙」）在 reactive 場景的完整推導見 觀測出口的職責三分。

概念位置

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

可觀察訊號

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

設計責任

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

觸發場景：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 加啟用條件、不是無主地放著