DDD-017：六边形架构（Hexagonal Architecture）
DDD-017：六边形架构（Hexagonal Architecture）
17.1 六边形架构概述
17.1.1 什么是六边形架构？
【原理】
六边形架构（Hexagonal Architecture），又称端口与适配器架构（Ports and Adapters Architecture），由 Alistair Cockburn 于 2005 年提出。其核心思想是将应用程序分为内部和外部，内部是核心业务逻辑，外部是技术实现细节，两者通过端口和适配器进行交互。
六边形架构的核心原则：
- 内外分离：核心业务逻辑独立于技术实现
- 依赖倒置：外部依赖内部，而非内部依赖外部
- 端口定义：内部定义交互接口（端口）
- 适配器实现：外部实现具体技术细节（适配器）
17.1.2 架构示意图
┌──────────────────────────────────────────────────┐ │ 外部世界 │ │ Web UI / REST API / CLI / MQ / External Services │ └───────────────┬──────────────────┬───────────────┘ │ │ ┌───────────────┼──────────────────┼───────────────┐ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Rest Adapter │ │ MQ Adapter │ │ │ │ (入站适配器) │ │ (出站适配器) │ │ │ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ ┌──────────┴─────────────┴────────────────────┴──────────────┴──────────┐ │ 六边形边界（应用边界） │ │ ┌─────────────────────────────────────────────────────────────────┐ │ │ │ 应用程序核心 │ │ │ │ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ 入站端口 │ │ 出站端口 │ │ │ │ │ │ (Driving Port) │ │ (Driven Port) │ │ │ │ │ │ OrderUseCase │ │ OrderRepository │ │ │ │ │ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ │ │ │ │ │ │ ┌──────────────────┐ │ │ │ │ │ └─────▶│ 应用服务 │◀─┘ │ │ │ │ │ OrderApplication │ │ │ │ │ │ Service │ │ │ │ │ └────────┬─────────┘ │ │ │ │ │ │ │ │ │ ┌────────▼─────────┐ │ │ │ │ │ 领域模型 │ │ │ │ │ │ Order Aggregate │ │ │ │ │ └──────────────────┘ │ │ │ │ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ │ │ └───────────────────────────────────────────────────────────────────────────┘ │ │ ┌───────────────┼────────────────────┼───────────────┐ │ ▼ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ JPA Adapter │ │ Redis Adapter │ │ │ │ (出站适配器) │ │ (出站适配器) │ │ │ └────────┬────────┘ └────────┬────────┘ │ │ │ │ │ └─────────────┬┴────────────────────┴┬─────────────┘ │ │ ┌─────────────▼──────────────────────▼─────────────┐ │ 基础设施 │ │ MySQL Database / Redis / Kafka │ └──────────────────────────────────────────────────┘17.1.3 核心概念
| 概念 | 说明 | 示例 |
|---|---|---|
| 端口（Port） | 定义应用程序与外界的交互接口 | OrderRepository、OrderUseCase |
| 适配器（Adapter） | 实现端口，连接具体技术 | JPA Repository、REST Controller |
| 入站端口（Driving Port） | 定义外部如何调用应用 | OrderUseCase 接口 |
| 出站端口（Driven Port） | 定义应用如何调用外部 | OrderRepository 接口 |
| 入站适配器（Driving Adapter） | 实现入站端口调用 | REST Controller |
| 出站适配器（Driven Adapter） | 实现出站端口接口 | JPA Repository |
17.2 端口与适配器详解
17.2.1 入站端口（Driving Port）
【原理】
入站端口定义了外部世界如何驱动应用程序执行业务用例。它是应用程序暴露给外部的服务接口。
入站端口特点：
- 定义在应用层或领域层
- 以用例为中心命名（如 CreateOrder、CancelOrder）
- 表达业务意图，不暴露技术细节
- 通常由 Application Service 实现
【代码示例】
// ========== 入站端口定义 ==========packagecom.example.order.application.port.in;/** * 订单用例接口（入站端口） * 定义外部可以执行的业务操作 */publicinterfaceOrderUseCase{/** * 创建订单 */OrderIdcreateOrder(CreateOrderCommandcommand);/** * 支付订单 */voidpayOrder(PayOrderCommandcommand);/** * 取消订单 */voidcancelOrder(CancelOrderCommandcommand);/** * 查询订单详情 */OrderDetailQueryResultqueryOrderDetail(OrderIdorderId);}// ========== 命令对象 ==========@Data@BuilderpublicclassCreateOrderCommand{privateUserIduserId;privateList<OrderItemData>items;privateCouponCodecouponCode;privateShippingAddressshippingAddress;@Data@BuilderpublicstaticclassOrderItemData{privateProductIdproductId;privateQuantityquantity;}}@Data@BuilderpublicclassPayOrderCommand{privateOrderIdorderId;privatePaymentMethodpaymentMethod;privateMoneyamount;}@Data@BuilderpublicclassCancelOrderCommand{privateOrderIdorderId;privateStringreason;}// ========== 查询结果 ==========@Data@BuilderpublicclassOrderDetailQueryResult{privateOrderIdorderId;privateOrderStatusstatus;privateMoneytotalAmount;privateLocalDateTimecreateTime;privateList<OrderItemResult>items;@Data@BuilderpublicstaticclassOrderItemResult{privateProductIdproductId;privateStringproductName;privateMoneyprice;privateQuantityquantity;privateMoneysubtotal;}}17.2.2 出站端口（Driven Port）
【原理】
出站端口定义了应用程序需要被驱动的外部依赖。它是应用程序对基础设施的需求声明。
出站端口特点：
- 定义在领域层或应用层
- 以能力命名（如 Repository、EventPublisher）
- 只定义接口，不关心实现
- 由基础设施层的适配器实现
【代码示例】
// ========== 出站端口定义 ==========packagecom.example.order.application.port.out;/** * 订单仓储接口（出站端口） * 定义数据持久化能力 */publicinterfaceOrderRepository{/** * 保存订单 */Ordersave(Orderorder);/** * 根据ID查询订单 */Optional<Order>findById(OrderIdorderId);/** * 根据用户ID查询订单列表 */List<Order>findByUserId(UserIduserId);/** * 删除订单 */voiddelete(Orderorder);}/** * 事件发布接口（出站端口） * 定义事件发布能力 */publicinterfaceEventPublisher{/** * 发布领域事件 */voidpublish(List<DomainEvent>events);/** * 发布单个事件 */defaultvoidpublish(DomainEventevent){publish(List.of(event));}}/** * 库存服务接口（出站端口） * 定义库存扣减能力 */publicinterfaceInventoryService{/** * 预留库存 */booleanreserveStock(ProductIdproductId,Quantityquantity);/** * 释放库存 */voidreleaseStock(ProductIdproductId,Quantityquantity);/** * 确认扣减库存 */voidconfirmDeduction(ProductIdproductId,Quantityquantity);}/** * 支付服务接口（出站端口） * 定义支付处理能力 */publicinterfacePaymentService{/** * 发起支付 */PaymentResultpay(PaymentRequestrequest);/** * 查询支付状态 */PaymentStatusqueryStatus(PaymentIdpaymentId);/** * 退款 */RefundResultrefund(RefundRequestrequest);}17.2.3 入站适配器（Driving Adapter）
【原理】
入站适配器实现对外部请求的接收，并将其转换为对入站端口的调用。
入站适配器特点：
- 处理特定技术协议（HTTP、MQ、CLI等）
- 负责请求解析、参数验证、异常处理
- 调用入站端口执行业务
- 将结果转换为响应格式
【代码示例】
// ========== 入站适配器 - REST Controller ==========packagecom.example.order.adapter.in.web;@RestController@RequestMapping("/api/orders")@RequiredArgsConstructorpublicclassOrderController{privatefinalOrderUseCaseorderUseCase;// 注入入站端口@PostMappingpublicResponseEntity<OrderResponse>createOrder(@RequestBody@ValidCreateOrderRequestrequest){// 1. 将请求DTO转换为命令对象CreateOrderCommandcommand=toCommand(request);// 2. 调用入站端口OrderIdorderId=orderUseCase.createOrder(command);// 3. 返回响应returnResponseEntity.status(HttpStatus.CREATED).body(newOrderResponse(orderId.getValue()));}@PostMapping("/{orderId}/payment")publicResponseEntity<Void>payOrder(@PathVariableLongorderId,@RequestBody@ValidPayOrderRequestrequest){PayOrderCommandcommand=PayOrderCommand.builder().orderId(OrderId.of(orderId)).paymentMethod(request.getPaymentMethod()).amount(Money.of(request.getAmount())).build();orderUseCase.payOrder(command);returnResponseEntity.ok().build();}@PostMapping("/{orderId}/cancellation")publicResponseEntity<Void>cancelOrder(@PathVariableLongorderId,@RequestBody@ValidCancelOrderRequestrequest){CancelOrderCommandcommand=CancelOrderCommand.builder().orderId(OrderId.of(orderId)).reason(request.getReason()).build();orderUseCase.cancelOrder(command);returnResponseEntity.ok().build();}@GetMapping("/{orderId}")publicResponseEntity<OrderDetailResponse>getOrder(@PathVariableLongorderId){OrderDetailQueryResultresult=orderUseCase.queryOrderDetail(OrderId.of(orderId));returnResponseEntity.ok(toResponse(result));}// ========== 转换方法 ==========privateCreateOrderCommandtoCommand(CreateOrderRequestrequest){returnCreateOrderCommand.builder().userId(UserId.of(request.getUserId())).items(request.getItems().stream().map(item->CreateOrderCommand.OrderItemData.builder().productId(ProductId.of(item.getProductId())).quantity(Quantity.of(item.getQuantity())).build()).collect(Collectors.toList())).couponCode(request.getCouponCode()!=null?CouponCode.of(request.getCouponCode()):null).shippingAddress(toAddress(request.getShippingAddress())).build();}}// ========== 入站适配器 - 消息消费者 ==========packagecom.example.order.adapter.in.messaging;@Component@RequiredArgsConstructorpublicclassOrderEventListener{privatefinalOrderUseCaseorderUseCase;@KafkaListener(topics="payment-completed",groupId="order-service")publicvoidonPaymentCompleted(PaymentCompletedEventevent){// 将消息事件转换为命令PayOrderCommandcommand=PayOrderCommand.builder().orderId(OrderId.of(event.getOrderId()