
关于
设计、实现和重构端口与适配器系统,具有清晰的领域边界、依赖反转和可测试的用例编排,跨 TypeScript、Java、Kotlin 和 Go 服务。
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;
};
兼容工具
Claude CodeCursor
标签
前端开发
