SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hexagonal-architecture

hexagonal-architecture

编程与开发

查看项目

更新于 10-16 12:51

技能介绍

用途

本技能适用于已明确选择加入六边形架构（端口与适配器）的项目。不要将这些模式应用于采用其他架构的项目。若要将六边形架构渐进式引入既有代码库，请参阅 resources/incremental-adoption.md。

其核心目标是把业务逻辑放在领域策略中，把用例与编排放在应用策略中，让外部系统只能通过端口（接口）与适配器（实现）连接，依赖方向始终向内。

主要能力

该技能围绕以下内容组织：

  • 核心概念：领域代码不依赖任何框架、传输协议、持久化实现、时钟、UUID 生成器、供应商 SDK 或 UI 关注点；时间、标识符与外部事实以类型化输入提供。驱动/输入适配器负责解析并翻译不可信的外部输入为类型化应用命令，然后调用应用用例；应用服务协调用例、调用领域行为并调用所需端口；被驱动/输出适配器实现其内部消费者所拥有的端口，并在边界处翻译技术特定结果。
  • 端口即公共契约：端口是内外边界上具名且有目的的对话。在类型化边界为公共或架构性场景时，用显式 interface 类型表示端口。端口命名从应用视角出发，使用会话的领域语言：驱动端口使用意图名（ForPlacingOrders、ForSendingReceipts），被驱动端口使用角色名词（OrderRepository、PaymentGateway）。给出端口命名对照表与设计原则，如不用 I 前缀、不用 Port/Impl 后缀、端口方法使用领域类型而非基础设施类型或供应商 SDK 的 DTO。
  • 适配器即实现：适配器为特定技术实现端口，负责在端口的领域类型与技术的原生类型之间翻译，不含业务逻辑。示例包括用 Drizzle/D1 实现仓库端口。

使用方式

在编写代码之前（该章节应作为指令阅读）：

  1. 第三方 SDK 的客户端类型永远不是端口。OrdersApiClient、SmtpClient、PushClient、Stripe 客户端等由供应商包或仓库 SDK 目录导出的任何内容都在六边形之外，导入它的每个文件也同样在外，包括使用 import type 以及 SDK 的 DTO 类型。
  2. 在已选择加入的代码库中添加功能时，顺序为：将业务规则放入纯内部函数（接收领域类型与 now 值）；在使用用例旁的内部声明其所需端口为导出的 interface；为每个被驱动端口编写一个导入 SDK 并翻译其形状的适配器，以及一个解析输入并调用驱动端口的驱动适配器；仅在组合根中装配 SDK 客户端 → 适配器 → 用例；通过驱动端口并配合手写的被驱动端口内存假件测试用例，单独针对 SDK 测试每个适配器。
  3. 修改仍直接导入 SDK 的用例时：在已选择加入的仓库中，移植所触碰文件的每一个 SDK 依赖是本次改动的一部分，而非范围蔓延；它是在新增行为的 RED 之前、在现有测试保持绿色的情况下进行的行为保持型 REFACTOR 步骤。
  4. 新文件的放置：适配器与假件是你自己的代码，应放在其所服务功能旁（src/<feature>/ports.ts、src/<feature>/adapters.ts、src/<feature>/testing/）或 adapters/ 文件夹，绝不放在存放 SDK 替身的文件夹中。
  5. 用例测试使用假件而非 mock：用例测试中不包含 vi.fn、vi.mock、vi.spyOn，也不导入 SDK 目录中的任何内容。

该技能还说明了与其它技能的关系：领域建模加载 domain-driven-design；设计或变更物理源码树使用 structure-codebase；端口或进程内模块的职责连贯性使用 codebase-design；在决定是否需要持久端口前刻画强耦合遗留行为使用 finding-seams。

按需加载的深度资源位于 resources/ 目录：worked-example.md（完整功能贯穿各层，含测试与文件映射）、testing-hex-arch.md（编写测试、创建假件、createTestDb、可替换性测试）、cqrs-lite.md（读取需跨聚合 JOIN、读写路径分离）、cross-cutting-concerns.md（认证、日志、事务或错误格式化的放置）、incremental-adoption.md（向既有代码库引入六边形架构）、greenfield-sequence.md（从零开始六边形项目）、references.md（查阅来源依据，尤其是端口/公共接口命名）。

适用场景

适用于已通过 README、CLAUDE.md 或 ADR 明确声明采用六边形架构的 TypeScript 项目，在其内进行新功能开发、传输或 SDK 替换、缺陷修复、小型业务规则改动等所有代码变更；也适用于既有代码库的渐进式采纳、全新六边形项目的启动、以及需要在读取侧跨聚合 JOIN 时采用 CQRS-lite 的场景。

限制

不要从项目中泛化的适配器、接口、测试接缝或隔离需求推断出六边形架构——除非项目已明确选择加入。不得将这些模式应用于使用其他架构的项目。该技能只覆盖结构与边界组织，不涉及领域建模本身（那是 DDD 技能的范畴），两者互补但相互独立，项目可以只用其一。关于本技能的价格、收费、平台支持等信息，资料中暂未提供。