707-technologies-hexagonal-architecture

Java 六边形架构边界审查

帮助团队审查并改进 Java 应用中的六边形架构边界，而不将指导与 Spring Boot、Quarkus 或 Micronaut 的运行时装配耦合。

此 Skill 涵盖哪些内容？

• 领域独立性：实体、值对象、领域服务和领域策略不依赖框架、持久化、Web、消息传递和基础设施 API
• 应用/用例编排：用例通过入站或出站端口协调领域行为，且不依赖具体适配器
• 适配器和基础设施边界：驱动适配器调用入站端口，驱动型适配器实现出站端口
• 依赖方向检查：通过包、模块、导入、Maven 模块和测试证据，确认适配器依赖核心，而非核心依赖适配器
• 可选的架构验证：当架构测试适用于项目时，使用 ArchUnit 风格规则验证六边形架构边界
• 基于证据的修复建议：问题描述引用具体类、导入、依赖、包或测试，并提出能够保持边界的小幅改动

**范围：**面向 Java 项目、与框架无关的架构边界审查。对于 Spring Boot、Quarkus 或 Micronaut 的运行时装配，请转交对应的框架 Skill。对于添加 ArchUnit 或其他 Maven 依赖，请转交 111-java-maven-dependencies。

约束

除非用户明确要求实现框架运行时功能，否则建议应聚焦于架构边界和依赖方向。编辑此代码库的 XML 源文件后，重新生成 Skills 并验证构建。

• 强制要求：在同一变更集中提出 Java 或 Maven 更改之前，运行 ./mvnw compile 或 mvn compile
• 边界：领域包不得依赖应用、适配器、基础设施、框架、持久化、Web、消息传递或依赖注入 API
• 用例：应用/用例代码可以编排领域行为并依赖入站/出站端口，但不得依赖具体适配器实现
• 适配器：驱动适配器调用入站端口，驱动型适配器实现出站端口；适配器不得演变为共享领域逻辑，也不应彼此产生不必要的依赖
• ArchUnit 可选：将 ArchUnit 视为可选的验证方式，在适用于项目时采用；不要要求先添加 ArchUnit，才能提供六边形架构指导
• 依赖：将 Maven 依赖评估（包括添加 ArchUnit 依赖）转交 111-java-maven-dependencies
• 框架转交：将 Spring Boot、Quarkus 和 Micronaut 的运行时装配转交对应的框架专用 Skill，且不要在此指导中嵌入直接的框架 Skill 链接
• 验证：在推广更改之前，运行 ./mvnw clean verify 或 mvn clean verify
• 边界情况：如果包布局、模块边界、框架归属或持久化策略存在歧义，并会影响审查，请先提出澄清问题，再编辑架构敏感代码
• 边界情况：区分已确认的边界违规、基于命名推断的约定以及缺失的上下文

何时使用此 Skill

• 审查六边形架构
• 审查端口与适配器边界
• 审查架构边界
• 强制执行依赖方向
• 添加 ArchUnit 架构测试
• 检测领域代码中的基础设施泄漏
• 改进端口与适配器边界

工作流

1. 阅读参考资料并梳理代码库

在对架构边界做出判断前，阅读 references/707-technologies-hexagonal-architecture.md，并检查软件包、模块、导入、Maven 模块、测试和框架入口点。

2. 识别端口、适配器和依赖方向

梳理领域层、应用程序/用例、入站端口、出站端口、驱动适配器、被驱动适配器和基础设施职责；记录所依据的证据，并将不明确的部分标记为假设。

3. 审查违规并提出维护边界的改进方案

报告具体的核心层对适配器依赖违规、框架或基础设施渗漏、适配器耦合和行为错位问题，并提出与现有项目结构相符的小幅修复步骤。

4. 酌情建议验证方式，并转交超出范围的工作

酌情建议采用 ArchUnit 风格的测试；将依赖项添加转交给 111-java-maven-dependencies，将框架运行时配置转交给对应的框架技能，并总结验证结果。

参考资料

如需详细指南、示例和约束，请参阅 references/707-technologies-hexagonal-architecture.md。