Communitygithub.com

xfoundries/software-architecture-skills

提供基於領域驅動設計、分層架構、洋蔥架構、六邊形架構(Ports and Adapters)及 CQRS 的業務領域系統原始碼感知架構指導。

software-architecture-skills 是什麼?

此技能旨在協助開發者使用 JFoundry 框架建構符合預設架構規範的業務應用程式,避免偏離框架設計意圖。它支援 Java 21 與 Maven 專案,預設採用六邊形架構(Hexagonal Architecture),並提供一系列參考文件和範本,包括架構選擇、依賴管理、儲存庫與連接埠設計、持久化資料轉換器、Outbox/Inbox 模式等。技能強調領域程式碼保持框架無關,透過 ArchUnit 測試強制執行架構規則,並提供從專案初始化到架構測試的完整工作流程。開發者可透過複製內建範本並替換佔位符來快速建立專案骨架,避免從頭編寫重複程式碼。此技能適用於 Cursor、Claude Code 等 AI 編碼代理,幫助使用者遵循統一的架構風格並減少設計決策偏差。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add xfoundries/software-architecture-skills

在你喜歡的 AI 中提問

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

說明文件

使用 JFoundry

目的

使用此技能來建構基於 jfoundry 的業務應用程式,避免偏離框架預期的架構。此技能適用於應用程式專案,不適用於修改 jfoundry 框架內部。

除非使用者明確選擇洋蔥架構,否則預設採用使用六邊形架構的新 Java 21 Maven 專案。不要將執行時期框架預設為 Spring Boot;僅當使用者選擇 Spring Framework、Spring Boot 或 Spring 專用 starter 時才選擇 Spring。優先複製內建模版,然後調整名稱和套件。

首次工作流程

  1. 識別專案形狀:單一應用程式模組、多模組 Maven 應用程式,或分離的領域/應用程式/基礎設施模組。對於一般的 DDD 專案,偏好多模組 Maven。
  2. 選擇一種主要的架構風格。新的業務專案偏好六邊形架構;僅在使用者要求或程式碼庫已使用時才選擇洋蔥架構。不要在相同的 ArchUnit 分析範圍內混用六邊形和洋蔥架構。
  3. 閱讀 references/dependencies.md,根據執行時期選擇 BOM,並從 assets/templates/maven/ 複製對應的 Maven 範本片段。
  4. 閱讀 references/architecture.md,並從 assets/templates/structure/ 複製對應的套件結構。
  5. 從 assets/templates/java/ 複製一個架構測試範本,取代 PACKAGE_NAME,並將其新增到業務專案的測試原始碼集下。
  6. 在建立聚合儲存庫、讀取端連接埠、查詢連接埠、查閱連接埠、讀取模型或維護連接埠之前,請閱讀 references/repository-and-ports.md。
  7. 在實作 AggregateData、DataConverter、MyBatis-Plus 資料物件或 MapStruct 轉換器之前,請閱讀 references/persistence-data-converters.md。
  8. 僅在專案需要可靠的外部事件發布或等冪訊息消費時,才閱讀 references/outbox-inbox.md。
  9. 執行最小的相關 Maven 驗證指令,通常是 mvn test 或模組範圍的 mvn -pl <module> test。

核心規則

  • 保持領域程式碼不受 Spring、MyBatis、持久化模型、訊息代理用戶端和框架生命週期 API 的影響。
  • 當規則和不變量有意義時,在領域中對業務行為進行建模;對於低複雜度的區域,使用更簡單的 CRUD 或交易腳本。
  • 對於非平凡的領域行為,在編碼前確認聚合、命令、不變量、事件、儲存庫和讀取端連接埠的假設;保持開放的領域問題可見。
  • Spring Boot starters 只能放在 boot/runtime 組合模組中,絕不能放在領域或應用程式模組中。
  • 將用例編排和交易面向的工作流程放在應用層。
  • 將對外需求表達為次要連接埠。將 MyBatis、JPA、Redis、HTTP 用戶端、MQ 用戶端和其他技術細節放在基礎設施適配器中。
  • 在 jfoundry 六邊形或洋蔥專案中,主要適配器(如控制器、訊息監聽器、CLI 指令和排程器)必須呼叫主要連接埠或應用程式服務,而不是直接呼叫次要適配器。
  • 使用聚合儲存庫來管理聚合生命週期和命令端的聚合載入。對於非聚合的讀取,偏好使用讀取端連接埠,並僅在該區分有助於專案時,將其拆分為查閱/讀取模型/維護角色。
  • 保持持久化資料轉換器為基礎設施本地。偏好使用 MapStruct @Mapper 介面和 INSTANCE;保持 toEntity(...) 明確,並呼叫聚合的 restore(...)。
  • 僅在需要可靠地發布給外部程序或代理時,才啟用 Outbox。當事件保持在進程內時,使用本地領域事件分發。
  • 僅當消費者必須安全處理重複傳遞時,才啟用 Inbox。
  • 及早新增 ArchUnit 測試。它們是專案骨架的一部分,而不是後期清理。

內建模版

複製範本,而不是從記憶中重新編寫:

  • assets/templates/java/HexagonalArchitectureTest.java
  • assets/templates/java/OnionSimpleArchitectureTest.java
  • assets/templates/maven/dependency-management-core.xml
  • assets/templates/maven/dependency-management-spring.xml
  • assets/templates/maven/domain-module-dependencies.xml
  • assets/templates/maven/application-module-dependencies.xml
  • assets/templates/maven/infrastructure-mybatis-plus-dependencies.xml
  • assets/templates/maven/architecture-test-dependencies.xml
  • assets/templates/maven/spring-boot-app-dependencies.xml
  • assets/templates/maven/spring-boot-mybatis-plus-dependencies.xml
  • assets/templates/maven/outbox-dependencies.xml
  • assets/templates/maven/outbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/inbox-dependencies.xml
  • assets/templates/maven/inbox-mybatis-plus-dependencies.xml
  • assets/templates/maven/broker-dependencies.xml
  • assets/templates/structure/hexagonal-package-structure.txt
  • assets/templates/structure/onion-simple-package-structure.txt

取代諸如 PACKAGE_NAME 和 JFOUNDRY_VERSION 之類的佔位符。保持可選片段為可選;除非用例需要,否則不要新增 Outbox、Inbox、MyBatis-Plus 或代理 starters。

參考文件路由

  • 當使用者正在啟動新專案或詢問如何呼叫此技能時,請閱讀 references/first-use.md。
  • 閱讀 references/architecture.md 以了解套件角色、註解、依賴方向和架構風格選擇。
  • 閱讀 references/dependencies.md 以了解 starter 選擇和 Maven 片段。
  • 在建立持久化模型、聚合儲存庫、讀取模型或查詢連接埠之前,請閱讀 references/repository-and-ports.md。
  • 在編寫 DataConverter 實作、持久化資料物件或 MapStruct 映射規則之前,請閱讀 references/persistence-data-converters.md。
  • 在新增事件外部化、代理適配器、Outbox 表格、分發器或消費者等冪性之前,請閱讀 references/outbox-inbox.md。
  • 在新增或變更架構測試之前,請閱讀 references/testing.md。

常見的首次提示

引導新專案時,首先詢問基礎套件、專案/模組形狀、執行時期堆疊、持久化選擇,以及是否需要外部訊息傳遞。如果使用者沒有偏好,則繼續使用:

  • Java 21
  • Maven
  • 尚未綁定執行時期框架
  • 六邊形架構
  • jfoundry-dependencies BOM
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() 和 JFoundryRules.jmoleculesDdd()

為新的業務專案建議的使用者提示:

使用 $use-jfoundry 為新的 Java 21 業務專案建立初始架構。
基礎套件:com.example.order
專案形狀:多模組 Maven
執行時期:未決定
持久化:MyBatis-Plus
訊息傳遞:稍後使用 Kafka,初始骨架中不包含
架構:除非您需要選擇,否則使用預設值

如果缺少詳細資訊,請提出一個簡潔的問題,或者在選擇風險較低時繼續使用上述預設值。

相關技能