六边形架构¶

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

何时使用¶

在长期可维护性和可测试性至关重要的新功能开发中。
重构领域逻辑与 I/O 关注点混杂的分层或框架重型代码。
为同一用例支持多种接口（HTTP、CLI、队列 Worker、定时任务）。
在不重写业务规则的前提下替换基础设施（数据库、外部 API、消息总线）。

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

核心概念¶

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

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

依赖方向始终向内：

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

工作方式¶

第 1 步：建模用例边界¶

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

第 2 步：先定义出站端口¶

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

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

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

第 3 步：以纯编排方式实现用例¶

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

第 4 步：在边缘构建适配器¶

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

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

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

第 6 步：按边界测试¶

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

架构图¶

flowchart LR
  Client["Client (HTTP/CLI/Worker)"] --> InboundAdapter["Inbound Adapter"]
  InboundAdapter -->|"calls"| UseCase["UseCase (Application Layer)"]
  UseCase -->|"uses"| OutboundPort["OutboundPort (Interface)"]
  OutboundAdapter["Outbound Adapter"] -->|"implements"| OutboundPort
  OutboundAdapter --> ExternalSystem["DB/API/Queue"]
  UseCase --> DomainModel["DomainModel"]

建议的模块结构¶

使用功能优先的组织方式，并带有显式边界：

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;
};

export class CreateOrderUseCase {
  constructor(
    private readonly orderRepository: OrderRepositoryPort,
    private readonly paymentGateway: PaymentGatewayPort
  ) {}

  async execute(input: CreateOrderInput): Promise<CreateOrderOutput> {
    const order = Order.create({ id: input.orderId, amountCents: input.amountCents });

    const auth = await this.paymentGateway.authorize({
      orderId: order.id,
      amountCents: order.amountCents,
    });

    // markAuthorized returns a new Order instance; it does not mutate in place.
    const authorizedOrder = order.markAuthorized(auth.authorizationId);
    await this.orderRepository.save(authorizedOrder);

    return {
      orderId: order.id,
      authorizationId: auth.authorizationId,
    };
  }
}

出站适配器¶

export class PostgresOrderRepository implements OrderRepositoryPort {
  constructor(private readonly db: SqlClient) {}

  async save(order: Order): Promise<void> {
    await this.db.query(
      "insert into orders (id, amount_cents, status, authorization_id) values ($1, $2, $3, $4)",
      [order.id, order.amountCents, order.status, order.authorizationId]
    );
  }

  async findById(orderId: string): Promise<Order | null> {
    const row = await this.db.oneOrNone("select * from orders where id = $1", [orderId]);
    return row ? Order.rehydrate(row) : null;
  }
}

组合根¶

export const buildCreateOrderUseCase = (deps: { db: SqlClient; stripe: StripeClient }) => {
  const orderRepository = new PostgresOrderRepository(deps.db);
  const paymentGateway = new StripePaymentGateway(deps.stripe);

  return new CreateOrderUseCase(orderRepository, paymentGateway);
};

多语言映射¶

在不同生态系统中使用相同的边界规则；只有语法和装配方式会变化。

TypeScript/JavaScript
端口：以 application/ports/* 作为接口/类型。
用例：使用构造函数/参数注入的类/函数。
适配器：adapters/inbound/*、adapters/outbound/*。
组合：显式的工厂/容器模块（无隐藏全局变量）。
Java
包：domain、application.port.in、application.port.out、application.usecase、adapter.in、adapter.out。
端口：application.port.* 中的接口。
用例：普通类（Spring @Service 是可选的，不是必需的）。
组合：使用 Spring 配置或手动装配类；保持装配逻辑不进入领域/用例类。
Kotlin
模块/包与 Java 的分层方式保持一致（domain、application.port、application.usecase、adapter）。
端口：Kotlin 接口。
用例：使用构造函数注入的类（Koin/Dagger/Spring/手动）。
组合：模块定义或专门的组合函数；避免服务定位器模式。
Go
包：internal/<feature>/domain、application、ports、adapters/inbound、adapters/outbound。
端口：由消费方应用包定义的小型接口。
用例：带有接口字段的结构体以及显式的 New... 构造函数。
组合：在 cmd/<app>/main.go（或专门的装配包）中进行装配，保持构造函数的显式性。

应避免的反模式¶

领域实体导入 ORM 模型、Web 框架类型或 SDK 客户端。
用例直接读取 req、res 或队列元数据。
从用例直接返回数据库行，而未进行领域/应用层映射。
让适配器直接互相调用，而非经由用例端口流转。
通过隐藏的全局单例将依赖装配分散到大量文件中。

迁移手册¶

选择一个因频繁变更而带来痛点的垂直切片（单个端点/任务）。
提取一个具有显式输入/输出类型的用例边界。
围绕现有基础设施调用引入出站端口。
将编排逻辑从控制器/服务迁移到用例中。
保留旧适配器，但让它们委托给新的用例。
围绕新边界添加测试（单元测试 + 适配器集成测试）。
逐切片重复执行；避免整体重写。

重构现有系统¶

绞杀者模式：保留现有端点，一次只将一个用例路由到新的端口/适配器。
不做大爆炸式重写：按功能切片迁移，并通过特征测试保持行为不变。
门面先行：在替换内部实现之前，先将遗留服务包装到出站端口之后。
组合冻结：尽早集中装配逻辑，避免新依赖泄漏到领域/用例层。
切片选择规则：优先处理变更频繁、影响范围小的流程。
回滚路径：为每个已迁移的切片保留可逆的开关或路由切换，直到生产环境行为得到验证。

测试指南（相同的六边形边界）¶

领域测试：将实体/值对象作为纯业务规则进行测试（无模拟、无框架设置）。
用例单元测试：使用出站端口的假实现/桩来测试编排逻辑；断言业务结果和端口交互。
出站适配器契约测试：在端口级别定义共享契约套件，并针对每个适配器实现运行。
入站适配器测试：验证协议映射（HTTP/CLI/队列负载到用例输入，以及输出/错误映射回协议）。
适配器集成测试：针对真实基础设施（数据库/API/队列）运行，验证序列化、模式/查询行为、重试和超时。
端到端测试：覆盖从入站适配器 -> 用例 -> 出站适配器的关键用户旅程。
重构安全性：在提取之前添加特征测试；保留它们直到新边界行为稳定且等价。

最佳实践清单¶

领域和用例层只导入内部类型和端口。
每个外部依赖都由一个出站端口表示。
验证发生在边界处（入站适配器 + 用例不变量）。
使用不可变转换（返回新值/实体，而不是修改共享状态）。
错误在边界之间进行转换（基础设施错误 -> 应用/领域错误）。
组合根是显式的且易于审计。
用例可以通过为端口提供简单的内存假实现来进行测试。
重构从一个带有行为保持测试的垂直切片开始。
语言/框架特定内容保留在适配器中，绝不进入领域规则。

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC