架构与系统设计 / 系统课时
在基础设施层实现订单持久化
在基础设施层实现订单持久化
定义好订单 Repository 契约后,基础设施层需要把领域对象真正落到数据库。本节用 PO、Mapper、Assembler 和 Repository Implementation 组成一条完整持久化链路,并通过可运行的 JDBC 示例验证保存与重建订单的过程。
学习目标
- 区分领域对象、PO、Mapper、Assembler 和 Repository Implementation 的职责
- 实现订单聚合到数据库记录的双向转换
- 验证基础设施实现没有把数据库细节泄漏到领域接口
把持久化职责拆成四类对象
订单持久化最容易失控的地方,是让一个类同时理解领域规则、SQL、字段映射和对象转换。拆分后,每个对象只承担一种变化来源:OrderPO 对应数据库结构,Mapper 负责 SQL,Assembler 负责领域对象与 PO 的转换,OrderRepositoryImpl 负责实现领域层声明的 Repository 契约。

这条链路的关键不是类名是否固定,而是依赖方向是否正确:基础设施实现可以依赖领域层定义的 OrderRepository 和 Order,领域层不能反过来依赖 OrderPO 或 Mapper。
定义数据库结构和持久化模型
示例使用 H2 内存数据库,表中只保存订单标识、总金额和状态。OrderPO 只反映持久化需要,不承载“支付是否允许”之类领域规则。
运行示例前,需要在 Maven 项目中加入 H2。下面是 pom.xml 的依赖片段示例,需放在现有 <dependencies> 中。
<dependency>
<groupId>com.h2database</groupId>
<artifactId>h2</artifactId>
<version>2.3.232</version>
</dependency>该依赖生效后,JDBC 可以通过 jdbc:h2:mem:orders 创建内存数据库;程序退出后数据随进程结束而释放。
完成 Mapper、Assembler 与 Repository 实现
下面的单文件示例包含完整领域接口和基础设施实现。Mapper 只处理 SQL 与 OrderPO,Assembler 只处理模型转换,Repository Implementation 负责把两者串起来。
import java.math.BigDecimal;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.sql.Statement;
import java.util.Optional;
public class OrderPersistenceDemo {
private static final String URL = "jdbc:h2:mem:orders;DB_CLOSE_DELAY=-1";
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, OrderStatus status) {
this.id = id;
this.totalAmount = totalAmount;
this.status = status;
}
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;
}
}
interface OrderRepository {
Optional<Order> findById(String orderId);
void save(Order order);
}
record OrderPO(String id, BigDecimal totalAmount, String status) {
}
static final class OrderAssembler {
// 转换职责集中在 Assembler,领域对象不感知数据库字段模型。
OrderPO toPO(Order order) {
return new OrderPO(
order.id(),
order.totalAmount(),
order.status().name()
);
}
Order toDomain(OrderPO po) {
return new Order(
po.id(),
po.totalAmount(),
OrderStatus.valueOf(po.status())
);
}
}
static final class OrderMapper {
void save(OrderPO po) throws SQLException {
// 先更新再插入,用最少 SQL 表达 Repository 的 save 语义。
String updateSql = "UPDATE orders SET total_amount = ?, status = ? WHERE id = ?";
try (Connection connection = DriverManager.getConnection(URL);
PreparedStatement statement = connection.prepareStatement(updateSql)) {
statement.setBigDecimal(1, po.totalAmount());
statement.setString(2, po.status());
statement.setString(3, po.id());
int updated = statement.executeUpdate();
if (updated == 0) {
insert(po);
}
}
}
private void insert(OrderPO po) throws SQLException {
String insertSql = "INSERT INTO orders(id, total_amount, status) VALUES (?, ?, ?)";
try (Connection connection = DriverManager.getConnection(URL);
PreparedStatement statement = connection.prepareStatement(insertSql)) {
statement.setString(1, po.id());
statement.setBigDecimal(2, po.totalAmount());
statement.setString(3, po.status());
statement.executeUpdate();
}
}
Optional<OrderPO> findById(String orderId) throws SQLException {
String sql = "SELECT id, total_amount, status FROM orders WHERE id = ?";
try (Connection connection = DriverManager.getConnection(URL);
PreparedStatement statement = connection.prepareStatement(sql)) {
statement.setString(1, orderId);
try (ResultSet resultSet = statement.executeQuery()) {
if (!resultSet.next()) {
return Optional.empty();
}
return Optional.of(new OrderPO(
resultSet.getString("id"),
resultSet.getBigDecimal("total_amount"),
resultSet.getString("status")
));
}
}
}
}
static final class OrderRepositoryImpl implements OrderRepository {
private final OrderMapper mapper;
private final OrderAssembler assembler;
OrderRepositoryImpl(OrderMapper mapper, OrderAssembler assembler) {
this.mapper = mapper;
this.assembler = assembler;
}
@Override
public Optional<Order> findById(String orderId) {
try {
return mapper.findById(orderId).map(assembler::toDomain);
} catch (SQLException e) {
// 将 JDBC 异常封装在基础设施层,避免污染领域接口。
throw new IllegalStateException("failed to load order " + orderId, e);
}
}
@Override
public void save(Order order) {
try {
mapper.save(assembler.toPO(order));
} catch (SQLException e) {
throw new IllegalStateException("failed to save order " + order.id(), e);
}
}
}
public static void main(String[] args) throws SQLException {
createSchema();
OrderRepository repository = new OrderRepositoryImpl(
new OrderMapper(),
new OrderAssembler()
);
Order order = new Order(
"order-1001",
new BigDecimal("199.00"),
OrderStatus.PENDING_PAYMENT
);
repository.save(order);
Order loaded = repository.findById("order-1001").orElseThrow();
// 先重建聚合,再执行业务行为,最后保存新的聚合状态。
loaded.pay();
repository.save(loaded);
Order reloaded = repository.findById("order-1001").orElseThrow();
System.out.println("id=" + reloaded.id());
System.out.println("total=" + reloaded.totalAmount());
System.out.println("status=" + reloaded.status());
}
private static void createSchema() throws SQLException {
String ddl = """
CREATE TABLE orders (
id VARCHAR(64) PRIMARY KEY,
total_amount DECIMAL(18, 2) NOT NULL,
status VARCHAR(32) NOT NULL
)
""";
try (Connection connection = DriverManager.getConnection(URL);
Statement statement = connection.createStatement()) {
statement.execute(ddl);
}
}
}预期输出
id=order-1001
total=199.00
status=PAID输出说明订单先以待支付状态写入数据库,加载为领域对象后执行 pay(),再次保存并重建时仍保持 PAID。数据库记录只是领域状态的持久化表达,状态变更规则仍然属于 Order。
保持依赖方向和事务边界
OrderRepositoryImpl 可以捕获 SQLException 并转换成基础设施异常或项目统一的数据访问异常,但不要让 SQLException 出现在领域接口里,否则调用方会被迫理解 JDBC。
示例中的“先更新,未命中再插入”是为了清楚展示 save 语义。生产环境需要结合数据库能力、唯一约束和事务策略处理并发写入;如果一次用例需要同时保存订单和其他聚合,也应由应用层的事务边界统一协调,而不是让领域对象自己开启事务。
判断实现是否合格,可以看一条简单标准:删除 JDBC、H2、PO 和 Mapper 之后,领域层的 Order 与 OrderRepository 仍然能够独立编译和表达业务意图。做到这一点,持久化技术就被限制在基础设施层,可以在不改领域模型的前提下替换。