第16章：领域驱动设计（DDD）¶

public class Order {
    private OrderId id;           // 唯一标识
    private CustomerId customerId;
    private List<OrderItem> items;
    private OrderStatus status;
    private Money totalAmount;

    // 实体的業務行为
    public void addItem(Product product, int quantity) {
        validateCanModify();
        OrderItem item = new OrderItem(product, quantity);
        items.add(item);
        recalculateTotal();
    }

    public void confirm() {
        if (items.isEmpty()) {
            throw new DomainException("订单不能为空");
        }
        this.status = OrderStatus.CONFIRMED;
        registerEvent(new OrderConfirmedEvent(this.id));
    }

    private void validateCanModify() {
        if (status != OrderStatus.DRAFT) {
            throw new DomainException("只有草稿状态的订单可以修改");
        }
    }
}

// 值对象（Value Object）：无唯一标识，通过属性值相等性判断，且不可变
// 使用Java record实现：自动生成equals/hashCode/toString
public record Money(BigDecimal amount, Currency currency) {
    // 紧凑构造器（Compact Constructor）：在创建时校验业务规则
    public Money {
        if (amount.compareTo(BigDecimal.ZERO) < 0) {
            throw new IllegalArgumentException("金额不能为负");  // 保护不变量
        }
        Objects.requireNonNull(currency, "货币不能为空");
    }

    // 值对象的行为：返回新对象而非修改自身（不可变性）
    public Money add(Money other) {
        assertSameCurrency(other);  // 跨币种计算保护
        return new Money(amount.add(other.amount), currency);
    }

    public Money multiply(int quantity) {
        return new Money(amount.multiply(BigDecimal.valueOf(quantity)), currency);
    }

    // 私有校验：确保两个金额的币种一致
    private void assertSameCurrency(Money other) {
        if (!currency.equals(other.currency)) {
            throw new DomainException("货币类型不一致");
        }
    }
}

// 地址值对象：通过属性组合描述一个完整的概念
public record Address(String province, String city, String district, String detail) {
    // 构造时校验必填字段
    public Address {
        Objects.requireNonNull(province);
        Objects.requireNonNull(city);
    }

    // 值对象可以包含有意义的业务方法
    public String fullAddress() {
        return province + city + district + detail;
    }
}

// === 聚合根（Aggregate Root） ===
// Order是聚合根，外部只能通过Order操作内部的OrderItem
public class Order {
    private OrderId id;
    private List<OrderItem> items;  // OrderItem属于Order聚合内部，不能被外部直接访问

    // 聚合根提供操作内部对象的方法，保护业务不变量
    public void addItem(ProductId productId, String name, Money price, int qty) {
        OrderItem item = new OrderItem(productId, name, price, qty);
        this.items.add(item);
    }

    // 通过聚合根删除内部实体
    public void removeItem(ProductId productId) {
        items.removeIf(i -> i.getProductId().equals(productId));
    }
}

// OrderItem不是聚合根，生命周期依赖于Order
public class OrderItem {
    private ProductId productId;  // 通过ID引用其他聚合（而非直接持有Product对象）
    private String productName;   // 快照数据：订单创建时的商品名称
    private Money unitPrice;      // 快照数据：订单创建时的单价
    private int quantity;

    // 计算小计金额（利用值对象Money的行为）
    Money subtotal() {
        return unitPrice.multiply(quantity);
    }
}

// === 领域事件定义 ===
// 用过去式命名（OrderConfirmed），表示“已经发生的事实”
public record OrderConfirmedEvent(
    OrderId orderId,
    CustomerId customerId,
    Money totalAmount,
    LocalDateTime occurredAt       // 事件发生时间
) implements DomainEvent {
    // 便捷构造器：自动填充事件发生时间
    public OrderConfirmedEvent(OrderId orderId, CustomerId customerId, Money totalAmount) {
        this(orderId, customerId, totalAmount, LocalDateTime.now());
    }
}

// === 在聚合根中发布事件 ===
// 继承AbstractAggregateRoot获得事件发布能力（Spring Data提供）
public class Order extends AbstractAggregateRoot<Order> {
    public void confirm() {
        // 业务校验...
        this.status = OrderStatus.CONFIRMED;
        // 注册领域事件，会在仓储save()时自动发布
        registerEvent(new OrderConfirmedEvent(id, customerId, totalAmount));
    }
}

// === 事件处理器 ===
// 在另一个限界上下文中监听并处理事件，实现聚合间解耦
@Component
public class OrderEventHandler {

    // @EventListener：同步事件监听（与发布者在同一事务内）
    @EventListener
    public void onOrderConfirmed(OrderConfirmedEvent event) {
        // 触发库存扣减（跨聚合操作）
        inventoryService.deductStock(event.orderId());
    }

    // @TransactionalEventListener：在事务提交后才执行，避免事务回滚导致重复通知
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void sendNotification(OrderConfirmedEvent event) {
        // 发送订单确认通知（异步操作，不影响主流程）
        notificationService.notify(event.customerId(), "订单已确认");
    }
}

// 领域服务：处理跨实体/跨聚合的业务逻辑，不自然属于任何单个实体
@DomainService
public class PricingService {

    // 订单价格计算：涉及订单和客户两个聚合，故放在领域服务中
    public Money calculateOrderPrice(Order order, Customer customer) {
        Money basePrice = order.calculateSubtotal();    // 订单基础价

        // 第一步：根据会员等级应用折扣
        Money discounted = applyMemberDiscount(basePrice, customer.getLevel());

        // 第二步：应用满减优惠活动
        Money afterPromo = applyPromotions(discounted, order.getItems());

        return afterPromo;
    }

    // 会员折扣策略：使用模式匹配根据等级确定折扣率
    private Money applyMemberDiscount(Money price, MemberLevel level) {
        BigDecimal rate = switch (level) {
            case GOLD -> new BigDecimal("0.9");      // 金牌会员九折
            case SILVER -> new BigDecimal("0.95");    // 银牌会员九五折
            default -> BigDecimal.ONE;                // 普通用户不打折
        };
        return price.multiply(rate);
    }
}

// === 仓储接口（定义在领域层） ===
// 领域层只定义接口，不依赖任何持久化技术
public interface OrderRepository {
    Optional<Order> findById(OrderId id);          // 按ID查找聚合
    void save(Order order);                         // 保存聚合（新增或更新）
    void delete(Order order);                       // 删除聚合
    List<Order> findByCustomerId(CustomerId customerId);  // 按客户ID查询
}

// === 仓储实现（基础设施层） ===
// 使用JPA实现领域层定义的接口，体现“依赖倒置原则”
@Repository
public class JpaOrderRepository implements OrderRepository {

    @PersistenceContext
    private EntityManager em;       // JPA实体管理器

    @Override
    public Optional<Order> findById(OrderId id) {
        // 查询持久化实体，然后通过Mapper转换为领域对象
        return Optional.ofNullable(em.find(OrderEntity.class, id.value()))
                .map(OrderMapper::toDomain);  // 数据库实体 → 领域对象的转换
    }

    @Override
    public void save(Order order) {
        OrderEntity entity = OrderMapper.toEntity(order);  // 领域对象 → 数据库实体
        em.merge(entity);           // merge支持新增和更新
    }
}

// === CQRS命令端：负责写操作 ===
// 命令对象：封装写操作的意图和数据
public record CreateOrderCommand(
    CustomerId customerId,
    List<OrderItemRequest> items,
    Address shippingAddress
) {}

// 命令处理器：编排用例，调用领域对象执行业务逻辑
@Service
public class OrderCommandHandler {

    private final OrderRepository orderRepository;
    private final PricingService pricingService;

    @Transactional  // 命令处理在事务内执行，保证原子性
    public OrderId handle(CreateOrderCommand cmd) {
        // 1. 创建聚合根
        Order order = Order.create(cmd.customerId(), cmd.shippingAddress());
        // 2. 添加订单项（通过聚合根方法保护业务规则）
        cmd.items().forEach(item ->
            order.addItem(item.productId(), item.name(), item.price(), item.qty())
        );
        // 3. 持久化聚合
        orderRepository.save(order);
        return order.getId();
    }
}

// === CQRS查询端：负责读操作，可以使用专门优化的读模型 ===
// 查询对象：封装查询条件和分页参数
public record OrderSummaryQuery(CustomerId customerId, int page, int size) {}

// 查询处理器：直接从读优化的视图中查询，不经过领域模型
@Service
public class OrderQueryHandler {

    private final OrderReadRepository readRepository;  // 读专用仓储，可能是ElasticSearch/Redis等

    public Page<OrderSummaryDTO> handle(OrderSummaryQuery query) {
        return readRepository.findSummariesByCustomer(
            query.customerId(), query.page(), query.size()
        );
    }
}

// === 事件溯源（Event Sourcing）的聚合根 ===
// 不直接存储当前状态，而是存储所有事件，通过回放事件重建状态
public class Order {
    private OrderId id;
    private OrderStatus status;
    private List<DomainEvent> uncommittedEvents = new ArrayList<>();  // 未提交的新事件

    // 从历史事件序列重建聚合状态（每次加载时调用）
    public static Order reconstitute(List<DomainEvent> events) {
        Order order = new Order();
        events.forEach(order::apply);  // 依次回放每个事件
        return order;
    }

    // 业务操作：只产生事件，不直接修改状态
    public void confirm() {
        raise(new OrderConfirmedEvent(id, LocalDateTime.now()));
    }

    // 产生事件：先apply更新状态，再加入未提交列表
    private void raise(DomainEvent event) {
        apply(event);                  // 立即更新内存状态
        uncommittedEvents.add(event);  // 记录待持久化的事件
    }

    // 事件处理：根据事件类型更新聚合状态（模式匹配）
    private void apply(DomainEvent event) {
        switch (event) {
            case OrderCreatedEvent e -> {
                this.id = e.orderId();
                this.status = OrderStatus.DRAFT;       // 创建时设为草稿状态
            }
            case OrderConfirmedEvent e -> {
                this.status = OrderStatus.CONFIRMED;    // 确认时转为已确认
            }
            default -> throw new IllegalArgumentException("Unknown event");
        }
    }
}

@Service
public class IdempotentCommandHandler {

    private final EventStore eventStore;
    private final IdempotencyStore idempotencyStore;  // Redis/DB

    @Transactional
    public OrderId handle(CreateOrderCommand cmd, String idempotencyKey) {
        // 1. 检查命令是否已处理过
        if (idempotencyStore.exists(idempotencyKey)) {
            return idempotencyStore.getResult(idempotencyKey, OrderId.class);
        }

        // 2. 执行命令
        Order order = Order.create(cmd.customerId(), cmd.shippingAddress());
        eventStore.append(order.getId(), order.getUncommittedEvents());

        // 3. 记录幂等键（与事件写入在同一事务中）
        idempotencyStore.save(idempotencyKey, order.getId(), Duration.ofHours(24));

        return order.getId();
    }
}

public interface EventStore {
    /**
     * 追加事件（乐观并发控制）
     * @param expectedVersion 期望的当前版本号，防止并发写入
     * @throws OptimisticConcurrencyException 版本冲突时抛出
     */
    void append(AggregateId id, List<DomainEvent> events, long expectedVersion);
}

// 实现：每个事件携带递增版本号
@Entity
@Table(uniqueConstraints = @UniqueConstraint(
    columnNames = {"aggregate_id", "version"}  // 联合唯一约束保证幂等
))
public class EventRecord {
    @Id @GeneratedValue
    private Long id;
    private String aggregateId;
    private long version;       // 聚合内递增版本号
    private String eventType;
    private String payload;
    private Instant occurredAt;
}

@Component
public class OrderProjection {

    private final OrderReadRepository readRepo;
    private final ProjectionOffsetStore offsetStore;

    /**
     * 处理事件时记录offset，确保重放安全
     * 即使消息被重复投递（如Kafka rebalance），也不会产生副作用
     */
    @Transactional
    public void handle(DomainEvent event, long offset) {
        // 1. 检查是否已处理过此偏移量
        if (offsetStore.isProcessed("order-projection", offset)) {
            return;  // 幂等跳过
        }

        // 2. 更新读模型
        switch (event) {
            case OrderCreatedEvent e -> readRepo.insert(toSummary(e));
            case OrderConfirmedEvent e -> readRepo.updateStatus(
                e.orderId(), OrderStatus.CONFIRMED
            );
        }

        // 3. 记录已处理偏移量
        offsetStore.markProcessed("order-projection", offset);
    }
}

// === Spring Boot DDD完整代码示例 ===

// === 用户接口层：处理HTTP请求，参数校验，DTO转换 ===
@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderApplicationService orderAppService;
    private final OrderAssembler assembler;  // DTO与命令对象的转换器

    @PostMapping
    public ResponseEntity<OrderResponse> createOrder(@RequestBody @Valid CreateOrderRequest req) {
        CreateOrderCommand cmd = assembler.toCommand(req);  // 请求DTO → 命令对象
        OrderId orderId = orderAppService.createOrder(cmd);
        return ResponseEntity.status(HttpStatus.CREATED)
                .body(new OrderResponse(orderId.value()));
    }

    @PostMapping("/{orderId}/confirm")
    public ResponseEntity<Void> confirmOrder(@PathVariable String orderId) {
        orderAppService.confirmOrder(new OrderId(orderId));
        return ResponseEntity.ok().build();
    }
}

// === 应用层：编排用例流程，不包含业务规则 ===
@Service
@Transactional  // 应用层管理事务边界
public class OrderApplicationService {

    private final OrderRepository orderRepository;
    private final PricingService pricingService;     // 领域服务
    private final CustomerRepository customerRepository;

    // 创建订单用例：应用层负责编排，领域层负责业务规则
    public OrderId createOrder(CreateOrderCommand cmd) {
        // 1. 获取客户聚合
        Customer customer = customerRepository.findById(cmd.customerId())
                .orElseThrow(() -> new EntityNotFoundException("客户不存在"));

        // 2. 创建订单聚合根（工厂方法）
        Order order = Order.create(cmd.customerId(), cmd.shippingAddress());

        // 3. 通过聚合根方法添加订单项
        cmd.items().forEach(item ->
            order.addItem(item.productId(), item.name(), item.price(), item.quantity())
        );

        // 4. 调用领域服务计算最终价格
        Money finalPrice = pricingService.calculateOrderPrice(order, customer);
        order.applyFinalPrice(finalPrice);

        // 5. 持久化聚合（仓储会自动发布领域事件）
        orderRepository.save(order);
        return order.getId();
    }

    // 确认订单用例
    public void confirmOrder(OrderId orderId) {
        Order order = orderRepository.findById(orderId)
                .orElseThrow(() -> new EntityNotFoundException("订单不存在"));
        order.confirm();           // 调用聚合根的业务方法
        orderRepository.save(order);
    }
}

// === 领域层 - 聚合根：包含核心业务逻辑，不依赖任何外部框架 ===
public class Order extends AbstractAggregateRoot<Order> {

    private OrderId id;
    private CustomerId customerId;
    private Address shippingAddress;
    private List<OrderItem> items = new ArrayList<>();
    private OrderStatus status;
    private Money totalAmount;
    private LocalDateTime createdAt;

    // 静态工厂方法：封装聚合创建逻辑，确保初始状态合法
    public static Order create(CustomerId customerId, Address address) {
        Order order = new Order();
        order.id = OrderId.generate();    // 生成唯一标识
        order.customerId = customerId;
        order.shippingAddress = address;
        order.status = OrderStatus.DRAFT; // 初始状态为草稿
        order.createdAt = LocalDateTime.now();
        return order;
    }

    // 添加商品：聚合根保护业务不变量 + 自动重算总额
    public void addItem(ProductId productId, String name, Money price, int qty) {
        if (status != OrderStatus.DRAFT) {
            throw new DomainException("只有草稿订单可以添加商品");
        }
        items.add(new OrderItem(productId, name, price, qty));
        recalculateTotal();               // 保持总额与订单项一致
    }

    // 确认订单：状态转换 + 发布领域事件
    public void confirm() {
        if (items.isEmpty()) {
            throw new DomainException("空订单不能确认");
        }
        if (status != OrderStatus.DRAFT) {
            throw new DomainException("当前状态不允许确认");
        }
        this.status = OrderStatus.CONFIRMED;
        registerEvent(new OrderConfirmedEvent(id, customerId, totalAmount));  // 发布事件
    }

    // 私有方法：汇总所有订单项小计金额
    private void recalculateTotal() {
        this.totalAmount = items.stream()
                .map(OrderItem::subtotal)     // 获取每项小计
                .reduce(Money.ZERO, Money::add);  // 累加求和
    }
}

// === 基础设施层 - 仓储实现：将领域对象与数据库实体解耦 ===
@Repository
public class JpaOrderRepository implements OrderRepository {

    private final SpringDataOrderRepository springRepo;  // Spring Data JPA自动实现
    private final OrderMapper mapper;                     // 领域对象↔数据库实体双向转换

    @Override
    public Optional<Order> findById(OrderId id) {
        return springRepo.findById(id.value()).map(mapper::toDomain);
    }

    @Override
    public void save(Order order) {
        OrderEntity entity = mapper.toEntity(order);
        springRepo.save(entity);
    }
}

// === 防腐层（Anti-Corruption Layer） ===
// 用于对接第三方系统，将外部模型翻译为领域模型，防止外部概念污染领域层

// 领域层定义的支付网关接口
public interface PaymentGateway {  // interface定义类型契约
    PaymentResult pay(OrderId orderId, Money amount);
}

// 基础设施层的适配器实现：将支付宝 SDK 转换为领域接口
@Component
public class AlipayGatewayAdapter implements PaymentGateway {  // extends继承；implements实现接口

    private final AlipayClient alipayClient;  // 第三方支付宝SDK

    @Override  // @Override重写父类方法
    public PaymentResult pay(OrderId orderId, Money amount) {
        // 1. 领域模型 → 第三方格式（出站转换）
        AlipayTradePayRequest request = new AlipayTradePayRequest();
        request.setOutTradeNo(orderId.value());
        request.setTotalAmount(amount.amount().toString());

        // 2. 调用第三方API
        AlipayTradePayResponse response = alipayClient.execute(request);

        // 3. 第三方结果 → 领域模型（入站转换）
        return response.isSuccess()
                ? PaymentResult.success(response.getTradeNo())
                : PaymentResult.failure(response.getSubMsg());
    }
}