程式碼庫設計
設計深度模組:在乾淨的接縫處放置一個小介面背後的大量行為,並可透過該介面進行測試。在設計或重構程式碼的任何地方,都使用這些語言和原則。目標是為呼叫者提供槓桿作用,為維護者提供局部性,並為所有人提供可測試性。
詞彙表
請精確使用這些術語——不要替換為「元件」、「服務」、「API」或「邊界」。一致的語言是重點。
模組 — 任何具有介面和實作的東西。刻意與規模無關:一個函式、類別、套件或跨層級的切片。避免:單元、元件、服務。
介面 — 呼叫者正確使用模組時必須知道的一切:型別簽章,但也包括不變條件、排序約束、錯誤模式、所需配置和效能特性。避免:API、簽章(太狹隘——它們僅指型別層級的表面)。
實現 — 模組內部的東西,其程式碼主體。與適配器不同:某物可以是一個帶有大量實現的小型適配器(像是Postgres儲存庫),也可以是一個帶有少量實現的大型適配器(像是記憶體模擬)。當接縫是主題時,使用「適配器」;否則使用「實現」。
深度 — 介面上的槓桿作用:呼叫者(或測試)在必須學習的每個介面單位上可以使用的行為量。當大量行為位於小型介面背後時,模組是深的;當介面幾乎與實現一樣複雜時,模組是淺的。
接縫 (Michael Feathers) — 一個可以在不直接編輯該位置的情況下改變行為的地方;是模組介面存在的位置。將接縫放在哪裡本身就是一個設計決策,與背後放置的內容不同。避免:邊界(與DDD的限界上下文過載)。
適配器 — 滿足接縫處介面的具體事物。描述角色(它填補了什麼插槽),而不是實質(內部是什麼)。
槓桿作用 — 呼叫者從深度中獲得的東西:每學習一個介面單位就能獲得更多能力。一個實作在N個呼叫點和M個測試中回報。
局部性 — 維護者從深度中獲得的東西:變更、錯誤、知識和驗證集中在一個地方,而不是分散在呼叫者之間。一次修復,處處固定。
深 vs 淺
深度模組 = 小介面 + 大量實現:
┌─────────────────────┐
│ 小型介面 │ ← 少數方法,簡單參數
├─────────────────────┤
│ │
│ 深度實現 │ ← 隱藏複雜邏輯
│ │
└─────────────────────┘
淺度模組 = 大介面 + 少量實現(應避免):
┌─────────────────────────────────┐
│ 大型介面 │ ← 許多方法,複雜參數
├─────────────────────────────────┤
│ 薄實現 │ ← 僅傳遞
└─────────────────────────────────┘
設計介面時,請詢問:
- 我可以減少方法的數量嗎?
- 我可以簡化參數嗎?
- 我可以在內部隱藏更多複雜性嗎?
原則
- 深度是介面的屬性,而非實現的屬性。 一個深度模組可以在內部由小的、可模擬的、可互換的部分組成——它們只是不屬於介面的一部分。一個模組可以具有內部接縫(對其實現私有,供其自身測試使用)以及其介面上的外部接縫。
- 刪除測試。 想像刪除該模組。如果複雜性消失,那麼它就是一個直通模組。如果複雜性重新出現在N個呼叫者中,那麼它就在發揮其作用。
- 介面就是測試表面。 呼叫者和測試跨越相同的接縫。如果你想測試超越介面,那模組的形狀可能不對。
- 一個適配器意味著一個假設的接縫。兩個適配器意味著一個真正的接縫。 除非有些東西實際上跨接縫變化,否則不要引入接縫。
為可測試性設計
好的介面讓測試自然:
-
接受依賴,而非建立它們。
// 可測試 function processOrder(order, paymentGateway) {} // 難以測試 function processOrder(order) { const gateway = new StripeGateway(); } -
回傳結果,而非產生副作用。
// 可測試 function calculateDiscount(cart): Discount {} // 難以測試 function applyDiscount(cart): void { cart.total -= discount; } -
小表面積。 更少的方法 = 需要更少的測試。更少的參數 = 更簡單的測試設定。
關係
- 一個模組恰好有一個介面(它呈現給呼叫者和測試的表面)。
- 深度是模組的屬性,相對於其介面來衡量。
- 接縫是模組****介面所在的位置。
- 適配器位於接縫處並滿足介面。
- 深度為呼叫者產生槓桿作用,為維護者產生局部性。
被拒絕的框架
- 深度作為實現行數與介面行數的比例 (Ousterhout):獎勵填充實現。我們改用深度即槓桿作用。
- 「介面」作為TypeScript的
interface關鍵字或類別的公開方法:太狹隘——這裡的介面包括呼叫者必須知道的每一個事實。 - 「邊界」:與DDD的限界上下文過載。應使用接縫或介面。
深入探討
- 鑑於其依賴關係深化集群 — 請參閱 DEEPENING.md:依賴類別、接縫紀律以及取代而非分層測試。
- 探索替代介面 — 請參閱 DESIGN-IT-TWICE.md:啟動並行子代理,以多種截然不同的方式設計介面,然後在深度、局部性和接縫放置方面進行比較。