架构与系统设计 / 系统课时

定义订单 Repository 接口

定义订单 Repository 接口

订单聚合已经能表达下单、支付等领域规则后,下一步不是直接给它绑定数据库 API,而是先定义领域层需要的持久化契约。本节用一个最小可运行示例设计订单 Repository,让查询与保存都围绕聚合和领域语义展开。

学习目标

  • 解释 Repository 为什么应面向聚合根,而不是面向数据表
  • 设计具有订单领域语义的查询与保存方法
  • 避免把 PO、Mapper 或通用 CRUD 细节泄漏进领域层

Repository 解决的边界问题

Repository 的职责可以理解为“让领域层像操作一个聚合集合一样取得或保存对象”。领域模型只声明自己需要什么能力,不关心对象最终存到 MySQL、文件还是远程服务。

因此,订单 Repository 接口应放在领域层,并以 Order 聚合根作为读写边界。应用层可以调用它加载订单、执行领域行为,再把修改后的聚合保存回去;基础设施层则负责实现具体数据库访问。

一个常见误区是把表级 CRUD 直接翻译成 Repository,例如暴露 insertRow、updateStatusColumn、selectByPrimaryKey。这会让领域层开始理解列、行和更新语句,分层边界随之被破坏。

先从用例反推接口

假设当前订单模块只有两个真实需求:按订单号加载订单,以及保存新建或已修改的订单。对应接口只需要 findById 和 save。查询不存在时使用 Optional,可以把“未找到”显式交给调用方处理。

如果以后出现“判断业务单号是否已存在”或“查询买家的待支付订单”这样的真实用例,再增加有领域含义的方法。不要为了看起来完整,一开始就补齐 findAll、deleteById、count 等并未被业务需要的通用接口。

用可运行示例验证接口语义

下面的示例把领域对象、Repository 接口和一个内存实现放在同一文件中,仅用于验证接口设计。真正项目中,接口应位于领域层,数据库实现应位于基础设施层。

java
import java.math.BigDecimal;
import java.util.HashMap;
import java.util.Map;
import java.util.Optional;

public class OrderRepositoryDemo {
    enum OrderStatus {
        PENDING_PAYMENT, PAID
    }

    static final class Order {
        private final String id;
        private final BigDecimal totalAmount;
        private OrderStatus status;

        Order(String id, BigDecimal totalAmount) {
            this.id = id;
            this.totalAmount = totalAmount;
            this.status = OrderStatus.PENDING_PAYMENT;
        }

        String id() {
            return id;
        }

        BigDecimal totalAmount() {
            return totalAmount;
        }

        OrderStatus status() {
            return status;
        }

        void pay() {
            if (status != OrderStatus.PENDING_PAYMENT) {
                throw new IllegalStateException("order cannot be paid twice");
            }
            status = OrderStatus.PAID;
        }
    }

    // 领域层只声明聚合所需的持久化能力,不暴露表或 SQL。
    interface OrderRepository {
        Optional<Order> findById(String orderId);

        void save(Order order);
    }

    // 内存实现仅用于验证契约;真实数据库实现应放在基础设施层。
    static final class InMemoryOrderRepository implements OrderRepository {
        private final Map<String, Order> store = new HashMap<>();

        @Override
        public Optional<Order> findById(String orderId) {
            return Optional.ofNullable(store.get(orderId));
        }

        @Override
        public void save(Order order) {
            store.put(order.id(), order);
        }
    }

    public static void main(String[] args) {
        OrderRepository repository = new InMemoryOrderRepository();

        Order order = new Order("order-1001", new BigDecimal("199.00"));
        repository.save(order);

        Order loaded = repository.findById("order-1001")
                .orElseThrow(() -> new IllegalStateException("order not found"));
        System.out.println("found=" + loaded.id() + ", total=" + loaded.totalAmount());

        // 领域行为发生在聚合上,Repository 只负责重新保存聚合状态。
        loaded.pay();
        repository.save(loaded);
        System.out.println("status=" + repository.findById("order-1001").orElseThrow().status());
    }
}

预期输出

text
found=order-1001, total=199.00
status=PAID

这个例子刻意没有在接口中出现 OrderPO、SQL、Mapper 或数据库连接。调用方看到的只有订单聚合及其标识,这正是领域层需要保持的抽象。

处理查询和保存的几个边界

save 是否区分新增与更新,通常不应由领域接口决定。领域层表达的是“保存这个聚合的当前状态”,基础设施实现可以根据主键、版本号或数据库能力选择 INSERT、UPDATE 或 upsert。

查询方法也应谨慎控制返回内容。如果某个列表页只需要订单号、金额和状态,而且数据量很大,可以由应用层使用专门的查询模型或读模型,不必强迫 Repository 每次还原完整聚合。Repository 的主要价值是为需要执行领域行为的用例重建聚合。

当方法参数开始出现表名、列名、分页 SQL 片段,或返回值直接变成数据库 PO 时,通常说明接口已经越过领域边界。订单 Repository 应保持“加载聚合、保存聚合”的语义,把持久化技术选择留给基础设施层。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

定义订单 Repository 接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通