轉換為六邊形架構 是做什麼的?
深入分析現有儲存庫,並設計一個原子化、分階段的重構計畫,將其遷移至六邊形架構(連接埠與適配器),同時不破壞任何外部合約或可觀察行為。
請使用與使用者請求相同的語言回覆。嚴格以計畫模式運作:先檢查程式碼庫,然後在修改任何檔案之前提供完整的計畫。
使用時機
- 使用者要求將現有專案遷移或重構為六邊形架構或連接埠與適配器。
- 使用者希望將業務邏輯與 Web 框架、ORM、資料庫、訊息佇列或外部 SDK 解耦。
- 使用者要求一個安全、漸進式、且零破壞性變更的架構重構計畫。
核心原則
- 零破壞性變更(黃金法則): 保留所有既有的外部合約。路由、HTTP 方法、狀態碼、請求/回應有效負載結構、標頭、錯誤格式、CLI 標誌或佇列訊息形狀必須保持完全相同。
- 重構前先表徵: 在自動化合約/表徵測試覆蓋現有端點或進入點之前,絕不移動或刪除正式程式碼。
- 嚴格的依賴規則: 原始碼依賴必須始終指向內部的
domain。領域層不得從 Web 框架、資料庫驅動程式、ORM、序列化程式庫或外部 SDK 進行任何匯入。 - 技術棧慣用適應法: 根據專案偵測到的語言和生態系統(例如 TypeScript/Node、Python、Go、Java/Kotlin、C#、Rust)調整目錄路徑、命名慣例、型別結構和測試執行器。
工作流程
步驟 1:程式碼庫探索
在提出任何資料夾樹狀結構或遷移步驟之前,先掃描儲存庫:
- 技術棧與工具: 檢查相依性清單、編譯器/linter 配置和測試執行器,以識別語言、框架、驗證程式庫、ORM/查詢建構器和 DI 方法。
- 進入點與合約: 清查所有驅動型進入點(HTTP 路由、GraphQL 解析器、gRPC 服務、訊息消費者、cron 任務)、它們的驗證結構、中介軟體/攔截器和全域錯誤處理器。
- 外部相依性: 清查所有被驅動的副作用(資料庫、快取、HTTP/RPC 客戶端、佇列、檔案儲存、環境配置、日誌記錄器)。
- 當前執行流程: 追蹤資料目前如何從進入點流向持久層/外部呼叫再返回,並注意業務規則在何處與傳輸或持久層細節混合在一起。
步驟 2:設計目標六邊形佈局
將三個同心層對應到專案的慣用原始碼根目錄(例如 TypeScript/Rust 中的 src/、Go 中的 internal/、JVM 中的 src/main/<lang>/,或 Python 中的主套件目錄):
domain/(純業務核心 - 零框架或 I/O 相依性):entities/和value-objects/:封裝業務規則、不變量和自我驗證的領域模型。ports/in/:定義用例合約的驅動埠介面。ports/out/:定義儲存庫、外部服務、事件發布器和LoggerPort合約的被驅動埠介面。errors/:語義領域例外(例如ResourceNotFoundError、DomainValidationError、ConflictError)。
application/(用例編排):use-cases/:實作ports/in,協調領域實體和ports/out。dtos/:與傳輸有效負載和持久層實體解耦的不可變輸入和輸出資料結構。
infrastructure/(技術細節與適配器):adapters/in/:驅動型適配器(HTTP 控制器/處理器、消費者處理器)、傳輸驗證結構、映射器(TransportInput -> InputDTO和OutputDTO -> TransportOutput),以及將domain/errors轉譯為確切舊版錯誤回應的全域錯誤映射器。adapters/out/:ports/out(資料庫儲存庫、HTTP 客戶端、代理)的具體實作,以及持久層/外部映射器,以使 ORM 模型或 SDK 型別永遠不會洩漏到domain/。config/:環境變數和執行時期設定的嚴格載入和啟動驗證。di/(組合根):透過建構子注入明確地連接被驅動的適配器、用例和驅動型適配器,避免隱藏單例或服務定位器。
- 啟動分離: 將應用程式建構(
buildApp/ 用於隔離整合測試的工廠函式)與伺服器/程序啟動(main/listen)分開。
步驟 3:在計畫中強制執行工程標準
確保計畫中的每個階段都強制執行:
- 強型別與不可變性: 禁止未經型別檢查的逃逸(例如
any或在應使用型別結構的地方使用原始未型別映射),並偏好不可變的 DTO 和值物件(readonly、凍結資料類別、記錄、值型別)。 - SOLID 與建構子注入: 保持類別和函式小而單一責任;透過建構子注入介面。
- 不帶耦合的可觀測性: 保留結構化日誌記錄和請求關聯上下文,同時透過
LoggerPort使domain/和application/與特定的日誌記錄程式庫解耦。 - 金字塔式測試:
domain/(純不變量)和application/(模擬ports/out)的單元測試。- 整合/合約測試,使用技術棧的原生命令列測試客戶端(例如
fastify.inject、Supertest、FastAPITestClient、SpringMockMvc或 Gohttptest)驗證真實的驅動型適配器與應用程式接線。
輸出格式(計畫模式)
將回覆結構化為以下精確章節:
- 當前架構診斷: 簡潔地清查偵測到的技術棧、進入點/端點、外部相依性和主要的耦合熱點。
- 目標目錄樹: 使用在儲存庫中找到的真實模組和功能名稱,提出完整的資料夾結構。
- 分階段執行計畫: 五個原子化、可驗證的階段:
- 階段 1 - 表徵測試與基礎結構搭建: 建立鎖定當前行為的合約測試,建立目標資料夾、配置載入器和組合根(
di/)。 - 階段 2 - 領域提取: 提取實體、值物件、領域錯誤和
ports/in+ports/out介面,並附帶單元測試。 - 階段 3 - 應用程式用例與被驅動適配器: 實作用例、DTO、
adapters/out儲存庫/客戶端和持久層映射器。 - 階段 4 - 驅動型適配器與錯誤轉譯: 重構控制器/處理器以透過映射器委派給用例,連接全域錯誤轉譯,並連接
di/。 - 階段 5 - 舊版清理與最終驗證: 移除過時的檔案,執行完整的測試套件、linter 和型別檢查器,並驗證零合約偏差。
- 階段 1 - 表徵測試與基礎結構搭建: 建立鎖定當前行為的合約測試,建立目標資料夾、配置載入器和組合根(
- 驗證檢查點: 每個階段結束時明確的命令或檢查,以證明在進入下一個階段之前沒有出現任何問題。
注意事項
- 不要過早編輯程式碼: 除非使用者明確要求立即開始執行階段 1,否則首先只輸出計畫,以便他們可以檢閱模組邊界。
- 避免對瑣碎的 CRUD 進行過度抽象: 仍然要乾淨地分離
domain、application和infrastructure,但保持直通的用例簡潔,而不是發明人為的領域複雜性。 - 匹配舊版怪癖: 如果現有端點回傳非標準的狀態碼或錯誤欄位名稱,請在階段 1 中記錄它,並在
infrastructure錯誤映射器中保留它,以免現有客戶端中斷。