📚 课程目录第4章支付订单聚合根设计

4. 支付订单聚合根设计：订单聚合根（Order Aggregate Root）的职责与属性

在支付订单服务中，订单聚合根（Order Aggregate Root）是整个聚合的入口与一致性边界。它负责封装订单的核心状态，确保所有对订单子实体（如支付记录、退款单、物流单）的修改都必须通过聚合根进行，从而维护业务不变量的强一致性。

4.1 聚合根的核心职责

订单聚合根并非简单的数据容器，而是承担了以下五项关键职责：

生命周期管理：控制订单从“待支付”到“已取消”、“已支付”、“已退款”等状态的合法流转，禁止非法状态跃迁。
业务规则校验：在每次状态变更或金额修改前，执行领域规则（如：已支付订单不可重复支付、退款金额不得超过实付金额）。
子实体协调：统一管理支付记录、退款单、物流单等子实体的创建与更新，确保子实体与聚合根状态一致。
事件发布：在关键状态变更后（如支付成功、退款完成），生成领域事件并推送至消息队列，供其他限界上下文消费。
缓存一致性入口：作为缓存写入与失效的唯一决策点，避免多个服务实例同时修改订单数据导致缓存与数据库不一致。

  设计原则：聚合根应保持“小聚合”粒度，仅包含强一致性要求的属性与子实体。对于弱一致性场景（如订单日志、用户浏览记录），应拆分至其他聚合或限界上下文。

4.2 聚合根的属性设计

订单聚合根的属性可划分为四类：标识与基础信息、金额与支付信息、状态与时间戳、版本与并发控制。下表列出了核心属性及其说明：

分类	属性名	类型	说明
标识与基础信息	orderId	String / UUID	全局唯一订单标识，聚合根 ID
	userId	String	下单用户标识，用于权限校验与查询路由
	merchantId	String	商户标识，用于分账与对账
金额与支付信息	totalAmount	Money（BigDecimal）	订单原始总金额，不含优惠
	payableAmount	Money（BigDecimal）	实际应付金额（总金额 - 优惠）
	paidAmount	Money（BigDecimal）	已支付金额，用于部分退款校验
状态与时间戳	orderStatus	Enum（OrderStatus）	核心状态：PENDING、PAID、CANCELLED、REFUNDING、REFUNDED
	createdAt	Instant	订单创建时间，用于缓存过期策略
	updatedAt	Instant	最后更新时间，用于乐观锁与缓存失效
版本与并发控制	version	Long	乐观锁版本号，防止并发写冲突
版本与并发控制	cacheKey	String	Redis 缓存键，由聚合根 ID 与版本号拼接而成

建模提示：cacheKey 属性并非持久化字段，而是聚合根在加载时根据 orderId 与 version 动态生成的运行时属性，用于缓存穿透防护与缓存更新。

4.3 聚合根的行为方法

聚合根通过领域方法封装业务逻辑，而非直接暴露 setter。以下是核心行为方法及其职责：

createOrder(userId, merchantId, totalAmount, discount)：创建订单，初始化状态为 PENDING，计算 payableAmount。
markPaid(paymentId, paidAmount)：标记支付成功，校验 paidAmount 是否等于 payableAmount，更新状态为 PAID，生成 OrderPaidEvent。
cancel(reason)：取消订单，仅允许 PENDING 状态取消，生成 OrderCancelledEvent。
applyRefund(refundAmount, refundReason)：发起退款，校验 refundAmount ≤ paidAmount，状态变更为 REFUNDING，生成 RefundRequestedEvent。
completeRefund(refundId)：完成退款，更新 paidAmount，若 paidAmount 归零则状态变更为 REFUNDED。

// 聚合根核心方法示例（伪代码）
public class OrderAggregate {
    private String orderId;
    private OrderStatus status;
    private Money payableAmount;
    private Money paidAmount;
    private Long version;

    public void markPaid(String paymentId, Money paidAmount) {
        if (this.status != OrderStatus.PENDING) {
            throw new DomainException("订单状态不允许支付");
        }
        if (!paidAmount.equals(this.payableAmount)) {
            throw new DomainException("支付金额与应付金额不一致");
        }
        this.status = OrderStatus.PAID;
        this.paidAmount = paidAmount;
        this.version++;
        // 发布领域事件
        DomainEventPublisher.publish(new OrderPaidEvent(this.orderId, paymentId));
    }
}

4.4 聚合根与 Redis 缓存策略的映射

订单聚合根是缓存策略的核心决策单元。以下 SVG 图展示了聚合根如何驱动缓存写入、失效与穿透防护：

4.5 聚合根设计中的常见陷阱

避坑指南：以下三个错误在支付订单聚合根设计中最为常见：

过度膨胀：将订单日志、用户地址、商品快照等弱一致性数据塞入聚合根，导致聚合过大、并发冲突频繁。
状态枚举缺失：使用字符串表示状态，导致非法状态跃迁无法在编译期或运行时被有效拦截。
忽略版本号：未使用乐观锁或版本号，导致高并发下缓存与数据库出现脏写。

4.6 聚合根与子实体的关系

订单聚合根通常包含以下子实体，它们通过聚合根的统一入口进行管理：

子实体	生命周期	访问方式
PaymentRecord（支付记录）	由 markPaid() 创建，不可修改	order.getPaymentRecords()
RefundOrder（退款单）	由 applyRefund() 创建，completeRefund() 关闭	order.getRefundOrders()
OrderItem（订单项）	由 createOrder() 创建，只读	order.getItems()

所有子实体的修改都必须通过聚合根的方法完成，禁止外部直接调用子实体的 setter 或修改其状态。这一约束是 DDD 聚合设计的核心原则，也是保障缓存一致性的基础。