architecture-paradigm-hexagonal

六边形（端口与适配器）范式

适用场景

• 将业务逻辑与外部依赖隔离
• 系统需要可替换的适配器以便测试

不适用场景

• 不依赖外部组件的小型脚本或实用工具
• 端口／适配器抽象会增加开销的原型

何时采用此范式

• 预计数据库、框架或用户界面会频繁变化，同时需要保持核心领域逻辑稳定时。
• 测试核心应用需要模拟复杂或运行缓慢的基础设施组件时。
• 开发团队需要为第三方集成提供清晰的入站和出站接口时。

采用步骤

1. 定义领域端口：识别与核心领域的所有交互。为发起操作的参与者（例如 UI、CLI、自动化作业）定义入站“驱动端口”，并为应用所使用的服务（例如数据库、消息总线、外部 API）定义出站“被驱动端口”。将这些端口定义为正式接口。
2. 在边界处实现适配器：针对每种外部技术，创建一个实现端口接口的“适配器”。确保核心领域完全不依赖适配器所使用的具体框架或库。
3. 组织用例：围绕业务能力组织应用功能，将其构建为服务。这些服务通过已定义的端口协调对领域的调用。
4. 实施契约测试：验证每个适配器是否正确遵守其所实现端口的预期。使用契约测试或消费者驱动的契约测试验证此行为。
5. 强制执行依赖规则：最关键的规则是，只有适配器可以依赖外部框架。通过自动化架构测试或静态分析规则来强制执行。

关键交付物

• 一份架构决策记录（ADR），正式列出端口、对应的适配器和依赖策略。
• 一组端口接口定义，存储在核心领域模块中。
• 每个适配器对应一套契约测试，以及领域和应用服务的单元测试。
• 展示入站和出站数据流的架构图，供运维团队和架构评审人员使用。

风险与缓解措施

• 端口／接口膨胀：
  • 缓解措施：端口数量过多会增加维护开销。将相关操作归并到内聚性更高、层级更高的端口中，通常按领域聚合组织。
• 抽象泄漏：
  • 缓解措施：如果端口接口暴露了传输层细节（例如 HTTP 标头），这就是“抽象泄漏”。应重构这些接口，改用以领域为中心的数据传输对象（DTO）。
• 适配器漂移：
  • 缓解措施：适配器可能与其所代表的外部技术不同步（例如数据库架构变更）。应定期自动验证适配器，例如检查 SQL 迁移是否仍符合持久化端口的预期。

具体组件

实现此范式时通常会涉及的工具和抽象的术语。它们不是依赖项，也不是 tools: frontmatter。

• boundary-validator：检查每个适配器是否符合端口契约
• adapter-generator：根据端口规范搭建主适配器和次适配器的脚手架
• contract-tester：通过共享契约测试验证每个适配器是否符合其端口

退出标准

• 端口接口定义为正式契约（接口、抽象类或类型别名），并存放在核心领域模块中，而不是适配器目录中。
• ADR 列出每个入站驱动端口和出站驱动端口，以及对应的适配器实现和依赖策略。
• 自动化架构测试（例如 ArchUnit、dep-cruise）确保适配器不会直接导入其他适配器或核心的内部实现。
• 每个适配器至少有一项契约测试，用于验证其是否正确满足端口的预期要求，然后才能合并该适配器。