乾淨架構框架
一種有紀律的軟體結構化方法,確保業務規則獨立於框架、資料庫以及傳遞機制。在設計系統架構、審查模組邊界或提供相依性管理建議時,請應用這些原則。
核心原則
原始碼相依性必須指向內側——朝向更高層級的政策。 內圈的任何事物都不能知道外圈的任何事物。這條單一規則產生了可測試、獨立於框架、UI、資料庫及任何外部機構的系統。業務規則才是重點;資料庫、網頁框架和傳遞機制都是細節——當細節依賴於政策時,你可以延遲決策、替換實作,並在隔離環境中測試業務邏輯。
評分
目標:10/10。 根據架構滿足的七項快速診斷問題(Quick Diagnostic)各得一分(0-7),然後映射到 0-10 的區間:滿足 6-7 項 = 9-10(相依性規則成立,業務邏輯獨立於框架和資料庫);4-5 項 = 6-8(核心可測試,但部分細節向內洩漏);2-3 項 = 3-5(框架或持久化機制主導結構);0-1 項 = 0-2(無邊界——業務規則存在於控制器和 ORM 模型中)。報告分數、未通過的診斷項目,以及修復每個項目所需的特定反轉。
1. 相依性規則與同心圓
核心概念: 將架構組織為同心圓——最內層是實體(Entity,企業業務規則),其次是用例(Use Case,應用程式業務規則),然後是介面適配器,最外層是框架與驅動程式。原始碼相依性永遠指向內側。
為何有效: 當高層級政策不依賴於低層級細節時,你可以更換資料庫、網頁框架或 API 風格,而無需觸及業務邏輯——系統變得能夠抵禦技術堆疊中最易變的部分。
關鍵見解:
- 內圈不能提及外圈的名稱——不能有來自外部的類別、函式、變數或資料格式
- 跨越邊界的資料必須以對內圈最方便的形式呈現,而不是由外圈決定
- 依賴反轉(介面向內定義,向外實作)是執行此規則的機制
- 圓的數量並非固定——四個是典型;規則保持不變
- 框架是細節,不是架構——它們屬於最外圈
程式碼應用:
| 情境 | 模式 | 範例 |
|---|---|---|
| 層級方向 | 內圈定義介面;外圈實作 | UserRepository 介面在用例中;PostgresUserRepository 在適配器中 |
| 資料跨越 | DTO 跨越邊界,不是 ORM 實體 | 用例回傳 UserResponse DTO,而不是 ActiveRecord 模型 |
| 相依性方向 | 匯入箭頭永遠指向內側 | 控制器匯入用例;用例從不匯入控制器 |
當內圈的匯入指向外圈時,請參閱 references/dependency-rule.md 取得四圈程式碼逐步解說、資料跨越規則,以及修復問題的四步驟依賴反轉程序。
2. 實體與用例
核心概念: 實體封裝了企業層級的業務規則——即使沒有軟體也會存在的規則。用例包含了應用程式特定的規則,用來協調進出實體的資料流。
為何有效: 將「業務做什麼」(實體)與「應用程式如何協調」(用例)分開,可以讓您在多個應用程式中重用實體,並在不改變核心業務規則的情況下變更應用程式行為。
關鍵見解:
- 實體不是資料庫行——它們是封裝關鍵業務規則的物件或純函式
- 用例接受請求模型(Request Model)並回傳回應模型(Response Model)——絕不使用框架物件
- 每個用例都是一個單一的應用程式操作(
CreateOrder、ApproveExpense) - 互動器模式(Interactor pattern):一個用例類別實作輸入邊界介面,並呼叫輸出邊界介面
- 用例的變更絕不應影響實體;實體的變更可能會波及用例
程式碼應用:
| 情境 | 模式 | 範例 |
|---|---|---|
| 實體設計 | 關鍵業務規則,零框架依賴 | Order.calculateTotal() 套用稅務規則;對 HTTP 一無所知 |
| 請求/回應 | 簡單的資料結構跨越邊界 | CreateOrderRequest { items, customerId }——沒有 ORM 模型 |
| 單一職責 | 每個操作一個用例 | PlaceOrder、CancelOrder、RefundOrder 作為獨立的類別 |
| 互動器 | 實作輸入埠,呼叫輸出埠 | PlaceOrderInteractor implements PlaceOrderInput |
在設計互動器或決定哪些屬於實體、哪些屬於用例時,請參閱 references/entities-use-cases.md——包含完整的企業與應用程式業務規則處理,以及請求/回應模型範例。
3. 介面適配器與框架
核心概念: 介面適配器在對用例/實體方便的格式與外部機構要求的格式之間轉換資料。框架和驅動程式是最外層——與外界溝通的黏合程式碼。
為何有效: 當網頁框架、ORM 或訊息佇列被限制在外圈時,更換其中任何一個都是局部性的變更。資料庫是細節;網頁是細節;細節應該是你業務規則的外掛程式,而不是應用程式的骨架。
關鍵見解:
- 控制器將 HTTP 轉換為用例輸入;呈現器將用例輸出轉換為視圖模型
- 閘道器實作用例定義的儲存庫介面——內圈定義合約,外圈履行合約
- 業務規則從不知道資料是存在 SQL、NoSQL 還是純文字檔案中,也不知道傳遞方式是 HTTP
- 對待框架要保持懷疑——它們希望你與它們耦合;讓它們保持距離
程式碼應用:
| 情境 | 模式 | 範例 |
|---|---|---|
| 控制器 | 傳遞機制 → 用例輸入 | OrderController.create(req) 建構 CreateOrderRequest,呼叫互動器 |
| 呈現器 | 用例輸出 → 視圖模型 | OrderPresenter.present(response) 格式化為 JSON/HTML |
| 閘道器 | 每個資料庫實作儲存庫介面 | SqlOrderRepository implements OrderRepository |
| 框架邊界 | 框架向內呼叫,絕不反向 | Express 路由處理器呼叫控制器;控制器從不匯入 Express |
在接線控制器、呈現器或閘道器,或論證資料庫/網頁是細節時,請參閱 references/adapters-frameworks.md——涵蓋外掛程式架構以及如何將框架限制在邊緣。
4. 元件原則
核心概念: 元件是部署的單元。三個內聚原則管理元件內部的內容;三個耦合原則管理元件之間的關係。
為何有效: 組合不良的元件會產生連鎖效應,一個變更迫使無關的程式碼重新部署;這些原則將變更局部化,並使發布保持獨立。
關鍵見解:
- REP(重用/發布等價原則):元件中的類別必須可以作為一個單元進行版本控制與發布
- CCP(共同封閉原則):因相同原因在同一時間變更的類別應放在一起——這是針對元件的 SRP
- CRP(共同重用原則):不要強迫使用者依賴他們不使用的類別
- ADP(無環依賴原則):元件圖不能有循環——使用 DIP 或建立新元件來打破循環
- SDP(穩定依賴原則):朝穩定方向依賴
- SAP(穩定抽象原則):穩定的元件應該是抽象的;不穩定的元件應該是具體的
程式碼應用:
| 情境 | 模式 | 範例 |
|---|---|---|
| 元件分組 | 將一起變更的類別分組(CCP) | 所有與訂單相關的用例放在一個元件中 |
| 打破循環 | 套用 DIP 來反轉依賴邊 | 將介面萃取到新元件中以打破循環 |
| 穩定性度量 | 不穩定性 I = Ce / (Ca + Ce) | 多個傳入,無傳出依賴 → I 接近 0(穩定) |
在將類別分組到可部署元件或打破依賴循環時,請參閱 references/component-principles.md——使用不穩定性指標逐步處理 REP、CCP、CRP、ADP、SDP、SAP。
5. SOLID 原則
核心概念: 五個類別與模組層級的原則——單一職責、開閉原則、里氏替換、介面隔離、依賴反轉——是使相依性規則成為可能的中階建構區塊。
為何有效: 每個原則都針對依賴關係出錯的特定方式,防止將程式碼庫變成遺留噩夢的僵化性、脆弱性和不可移動性。
關鍵見解:
- SRP:一個模組只有一個改變的理由——它服務於一個角色(而不是「做一件事」)
- OCP:通過新增程式碼來擴展行為,而不是修改現有程式碼——策略模式和外掛程式模式
- LSP:子型別必須能透過基底介面使用,而客戶端無需察覺——被未預期的異常或忽略的方法所違反
- ISP:客戶端不應依賴他們不使用的方法——胖介面會產生不必要的耦合
- DIP:高層級模組和低層級模組都依賴於高層級模組定義的抽象
程式碼應用:
| 情境 | 模式 | 範例 |
|---|---|---|
| SRP 違反 | 類別服務多個角色 | Employee 處理薪資(CFO)、報告(COO)、持久化(CTO) |
| OCP 透過策略 | 透過新類別實作新行為 | 新增 ExpressShipping 實作 ShippingStrategy;Order 不變 |
| LSP 違反 | 子型別改變預期行為 | Square extends Rectangle 破壞了 setWidth()/setHeight() 合約 |
| ISP 應用 | 將胖介面拆分為角色介面 | 使用 Printer、Scanner、Fax 而不是一個 MultiFunctionDevice |
| DIP 接線 | 高層級定義介面;低層級實作 | OrderService 依賴於 PaymentGateway,而不是 StripeClient |
在將 SRP/OCP/LSP/ISP/DIP 應用於特定類別或診斷違反時,請參閱 references/solid-principles.md——每個原則都透過程式碼範例及其預防的程式碼壞味道逐步說明。
6. 邊界與邊界結構
核心概念: 邊界是重要事物與細節事物之間的一條線,通過多型來實作:依賴關係指向內側,而控制流可以從任一方向跨越。
為何有效: 每個邊界都提供了延遲決策或替換實作的選項;策略性地放置邊界決定了系統在多年維護中是令人愉悅還是痛苦。
關鍵見解:
- 完整邊界在兩側使用相互的介面;部分邊界使用更簡單的策略或外觀模式
- 謙卑物件模式:將邊界程式碼拆分為難以測試的部分(靠近邊界)和易於測試的部分(邏輯)
- 服務不自動構成架構邊界——一個具有龐大共享資料模型的微服務就是一個帶有網路呼叫的單體
- 測試是最孤立的元件:它們向內依賴,沒有什麼依賴於它們
- 過早的邊界是昂貴的,但缺失的邊界也同樣昂貴——在可能變動的點上繪製邊界
程式碼應用:
| 情境 | 模式 | 範例 |
|---|---|---|
| 完整與部分邊界 | 相互的埠,或單一的策略 | 用例定義 PlaceOrderInput/PlaceOrderOutput;較簡單的情況使用 ShippingStrategy |
| 謙卑物件 | 將可測試的邏輯與基礎設施分開 | PresenterLogic(可測試)產生 ViewModel;View(謙卑)渲染它 |
| 主程式作為外掛 | 組合根組裝系統 | main() 接線所有具體實作並啟動應用程式 |
在決定邊界繪製位置、選擇完整或部分邊界、或應用謙卑物件模式時,請參閱 references/boundaries.md——也涵蓋了服務作為邊界、測試邊界以及主程式作為終極外掛。
常見錯誤
| 錯誤 | 為何失敗 | 修正方式 |
|---|---|---|
| ORM 洩漏到業務邏輯中 | 實體耦合到資料庫綱要;資料庫變更會改寫業務規則 | 將領域實體與持久化模型分開;在適配器層進行映射 |
| 業務規則放在控制器中 | 未經 HTTP 無法測試;在端點間重複 | 將邏輯移到用例互動器中;控制器僅負責轉譯與委派 |
| 框架優先的架構 | 框架主導結構;更換意味著重寫 | 將框架視為外掛;根據業務能力組織程式碼 |
| 循環的元件依賴 | 變更不可預測地擴散;無法獨立發布 | 套用 DIP 或萃取一個共享抽象元件 |
| 每個特性一個巨型用例 | 數千行的膨脹協調器 | 拆分為專注的單一操作用例 |
| 因為「簡單」而跳過邊界 | 耦合悄悄累積,直到成本變得巨大 | 在可能變動的點上主動繪製邊界 |
| 微服務自動代表好架構 | 分散式單體比乾淨的單體更差 | 在服務內部和服務之間套用相依性規則;服務是部署邊界,不是架構邊界 |
快速診斷
| 問題 | 如果沒有 | 行動 |
|---|---|---|
| 你能在沒有資料庫、網頁伺服器或框架的情況下測試業務規則嗎? | 規則與基礎設施耦合 | 在介面後萃取實體和用例;模擬外層 |
| 所有原始碼相依性都指向內側嗎?(無內圈匯入外圈) | 相依性方向錯誤 | 找到向外指向的匯入,套用依賴反轉 |
| 實體是否不包含任何框架、資料庫或 Web 匯入? | 實體被細節污染 | 從實體中移除外部匯入;透過介面注入依賴 |
| 用例是否以 DTO(或原始類型)的形式接收請求並回傳回應,而不是 ORM 模型? | 資料洩漏邊界 | 為每個跨越邊界的操作定義請求/回應模型 |
| 控制器是否只執行轉譯和委派而不包含業務邏輯? | 控制器含有業務規則 | 將規則移至用例中;讓控制器僅管理 HTTP/框架關注點 |
| 是否將元件分組,使得因相同原因變更的類別放在一起? | 變更跨元件擴散 | 套用 CCP 重組;檢查是否有循環或穩定依賴問題 |
| 系統是否與框架和資料庫解耦,足以讓切換兩者中的任何一個只需在適配器層進行局部變更? | 框架/資料庫影響了架構 | 從最外層隔離框架細節;使用儲存庫模式抽象化資料庫 |