Community程式設計與開發github.com

轉換為六邊形架構

分析現有程式碼庫(不限語言或框架),並生成一個分階段、零破壞性變更的重構計畫,將其遷移至六邊形架構(連接埠與適配器)。

轉換為六邊形架構 是什麼?

此技能會深入分析現有程式碼庫,並設計一個原子化、分階段的重構計畫,將專案遷移至**六邊形架構(連接埠與適配器)**,同時確保所有外部合約與可觀察行為保持不變。它特別適用於需要將業務邏輯與 Web 框架、ORM、資料庫、訊息佇列或外部 SDK 解耦的情境。該技能支援多種語言與生態系統(例如 TypeScript、Python、Go、Java/Kotlin、C#、Rust),並遵循嚴格的依賴規則:領域層不得導入任何框架或 I/O 相關的程式庫。輸出格式為「計畫模式」,包含詳細的目錄樹、五個可驗證的執行階段,以及每個階段的驗證檢查點,以確保在進行重構時不會破壞任何現有的外部合約或行為。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/gabrandalisse/skills/tree/HEAD/skills/to-hexagonal-architecture

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

轉換為六邊形架構 是做什麼的?

深入分析現有儲存庫,並設計一個原子化、分階段的重構計畫,將其遷移至六邊形架構(連接埠與適配器),同時不破壞任何外部合約或可觀察行為。

請使用與使用者請求相同的語言回覆。嚴格以計畫模式運作:先檢查程式碼庫,然後在修改任何檔案之前提供完整的計畫。

使用時機

  • 使用者要求將現有專案遷移或重構為六邊形架構或連接埠與適配器。
  • 使用者希望將業務邏輯與 Web 框架、ORM、資料庫、訊息佇列或外部 SDK 解耦。
  • 使用者要求一個安全、漸進式、且零破壞性變更的架構重構計畫。

核心原則

  1. 零破壞性變更(黃金法則): 保留所有既有的外部合約。路由、HTTP 方法、狀態碼、請求/回應有效負載結構、標頭、錯誤格式、CLI 標誌或佇列訊息形狀必須保持完全相同。
  2. 重構前先表徵: 在自動化合約/表徵測試覆蓋現有端點或進入點之前,絕不移動或刪除正式程式碼。
  3. 嚴格的依賴規則: 原始碼依賴必須始終指向內部的 domain。領域層不得從 Web 框架、資料庫驅動程式、ORM、序列化程式庫或外部 SDK 進行任何匯入。
  4. 技術棧慣用適應法: 根據專案偵測到的語言和生態系統(例如 TypeScript/Node、Python、Go、Java/Kotlin、C#、Rust)調整目錄路徑、命名慣例、型別結構和測試執行器。

工作流程

步驟 1:程式碼庫探索

在提出任何資料夾樹狀結構或遷移步驟之前,先掃描儲存庫:

  1. 技術棧與工具: 檢查相依性清單、編譯器/linter 配置和測試執行器,以識別語言、框架、驗證程式庫、ORM/查詢建構器和 DI 方法。
  2. 進入點與合約: 清查所有驅動型進入點(HTTP 路由、GraphQL 解析器、gRPC 服務、訊息消費者、cron 任務)、它們的驗證結構、中介軟體/攔截器和全域錯誤處理器。
  3. 外部相依性: 清查所有被驅動的副作用(資料庫、快取、HTTP/RPC 客戶端、佇列、檔案儲存、環境配置、日誌記錄器)。
  4. 當前執行流程: 追蹤資料目前如何從進入點流向持久層/外部呼叫再返回,並注意業務規則在何處與傳輸或持久層細節混合在一起。

步驟 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、FastAPI TestClient、Spring MockMvc 或 Go httptest)驗證真實的驅動型適配器與應用程式接線。

輸出格式(計畫模式)

將回覆結構化為以下精確章節:

  1. 當前架構診斷: 簡潔地清查偵測到的技術棧、進入點/端點、外部相依性和主要的耦合熱點。
  2. 目標目錄樹: 使用在儲存庫中找到的真實模組和功能名稱,提出完整的資料夾結構。
  3. 分階段執行計畫: 五個原子化、可驗證的階段:
    • 階段 1 - 表徵測試與基礎結構搭建: 建立鎖定當前行為的合約測試,建立目標資料夾、配置載入器和組合根(di/)。
    • 階段 2 - 領域提取: 提取實體、值物件、領域錯誤和 ports/in + ports/out 介面,並附帶單元測試。
    • 階段 3 - 應用程式用例與被驅動適配器: 實作用例、DTO、adapters/out 儲存庫/客戶端和持久層映射器。
    • 階段 4 - 驅動型適配器與錯誤轉譯: 重構控制器/處理器以透過映射器委派給用例,連接全域錯誤轉譯,並連接 di/。
    • 階段 5 - 舊版清理與最終驗證: 移除過時的檔案,執行完整的測試套件、linter 和型別檢查器,並驗證零合約偏差。
  4. 驗證檢查點: 每個階段結束時明確的命令或檢查,以證明在進入下一個階段之前沒有出現任何問題。

注意事項

  • 不要過早編輯程式碼: 除非使用者明確要求立即開始執行階段 1,否則首先只輸出計畫,以便他們可以檢閱模組邊界。
  • 避免對瑣碎的 CRUD 進行過度抽象: 仍然要乾淨地分離 domain、application 和 infrastructure,但保持直通的用例簡潔,而不是發明人為的領域複雜性。
  • 匹配舊版怪癖: 如果現有端點回傳非標準的狀態碼或錯誤欄位名稱,請在階段 1 中記錄它,並在 infrastructure 錯誤映射器中保留它,以免現有客戶端中斷。

相關技能