使用 JFoundry
目的
使用此技能基于 jfoundry 构建业务应用程序,且不偏离框架预期的架构。它适用于应用程序项目,不适用于更改 jfoundry 框架内部结构。
默认创建一个新的 Java 21 Maven 项目,采用六边形架构,除非用户明确选择洋葱架构。不要默认使用 Spring Boot 运行时框架;仅在用户选择了 Spring Framework、Spring Boot 或 Spring 特定启动器时才选择 Spring。优先复制捆绑的模板,然后调整名称和包结构。
首次使用工作流
- 确定项目形态:单个应用程序模块、多模块 Maven 应用,还是独立的 domain/application/infrastructure 模块。对于常规 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 启动器放在 boot/runtime 程序集模块中,绝不要放在领域或应用程序模块中。
- 将用例编排和面向事务的工作流放在应用层。
- 将出站需求表达为次要端口。将 MyBatis、JPA、Redis、HTTP 客户端、MQ 客户端和其他技术细节放在基础设施适配器中。
- 在 jfoundry 六边形或洋葱架构项目中,主要适配器(如控制器、消息监听器、CLI 命令和调度程序)必须调用主要端口或应用程序服务,而不是直接调用次要适配器。
- 使用聚合仓库进行聚合生命周期管理和命令端聚合加载。对于非聚合读取,优先使用读端端口,并且仅当这种区分对项目有帮助时,才将其拆分为查找/读取模型/维护角色。
- 保持持久化数据转换器为基础设施本地私有。优先使用带有
INSTANCE的 MapStruct@Mapper接口;保持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 或代理启动器,除非用例需要它们。
参考路由
- 当用户启动一个新项目或询问如何调用此技能时,阅读
references/first-use.md。 - 有关包角色、注解、依赖方向和架构风格选择,请阅读
references/architecture.md。 - 有关启动器选择和 Maven 片段,请阅读
references/dependencies.md。 - 在建模持久化、聚合仓库、读取模型或查询端口之前,请阅读
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,初始骨架中不包含
架构:默认,除非您需要选择
如果缺少详细信息,请提出一个简洁的问题,或者在上面的默认值选择风险较低时按默认值进行。