codebase-designlisted

# 程式碼庫設計 設計**深模組**：小介面背後有大量行為、放在乾淨的接縫上、可以透過那個介面測試。在任何程式碼被設計或重構的地方使用這套語言與這些原則。目標是讓呼叫者獲得槓桿收益、維護者獲得局部性、所有人獲得可測試性。 ## 詞彙表 精確使用這些術語——不要替換成「component」「service」「API」或「boundary」。一致的語言就是重點。 **模組**——任何有介面與實作的東西。刻意地與規模無關：一個函式、類別、套件，或橫跨層級的切片。_Avoid_: unit、component、service。 **介面**——呼叫者要正確使用模組所需知道的一切：型別簽名，也包括不變量、順序約束、錯誤模式、必要的設定，與效能特徵。_Avoid_: API、signature（太窄——它們只指型別層級的表面）。 **實作**——模組裡面的東西，它的程式碼本體。與**轉接器**區別：一個東西可以是小轉接器配大實作（Postgres repo），或大轉接器配小實作（記憶體中的假物件）。當主題是接縫時用「轉接器」；其他情況用「實作」。 **深度**——介面上的槓桿收益：呼叫者（或測試）每學習一單位介面所能行使的行為量。當大量行為藏在一個小介面後面時，模組是**深的**；當介面幾乎跟實作一樣複雜時是**淺的**。 **接縫** _(Michael Feathers)_——一個你可以不用在原地編輯就能改變行為的地方；模組介面所在的*位置*。接縫放哪裡本身是一個設計決策，與放在它後面的是什麼是兩回事。_Avoid_: boundary（與 DDD 的 bounded context 過載）。 **轉接器**——在接縫處滿足某個介面的具體東西。描述*角色*（它填補什麼槽位），不是實體（裡面是什麼）。 **槓桿收益**——呼叫者從深度得到的：每學習一單位介面獲得更多能力。一份實作在 N 個呼叫點與 M 個測試之間回本。 **局部性**——維護者從深度得到的：變更、bug、知識與驗證集中在一個地方，而不是散落在呼叫者之間。修一次，處處修好。 ## 深 vs 淺 **深模組** = 小介面 + 大量實作： ``` ┌─────────────────────┐ │ Small Interface │ ← Few methods, simple params ├─────────────────────┤ │ │ │ Deep Implementation│ ← Complex logic hidden │ │ └─────────────────────┘ ``` **淺模組** = 大介面 + 少許實作（避免）： ``` ┌─────────────────────────────────┐ │ Large Interface │ ← Many methods, complex params ├─────────────────────────────────┤ │ Thin Implementation │ ← Just passes through └─────────────────────────────────┘ ``` 設計介面時問： - 我能減少方法數量嗎？ - 我能簡化參數嗎？ - 我能把更多複雜度藏在裡面嗎？ ## 原則 - **深度是介面的屬性，不