使用 JFoundry
目的
使用此技能來建構基於 jfoundry 的業務應用程式,避免偏離框架預期的架構。此技能適用於應用程式專案,不適用於修改 jfoundry 框架內部。
除非使用者明確選擇洋蔥架構,否則預設採用使用六邊形架構的新 Java 21 Maven 專案。不要將執行時期框架預設為 Spring Boot;僅當使用者選擇 Spring Framework、Spring Boot 或 Spring 專用 starter 時才選擇 Spring。優先複製內建模版,然後調整名稱和套件。
首次工作流程
- 識別專案形狀:單一應用程式模組、多模組 Maven 應用程式,或分離的領域/應用程式/基礎設施模組。對於一般的 DDD 專案,偏好多模組 Maven。
- 選擇一種主要的架構風格。新的業務專案偏好六邊形架構;僅在使用者要求或程式碼庫已使用時才選擇洋蔥架構。不要在相同的 ArchUnit 分析範圍內混用六邊形和洋蔥架構。
- 閱讀
references/dependencies.md,根據執行時期選擇 BOM,並從assets/templates/maven/複製對應的 Maven 範本片段。 - 閱讀
references/architecture.md,並從assets/templates/structure/複製對應的套件結構。 - 從
assets/templates/java/複製一個架構測試範本,取代PACKAGE_NAME,並將其新增到業務專案的測試原始碼集下。 - 在建立聚合儲存庫、讀取端連接埠、查詢連接埠、查閱連接埠、讀取模型或維護連接埠之前,請閱讀
references/repository-and-ports.md。 - 在實作
AggregateData、DataConverter、MyBatis-Plus 資料物件或 MapStruct 轉換器之前,請閱讀references/persistence-data-converters.md。 - 僅在專案需要可靠的外部事件發布或等冪訊息消費時,才閱讀
references/outbox-inbox.md。 - 執行最小的相關 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.javaassets/templates/java/OnionSimpleArchitectureTest.javaassets/templates/maven/dependency-management-core.xmlassets/templates/maven/dependency-management-spring.xmlassets/templates/maven/domain-module-dependencies.xmlassets/templates/maven/application-module-dependencies.xmlassets/templates/maven/infrastructure-mybatis-plus-dependencies.xmlassets/templates/maven/architecture-test-dependencies.xmlassets/templates/maven/spring-boot-app-dependencies.xmlassets/templates/maven/spring-boot-mybatis-plus-dependencies.xmlassets/templates/maven/outbox-dependencies.xmlassets/templates/maven/outbox-mybatis-plus-dependencies.xmlassets/templates/maven/inbox-dependencies.xmlassets/templates/maven/inbox-mybatis-plus-dependencies.xmlassets/templates/maven/broker-dependencies.xmlassets/templates/structure/hexagonal-package-structure.txtassets/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-dependenciesBOMjfoundry-domain-starterjfoundry-application-starterJFoundryRules.hexagonalStrict()和JFoundryRules.jmoleculesDdd()
為新的業務專案建議的使用者提示:
使用 $use-jfoundry 為新的 Java 21 業務專案建立初始架構。
基礎套件:com.example.order
專案形狀:多模組 Maven
執行時期:未決定
持久化:MyBatis-Plus
訊息傳遞:稍後使用 Kafka,初始骨架中不包含
架構:除非您需要選擇,否則使用預設值
如果缺少詳細資訊,請提出一個簡潔的問題,或者在選擇風險較低時繼續使用上述預設值。