转向六边形架构 是做什么的?
深入分析现有仓库,设计一个原子化、分阶段的重构计划,将其迁移到 六边形架构(端口与适配器),同时不破坏任何外部契约或可观察行为。
使用与用户请求相同的语言进行回复。严格在 计划模式 下操作:首先检查代码库,在修改任何文件之前交付完整的计划。
何时使用
- 用户要求将现有项目迁移或重构为六边形架构或端口与适配器。
- 用户希望将业务逻辑与 Web 框架、ORM、数据库、消息代理或外部 SDK 解耦。
- 用户请求一个安全、增量式的架构重构计划,且要求零破坏性变更。
核心原则
- 零破坏性变更(黄金法则): 保留每一个现有的外部契约。路由、HTTP 方法、状态码、请求/响应负载模式、标头、错误格式、CLI 标志或队列消息形状必须保持完全相同。
- 重构前先特征化: 在自动化契约/特征测试覆盖现有端点或入口点之前,绝不移动或删除生产逻辑。
- 严格依赖规则: 源代码依赖必须始终向内指向
domain。领域层不能有任何对 Web 框架、数据库驱动程序、ORM、序列化库或外部 SDK 的导入。 - 符合技术栈惯用方式: 根据检测到的语言和生态系统(例如 TypeScript/Node、Python、Go、Java/Kotlin、C#、Rust),调整目录路径、命名约定、类型构造和测试运行器。
工作流程
步骤 1:代码库发现
在提出任何文件夹树或迁移步骤之前,扫描仓库:
- 技术栈和工具: 检查依赖清单、编译器/linter 配置和测试运行器,以识别语言、框架、验证库、ORM/查询构建器和 DI 方法。
- 入口点和契约: 盘点所有驱动入口点(HTTP 路由、GraphQL 解析器、gRPC 服务、消息消费者、定时任务)、它们的验证模式、中间件/拦截器和全局错误处理器。
- 外部依赖: 盘点所有驱动的副作用(数据库、缓存、HTTP/RPC 客户端、队列、文件存储、环境配置、日志记录器)。
- 当前执行流程: 追踪数据当前如何从入口点流向持久化/外部调用并返回,注意业务规则与传输或持久化细节混合的地方。
步骤 2:设计目标六边形布局
将三个同心层映射到项目惯用的源代码根目录(例如,TypeScript/Rust 中的 src/,Go 中的 internal/,JVM 中的 src/main/<lang>/,或 Python 中的主包目录):
domain/(纯业务核心 - 零框架或 I/O 依赖):entities/和value-objects/:封装业务规则、不变条件和自验证的领域模型。ports/in/:定义用例契约的驱动端口接口。ports/out/:定义仓库、外部服务、事件发布器和LoggerPort契约的被驱动端口接口。errors/:语义化领域异常(例如ResourceNotFoundError、DomainValidationError、ConflictError)。
application/(用例编排):use-cases/:ports/in的实现,协调领域实体和ports/out。dtos/:与传输负载和持久化实体解耦的不可变输入和输出数据结构。
infrastructure/(技术细节和适配器):adapters/in/:驱动适配器(HTTP 控制器/处理器、消费者处理器)、传输验证模式、映射器(TransportInput -> InputDTO和OutputDTO -> TransportOutput),以及一个将domain/errors转换为完全相同的旧错误响应的全局错误映射器。adapters/out/:ports/out的具体实现(数据库仓库、HTTP 客户端、代理)以及持久化/外部映射器,使 ORM 模型或 SDK 类型永远不会泄漏到domain/。config/:环境变量和运行时设置的严格加载和启动验证。di/(组合根):通过构造函数注入明确地连接被驱动适配器、用例和驱动适配器,避免隐藏单例或服务定位器。
- 引导分离: 将应用程序构建(
buildApp/ 用于隔离集成测试的工厂函数)与服务器/进程启动(main/listen)分离。
步骤 3:在计划中强制执行工程标准
确保计划中的每个阶段都强制执行:
- 强类型和不可变性: 禁止非类型化转义(例如
any或应该使用类型化结构的地方使用原始非类型化映射),并倾向于使用不可变的 DTO 和值对象(readonly、冻结的数据类、记录、值类型)。 - SOLID 和构造函数注入: 保持类和函数小巧且职责单一;通过构造函数注入接口。
- 无耦合的可观察性: 保留结构化日志记录和请求关联上下文,同时通过
LoggerPort使domain/和application/与特定日志记录库解耦。 - 金字塔形测试:
domain/的单元测试(纯不变条件)和application/的单元测试(模拟ports/out)。- 使用技术栈原生的内存测试客户端(例如
fastify.inject、Supertest、FastAPITestClient、SpringMockMvc或 Gohttptest)验证真实驱动适配器与应用程序连接性的集成/契约测试。
输出格式(计划模式)
将响应组织成以下确切部分:
- 当前架构诊断: 所检测到的技术栈、入口点/端点、外部依赖以及主要耦合热点的简要清单。
- 目标目录树: 使用在仓库中找到的真实的模块和特性名称,展示提议的完整文件夹结构。
- 分阶段执行计划: 五个原子化、可验证的阶段:
- 阶段 1 - 特征测试和基础脚手架: 创建锁定当前行为的契约测试,创建目标文件夹、配置加载器和组合根(
di/)。 - 阶段 2 - 领域提取: 提取实体、值对象、领域错误以及
ports/in+ports/out接口及其单元测试。 - 阶段 3 - 应用用例和被驱动适配器: 实现用例、DTO、
adapters/out仓库/客户端和持久化映射器。 - 阶段 4 - 驱动适配器和错误转换: 重构控制器/处理器,使其通过映射器委托给用例,连接全局错误转换,并连接
di/。 - 阶段 5 - 旧代码清理和最终验证: 删除过时文件,运行完整的测试套件、linter 和类型检查器,并验证零契约漂移。
- 阶段 1 - 特征测试和基础脚手架: 创建锁定当前行为的契约测试,创建目标文件夹、配置加载器和组合根(
- 验证检查点: 在每个阶段结束时,提供明确的命令或检查,以证明在进入下一阶段之前没有任何破坏。
注意事项
- 不要过早编辑代码: 除非用户明确要求立即开始执行阶段 1,否则首先仅输出计划,以便他们可以审查模块边界。
- 避免对简单的 CRUD 过度抽象: 仍然干净地分离
domain、application和infrastructure,但保持传透用例简洁,而不是人为地增加领域复杂性。 - 匹配遗留怪异之处: 如果现有端点返回非标准的状态码或错误字段名,请在阶段 1 中记录它,并在
infrastructure的错误映射器中保留它,以使现有客户端不中断。