Communitygithub.com

xfoundries/software-architecture-skills

基于源码感知的业务领域架构指导,支持领域驱动设计、分层架构、洋葱架构、六边形架构/端口与适配器以及CQRS。

software-architecture-skills 是什么?

该技能旨在为使用 JFoundry 框架构建业务应用的开发者提供架构层面的智能指导,确保项目遵循框架预期的架构规范,避免设计漂移。它支持多种企业级架构风格,包括六边形架构(默认)、洋葱架构、领域驱动设计(DDD)以及 CQRS,并能够根据用户选择的运行时(如 Spring Boot 或无运行时绑定)和持久化方案(如 MyBatis-Plus)自动匹配合适的依赖模板和包结构。技能内置了丰富的模板资产和参考文档,涵盖项目结构、依赖管理、聚合仓库、数据转换器、Outbox/Inbox 模式等关键决策点,并强制要求通过 ArchUnit 测试来维护架构边界。通过将领域代码与框架技术细节严格分离,该技能帮助开发者构建高内聚、低耦合、可测试的业务系统。

兼容平台~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 特定启动器时才选择 Spring。优先复制捆绑的模板,然后调整名称和包结构。

首次使用工作流

  1. 确定项目形态:单个应用程序模块、多模块 Maven 应用,还是独立的 domain/application/infrastructure 模块。对于常规 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 启动器放在 boot/runtime 程序集模块中,绝不要放在领域或应用程序模块中。
  • 将用例编排和面向事务的工作流放在应用层。
  • 将出站需求表达为次要端口。将 MyBatis、JPA、Redis、HTTP 客户端、MQ 客户端和其他技术细节放在基础设施适配器中。
  • 在 jfoundry 六边形或洋葱架构项目中,主要适配器(如控制器、消息监听器、CLI 命令和调度程序)必须调用主要端口或应用程序服务,而不是直接调用次要适配器。
  • 使用聚合仓库进行聚合生命周期管理和命令端聚合加载。对于非聚合读取,优先使用读端端口,并且仅当这种区分对项目有帮助时,才将其拆分为查找/读取模型/维护角色。
  • 保持持久化数据转换器为基础设施本地私有。优先使用带有 INSTANCE 的 MapStruct @Mapper 接口;保持 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 或代理启动器,除非用例需要它们。

参考路由

  • 当用户启动一个新项目或询问如何调用此技能时,阅读 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-dependencies BOM
  • jfoundry-domain-starter
  • jfoundry-application-starter
  • JFoundryRules.hexagonalStrict() 和 JFoundryRules.jmoleculesDdd()

为新业务项目建议的用户提示:

使用 $use-jfoundry 为一个新的 Java 21 业务项目创建初始架构。
基础包:com.example.order
项目形态:多模块 Maven
运行时:未决定
持久化:MyBatis-Plus
消息传递:稍后使用 Kafka,初始骨架中不包含
架构:默认,除非您需要选择

如果缺少详细信息,请提出一个简洁的问题,或者在上面的默认值选择风险较低时按默认值进行。

相关技能