# Spring Boot 的干净架构、六边形架构和 DDD ## 概述该技能为在 Java 21+ Spring Boot 3.5+ 应用程序中实现简洁架构、六边形架构（端口和适配器）和领域驱动设计战术模式提供了全面的指导。它通过适当的分层和依赖关系管理确保关注点的清晰分离、独立于框架的域逻辑以及高度可测试的代码库。 ## 何时使用 * 通过明确的关注点分离来构建新的 Spring Boot 应用程序 * 将紧密耦合的代码重构为可测试的分层架构 * 实现独立于框架和基础设施的领域逻辑 * 为可交换实现设计端口和适配器 * 应用领域驱动设计战术模式（实体、值对象、聚合） * 创建可测试的业务逻辑，无需 Spring 上下文依赖 * 触发短语：**“实现干净的架构”**、**“端口和适配器模式”**、**“将域与基础设施分离”**、**“六边形架构 Spring Boot”**、**“DDD 聚合设计”** ## 说明 ### 1\.了解核心概念 #### 清晰的架构层（依赖规则）依赖关系向内流动。内层对外层一无所知。层|责任| Spring Boot 等效项 ---|---|--- **域名** |实体、值对象、领域事件、存储库接口 | `domain/` \- 没有 Spring 注释 **应用** |用例、应用程序服务、DTO、端口 | `application/` \- @Service、@Transactional **基础设施** |框架、数据库、外部 API | `基础设施/` \- @Repository、@Entity **适配器** |控制器、演示器、外部网关 | `适配器/` \- @RestController #### 六边形架构（端口和适配器） * **Domain Core** ：纯Java业务逻辑，无框架依赖 * **端口** ：定义合约的接口（驱动和驱动） * **适配器**：具体实现（JPA、REST、消息传递） #### 领域驱动设计战术模式 * **实体** ：具有身份和生命周期的对象（例如“订单”、“客户”） * **值对象**：不可变，由属性定义（例如，“Money”、“Email”） * **聚合** ：与根实体的一致性边界 * **领域事件**：捕获重要的业务事件 * **存储库** ：持久性抽象，在基础设施中实现 ### 2\.组织包结构遵循这个基于功能的包组织： com.example.order/ ├── 域/ │ ├── model/ # 实体、值对象 │ ├── event/ # 领域事件 │ ├──repository/ # 存储库接口（端口） │ └── 异常/ # 域异常 ├── 应用/ │ ├── port/in/ # 驱动端口（用例接口） │ ├── port/out/ # 驱动端口（外部服务接口） │ ├── service/ # 应用服务 │ └── dto/ # 请求/响应DTO ├── 基础设施/ │ ├── persistence/ # JPA 实体、存储库适配器 │ └── external/ # 外部服务适配器 └── 适配器/ └── 休息/ # REST 控制器 ### 3\.实现领域层（无框架）领域层必须对 Spring 或任何框架具有零依赖。 * 使用带有内置验证的不可变值对象的 Java 记录 * 将业务逻辑放在实体中，而不是服务中（富域模型） * 在领域层定义存储库接口（端口） * 使用强类型ID，防止ID混淆 * 实现领域事件以解耦副作用 * 使用工厂方法创建实体以强制不变量 ### 4\.实施应用层 * 在`application/port/in/`中创建用例接口（驱动端口） * 在`application/port/out/`中创建外部服务接口（驱动端口） * 使用`@Service`和`@Transactional`实现应用服务 * 使用 DTO 进行请求/响应，与域模型分开 * 操作成功后发布领域事件 ### 5\.实施基础设施层（适配器） * 在`infrastruction/persistence/`中创建JPA实体 * 实现在域和 JPA 实体之间映射的存储库适配器 * 使用 MapStruct 或手动映射器进行域-JPA 转换 * 为可交换实现配置条件bean * 使基础设施问题与领域逻辑隔离 ### 6\.实施适配器层 (REST) * 在`adapter/rest/`中创建REST控制器 * 注入用例接口，而不是实现 * 在 DTO 上使用 Bean 验证 * 返回正确的 HTTP 状态代码和响应 * 使用全局异常处理程序处理异常 ### 7\.应用最佳实践 1. **依赖规则**：Domain对Spring或其他框架的依赖为零 2. **不可变值对象**：使用具有内置验证的值对象的Java记录 3. **丰富的领域模型**：将业务逻辑放在实体中，而不是服务中 4. **存储库模式**：域定义接口，基础设施实现 5. **领域事件**：将副作用与主要操作分离 6. **构造函数注入**：通过final字段强制依赖 7. **DTO映射**：将领域模型与API合约分开 8. **事务边界**：将@Transactional放置在应用程序服务中 ### 8\.编写测试 * **领域测试** ：没有 Spring 上下文的纯单元测试，快速执行 * **应用程序测试** ：使用 Mockito 对模拟端口进行单元测试 * **基础设施测试**：使用 @DataJpaTest 和 Testcontainers 进行集成测试 * **适配器测试** ：使用 @WebMvcTest 进行控制器测试 ## 示例 ### 示例 1：领域层 - 具有领域事件的实体 // 域/模型/Order.java 公开课顺序{ 私有最终 OrderId id；私有最终 List 项目；私人资金总额；私人 OrderStatus 状态；私有最终ListdomainEvents = new ArrayList<>(); 私人订单（OrderId id，List 项目）{ 这个.id = id; this.items = new ArrayList<>(items); this.status = OrderStatus.PENDING; 计算总计（）； } 公共静态订单创建（列表项目）{ 验证项目（项目）；订单 order = new Order(OrderId.generate(), items); order.domainEvents.add(new OrderCreatedEvent(order.id, order.total)); 退货订单； } 公共无效确认（）{ if (状态！= OrderStatus.PENDING) { throw new DomainException("只能确认挂单"); } this.status = OrderStatus.CONFIRMED; } 公共列表 getDomainEvents() { 返回 List.copyOf(domainEvents); } 公共无效clearDomainEvents（）{ 域事件.clear(); } } ### 示例 2：域层 - 带验证的值对象 //domain/model/Money.java（值对象）公共记录 Money(BigDecimal 金额, 货币货币) { 公共资金{ if (amount.compareTo(BigDecimal.ZERO) < 0) { throw new DomainException("金额不能为负数"); } } 公共静态货币零（）{ 返回新的 Money(BigDecimal.ZERO,Currency.getInstance("EUR")); } 公共资金添加（其他资金）{ if (!this.currency.equals(other.currency)) { throw new DomainException("货币不匹配"); } return new Money(this.amount.add(other.amount), this.currency); } } ### 示例 3：域层 - 存储库端口 // 域/repository/OrderRepository.java（端口）公共接口订单存储库{ 订单保存(Order order); 可选<订单> findById(OrderId id); } ### 示例 4：应用程序层 - 用例和服务 // 应用程序/端口/in/CreateOrderUseCase.java 公共接口CreateOrderUseCase { OrderResponse createOrder(CreateOrderRequest 请求); } // application/dto/CreateOrderRequest.java 公共记录CreateOrderRequest( @NotNull UUID customerId， @NotEmpty 列表项目）{} // 应用程序/服务/OrderService.java @服务 @RequiredArgsConstructor @事务性公共类 OrderService 实现 CreateOrderUseCase { 私有最终 OrderRepository orderRepository; 私有最终 PaymentGateway 支付网关；私有最终DomainEventPublisher事件发布者； @覆盖公共 OrderResponse createOrder（CreateOrderRequest 请求）{ List items = mapItems(request.items()); 订单 order = Order.create(items); PaymentResult payment = paymentGateway.charge(order.getTotal()); if (! payment.successful()) { throw new PaymentFailedException("支付失败"); } 订单.确认(); 订单已保存 = orderRepository.save(order); 发布事件（订单）；返回 OrderMapper.toResponse(已保存); } 私人无效publishEvents（订单订单）{ order.getDomainEvents().forEach(eventPublisher::publish); order.clearDomainEvents(); } } ### 示例 5：基础设施层 - JPA 实体和适配器 //基础设施/持久性/OrderJpaEntity.java @实体 @Table(名称=“订单”) 公共类 OrderJpaEntity { @Id 私有 UUID ID； @Enumerated(EnumType.STRING) 私人 OrderStatus 状态；私有 BigDecimal 总金额； @OneToMany(cascade = CascadeType.ALL, orphanRemoval = true) 私有列表项目； } //基础设施/持久性/OrderRepositoryAdapter.java @组件 @RequiredArgsConstructor 公共类 OrderRepositoryAdapter 实现 OrderRepository { 私有最终 OrderJpaRepository jpaRepository; 私有最终 OrderJpaMapper 映射器； @覆盖公共订单保存（订单订单）{ OrderJpaEntity 实体 = mapper.toEntity(order); 返回mapper.toDomain(jpaRepository.save(entity)); } @覆盖公共可选 findById(OrderId id) { 返回 jpaRepository.findById(id.value()).map(mapper::toDomain); } } ### 示例 6：适配器层 - REST 控制器 // 适配器/rest/OrderController.java @RestController @RequestMapping("/api/orders") @RequiredArgsConstructor 公共类订单控制器{ 私有最终CreateOrderUseCase createOrderUseCase； @PostMapping 公共 ResponseEntity createOrder( @Valid @RequestBody CreateOrderRequest 请求）{ OrderResponse 响应 = createOrderUseCase.createOrder(request); URI 位置 = ServletUriComponentsBuilder .fromCurrentRequest() .path("/{id}") .buildAndExpand(response.id()) .toUri(); 返回 ResponseEntity.created(位置).body(响应); } } ### 示例 7：领域测试（无 Spring 上下文）订单测试类 { @测试无效shouldCreateOrderWithValidItems（）{ 列表项目 = List.of( 新的 OrderItem(新的 ProductId(UUID.randomUUID()), 2, 新的 Money("10.00", EUR)) ）；订单 order = Order.create(items); assertThat(order.getStatus()).isEqualTo(OrderStatus.PENDING); assertThat(order.getDomainEvents()).hasSize(1); } } ### 示例 8：应用程序测试（带有模拟的单元） @ExtendWith(MockitoExtension.class) 类 OrderServiceTest { @Mock OrderRepository orderRepository； @Mock PaymentGateway paymentGateway； @Mock DomainEventPublisher eventPublisher； @InjectMocks OrderService orderService; @测试无效shouldCreateAndConfirmOrder（）{ when( paymentGateway.charge(any())).thenReturn(new PaymentResult(true, "tx-123")); when(orderRepository.save(any())).thenAnswer(i -> i.getArgument(0)); OrderResponse 响应 = orderService.createOrder(createRequest()); assertThat(response.status()).isEqualTo(OrderStatus.CONFIRMED); 验证(eventPublisher).publish(any(OrderCreatedEvent.class)); } } ## 最佳实践 1. **依赖规则**：Domain对Spring或其他框架的依赖为零——这是最关键的原则 2. **不可变值对象**：使用Java记录作为值对象，并在紧凑的构造函数中内置验证 3. **丰富的领域模型**：将业务逻辑放在实体中，而不是服务中 - 避免贫乏的领域模型 4. **存储库模式**：域定义接口，基础设施实现 - 绝不相反 5. **领域事件**：使用事件驱动模式将副作用与主要操作分离 6. **构造函数注入**：通过带有 Lombok @RequiredArgsConstructor 的最终字段进行强制依赖 7. **DTO 映射**：将域模型与 API 合约分开 - 永远不要直接暴露实体 8. **事务边界**：将@Transactional放在应用程序服务中，而不是域层中 9. **工厂方法** ：使用静态工厂方法（如“Entity.create()”）进行具有不变强制的实体构造 10. **单独的 JPA 实体** ：将域实体与 JPA 实体分开，并在它们之间使用映射器 ## 限制和警告 ### 关键限制 * **Domain Layer Purity** ：切勿将 Spring 注解（`@Entity`、`@Autowired`、`@Component`）添加到域类中 * **依赖关系方向** ：依赖关系必须仅指向内部（域 <\- 应用程序 <\- 基础设施/适配器） * **框架隔离**：所有特定于框架的代码必须保留在基础设施和适配器层中 ### 要避免的常见陷阱 * **贫血领域模型**：仅具有 getter/setter 的实体，服务中的逻辑 - 将业务逻辑放置在实体中 * **框架泄漏**：领域层中的`@Entity`、`@Autowired` - 保持领域框架自由 * **延迟加载问题**：通过域模型公开 JPA 实体 - 使用映射器进行转换 * **循环依赖**：域聚合之间 - 使用 ID 而不是直接引用 * **缺少域事件**：直接服务调用而不是跨聚合通信的事件 * **存储库错位**：在基础设施中定义存储库接口 - 它们属于域 * **DTO 绕过** ：直接在 API 中公开域实体 - 始终将 DTO 用于外部合约 ### 性能考虑因素 * 将 JPA 实体与域模型分开以避免延迟加载问题 * 使用只读事务进行查询操作 * 针对复杂的读/写场景考虑CQRS ## 参考文献 * `references/java-clean-architecture.md` \- Java 特定模式（记录、密封类、强类型 ID） * `references/spring-boot-implementation.md` \- Spring Boot 集成（DI 模式、JPA 映射、事务管理）

干净的架构

包含技能