---

name: hexagonal-architecture description: 设计、实现和重构端口与适配器系统，具有清晰的领域边界、依赖倒置和可测试的用例编排，适用于 TypeScript、Java、Kotlin 和 Go 服务。 origin: ECC

六边形架构

六边形架构（端口与适配器）使业务逻辑独立于框架、传输和持久化细节。核心应用依赖抽象端口，适配器在边缘实现这些端口。

适用场景

• 构建需要长期可维护性和可测试性的新功能。
• 重构分层或框架耦合严重的代码，其中领域逻辑与 I/O 关注点混合。
• 为同一用例支持多种接口（HTTP、CLI、队列消费者、定时任务）。
• 替换基础设施（数据库、外部 API、消息总线）而无需重写业务规则。

当请求涉及边界、领域中心设计、重构紧耦合服务或将应用逻辑与特定库解耦时使用此技能。

核心概念

• 领域模型：业务规则和实体/值对象。不引入框架依赖。
• 用例（应用层）：编排领域行为和工作流步骤。
• 入站端口：描述应用能做什么的契约（命令/查询/用例接口）。
• 出站端口：应用所需依赖的契约（仓储、网关、事件发布者、时钟、UUID 等）。
• 适配器：端口的基础设施和交付实现（HTTP 控制器、数据库仓储、队列消费者、SDK 包装器）。
• 组合根：将具体适配器绑定到用例的单一装配位置。

出站端口接口通常位于应用层（或仅当抽象确实属于领域级别时才放在领域层），而基础设施适配器实现它们。

依赖方向始终向内：

• 适配器 -> 应用/领域
• 应用 -> 端口接口（入站/出站契约）
• 领域 -> 仅领域抽象（无框架或基础设施依赖）
• 领域 -> 不依赖外部

工作方式

步骤 1：建模用例边界

定义具有清晰输入和输出 DTO 的单一用例。将传输细节（Express req、GraphQL context、任务载荷包装器）保持在此边界之外。

步骤 2：先定义出站端口

将每个副作用识别为端口：

• 持久化（UserRepositoryPort）
• 外部调用（BillingGatewayPort）
• 横切关注点（LoggerPort、ClockPort）

端口应建模能力，而非技术。

步骤 3：用纯编排实现用例

用例类/函数通过构造函数/参数接收端口。它验证应用级不变量，协调领域规则，并返回普通数据结构。

步骤 4：在边缘构建适配器

• 入站适配器将协议输入转换为用例输入。
• 出站适配器将应用契约映射到具体 API/ORM/查询构建器。
• 映射保留在适配器中，不在用例内部。

步骤 5：在组合根中装配一切

实例化适配器，然后将它们注入用例。保持装配集中化以避免隐藏的服务定位器行为。

步骤 6：按边界测试

• 用假端口对用例进行单元测试。
• 用真实基础设施依赖对适配器进行集成测试。
• 通过入站适配器对用户流程进行端到端测试。

建议的模块布局

使用功能优先的组织方式，具有明确的边界：

src/
  features/
    orders/
      domain/
        Order.ts
        OrderPolicy.ts
      application/
        ports/
          inbound/
            CreateOrder.ts
          outbound/
            OrderRepositoryPort.ts
            PaymentGatewayPort.ts
        use-cases/
          CreateOrderUseCase.ts
      adapters/
        inbound/
          http/
            createOrderRoute.ts
        outbound/
          postgres/
            PostgresOrderRepository.ts
          stripe/
            StripePaymentGateway.ts
      composition/
        ordersContainer.ts

TypeScript 示例

端口定义

export interface OrderRepositoryPort {
  save(order: Order): Promise<void>;
  findById(orderId: string): Promise<Order | null>;
}

export interface PaymentGatewayPort {
  authorize(input: { orderId: string; amountCents: number }): Promise<{ authorizationId: string }>;
}

用例

type CreateOrderInput = {
  orderId: string;
  amountCents: number;
};

type CreateOrderOutput = {
  orderId: string;
  authorizationId: string;
};