10.对象关系行为

0 阅读32分钟

对象关系行为

1.介绍

对象-关系行为模式,是指在业务事务运行期间,专门用于管理内存领域对象与底层关系型数据库之间数据拉取、状态追踪、内存去重与批量写回行为的一套架构套路

行为模式解决的就是"在业务操作过程中,对象的状态如何高效、安全、一致地在内存和磁盘之间流转"

2.为什么需要

  • 频繁的微小通信:每当业务代码修改了某个对象的属性,就立即向数据库发送一条SQL UPDATE;或者在循环中频繁调用数据库写方法。这会导致产生大量微小的网络轮询,使系统吞吐量急剧下降。同时,跨多个对象的写入如果顺序不当,极易触发数据库外键约束报错或死锁
  • 内存状态冲突:假设在一个请求中,通过两条不同的查询路径(例如先通过ID查询客户,再通过订单关联查询客户)两次加载了数据库中ID为129的同一条记录。如果系统在内存中创建了两个独立的Customer对象实例,当代码在A处更新了手机号、在B处更新了邮箱时,写回数据库时就会发生状态覆盖和冲突,导致数据丢失或损坏
  • 级联爆炸加载:在面向对象模型中,对象之间充斥着丰富的网状引用(例如一个订单Order关联一个客户Customer,客户又关联历史所有订单,每个订单又关联商品)如果读取一个起点对象就把整张关系网全部拉取出来,就会引发波动加载,将大半个数据库的数据一次性灌入内存,造成内存溢出与严重的响应卡顿

3.三大模式

  • 工作单元(Unit of Work)
  • 标识映射(Identity Map)
  • 延迟加载(Lazy Load)

4.工作流程

在实际的企业级框架中,这三大行为模式从来不是孤立工作的,它们紧密组合成了一套完整的持久化机制:

[业务代码调用接口 / 查询对象]
           │
           ▼
    [检查 Identity Map 缓存] ──(若命中)──> [直接返回内存中唯一的对象引用]
           │ (若未命中)
           ▼
    [从数据库执行 SQL SELECT]
           │
           ▼
    [装载数据实体 (对深层关联配置 Lazy Load 占位符)]
           │
           ▼
    [自动注册进 Identity Map & Unit of Work (标记为 Clean/或留存 Snapshot)]
           │
           ▼
    [业务代码直接修改内存对象的属性] ──> [Unit of Work 追踪状态变更 (标记为 Dirty)]
           │
           ▼
    [提交事务 commit() / flush()]
           │
           ▼
[Unit of Work 集中进行脏检查、SQL 拓扑排序、打包 Batch 批量发送数据库执行]

5.现代框架支持

在现代技术栈中,开发者几乎不需要手动实现这套行为机制:

  • Java (JPA / Hibernate):Session / EntityManager就是标准的UnitOfWork ;其一级缓就是Identity Map;基于CGLIB/ByteBuddy的@ManyToOne(fetch = FetchType.LAZY)就是Lazy Load(虚代理)
  • .NET (Entity Framework Core):DbContext充当Unit of Work ;其内部的ChangeTracker实现状态追踪与Identity Map;导航属性支持Lazy Loading

6.工作单元

介绍

工作单元是一个专门的对象,它维护在单个业务事务中被影响的所有对象列表,并统筹协调变更的原子化写出以及并发冲突的解决

工作单元充当了数据库映射的控制器。在没有工作单元的情况下,通常由领域对象或业务脚本直接决定何时读写数据库;而引入工作单元后,所有的持久化细节都交由工作单元在最后一刻集中集中裁决和调度

核心功能

  • 推迟执行与批量优化:工作单元将所有的SQL操作推迟到业务事务即将提交的最后一刻(commit()时)将几十次零散的数据库操作打包为批量批处理一次性发送给数据库
  • 自动化内存状态追踪:工作单元在内存中记录整个业务事务期间数据模型的所有变化。开发者只需纯粹地操作内存对象,工作单元会在提交时自动计算需要向数据库提交的变更集,无需手动调用更新方法
  • 自动梳理外键约束与SQL拓扑排序:工作单元内部包含变更集算法,在提交时通过拓扑排序自动规划正确的SQL命令顺序(如:先执行所有INSERT,再执行UPDATE,最后执行DELETE)
  • 死锁预防与结合标识映射:工作单元能保持固定的写表顺序以大幅降低死锁概率,且通常作为标识映射(第一级缓存)的宿主容器,确保同一数据库记录在会话内存中永远只有一个对象实例

对象的四大生命周期状态

在工作单元的上下文管理中,领域对象随着业务流转跨越4种基本状态:

  • 干净(Clean):从数据库装载后未发生任何属性修改的对象
  • 新建(New):在事务中刚创建、尚未存在于数据库中的对象
  • 变脏(Dirty / Modified):从数据库加载后,某些属性已被修改的对象
  • 已被删除(Deleted / Removed):在事务中被标记为需要从数据库中移除的对象

三大对象注册策略

工作单元需要感知对象的变更,主要有3种主要的注册机制,如下图所示:

7.标识映射

介绍

标识映射通过在内存映射中记录每个已经从数据库中读取出的对象,确保同一个业务会话或业务事务内部,每个数据库记录只被加载并实例化一次

为什么需要

  • 保证数据一致性:如果在一个业务请求里,由于不同查询路径先后两次读取了数据库中的同一行数据(如客户ID=1)若没有标识映射,内存中就会生成两个独立的Customer对象实例。如果业务代码在A处修改了电话,在B处修改了邮箱,在最终写回数据库时,后提交的对象就会直接覆盖前一个对象的修改,导致严重的数据丢失与状态混乱
  • 优化查询性能:标识映射缓存了当前事务已读出的对象,相同的ID查询可以直接命中内存,免去了昂贵的数据库网络往返与SQL解析执行开销

工作流程

在标准的数据映射器实现中,标识映射会在两处进行拦截与检测:

  • 在执行SQL前(Finder检查):如果按主键ID进行find(id),先查标识映射;若命中则直接返回,彻底省下一次数据库交互
  • 在解析结果集时(Load检查):对于复杂条件查询(例如WHERE lastname LIKE 'F%')无法在执行前预测会返回哪些主键,必须查库。当遍历ResultSet时,每读取一行数据都要再次检查标识映射。若该对象已被加载过,则直接取内存现有实例放入列表,杜绝重复实例化

设计核心

决策维度核心选择与考量
键的选择绝大多数情况下选用数据库表的主键(如不可变的代理主键)既易于比对又保证唯一性
显式 VS 通用显式映射(如getPerson(Long id))在Java等强类型语言中具备编译期类型安全,代码自解释性好;通用映射(如get("Person", id))复用性好,但容易丧失类型安全
**数量与继承处理 **最常见是一类一映射(或一表一映射)但若存在多态继承树(如Car继承Vehicle)采用整棵继承树共享一个映射能避免多态查找时在多个Map之间来回穿梭
存放位置与作用域必须绑定在业务会话或业务事务范围内,绝不可跨用户会话共享。工作单元是存放标识映射的最佳宿主,因为工作单元负责追踪所有进出数据库的对象

案例

介绍

以下案例还原福勒在PofEAA中的经典范式:实现显式PersonIdentityMap,并与AbstractMapper(数据映射器层超类型)无缝集成

代码

显式标识映射单例/注册表:管理Person对象的内存唯一索引,同时为原始长整型参数提供便捷装箱重载

import java.util.HashMap;
import java.util.Map;

/**
 * 人员实体的显式标识映射 (Explicit Identity Map)
 * 作用域:绑定于当前会话/线程上下文
 */
public class PersonIdentityMap {
    private static final PersonIdentityMap soleInstance = new PersonIdentityMap();
    private final Map<Long, Person> people = new HashMap<>();

    public static PersonIdentityMap getInstance() {
        return soleInstance;
    }

    public static void addPerson(Person person) {
        soleInstance.people.put(person.getId(), person);
    }

    public static Person getPerson(Long key) {
        return soleInstance.people.get(key);
    }

    // 便捷重载:支持直接使用 long 字面量检索
    public static Person getPerson(long key) {
        return getPerson(Long.valueOf(key));
    }
}

不适用的场景

8.延迟加载

介绍

延迟加载是一个本身并不包含所需要的所有数据、但是知道如何获取这些数据的对象

在将关系数据库数据映射为内存对象网时,不一次性拉取整个对象关联树,而是保留一个占位符;只有当应用程序代码真正通过导航或方法调用访问该属性时,才触发数据库查询把真实数据读取进来

问题

  • 防止整库级联拖入:在面向对象领域模型中,对象彼此高度互联(例如:读取一个Customer会顺带关联其所有的Order,每个Order又关联所有的OrderItem和Product,Product又反向关联Supplier)如果不设边界,仅仅读取一个根对象就会将大半个数据库的数据一口气全部读入内存
  • 平衡内存开销与响应速度:绝大多数业务场景只关心根对象或其首层属性,根本用不到深层关联数据。推迟加载不必要的数据能显著降低内存占用和数据库读取带宽
  • 打破双向循环引用死锁:当实体之间存在双向关联(如Order -> Customer -> Orders)且采用丰富构造函数时,容易在初始化阶段发生无限递归调用导致调用栈溢出;延迟加载可以在关联处切断加载链,打破循环

方案总览

  • 延迟初始化:这是最简单直接的方法。在对象的属性域上,每次访问(即使在类内部)都必须通过get方法。在get方法内部,先检查该属性是否为null;如果为null,才去数据库查询并赋值,然后返回。它的缺点是会让领域对象与数据库访问代码产生强耦合
  • 虚代理:这是一个完美的替身。它看起来和你要访问的真实对象类一模一样,但它内部其实是空的。只有当你调用它的某个业务方法时,它才会在暗中查询数据库,实例化真实对象并委托执行。注意:虚代理会引发标识问题。由于代理对象不是真实对象,如果你在系统中为一个真实对象创建了多个虚代理,普通的相等性测试(如Java中的==)就会报错,引发难以追踪的bug
  • 值保持器:为了避免虚代理的标识问题,你可以用一个泛型的值保持器对象来包装真实对象。客户端必须显式地调用getValue方法来获取底层数据。它的缺点是领域类必须知道值保持器的存在,丧失了强类型的隐蔽性
  • 重影:重影就是真实对象本身,但它处于未被唤醒的部分状态。当你从数据库加载它时,它只有一个ID属性是有值的。一旦你访问它的任何其他属性,它就会瞬间加载自己的全部状态。重影非常适合直接放入标识映射中,不仅维护了对象唯一性,还能有效打破循环引用的死循环

对比

案例

介绍

我们以供应商(Supplier)与产品列表(Product)的一对多关联为例,展示三种最常见的实现方式

虚代理

这是Java企业级开发中最优雅的解法。领域实体只认识标准的List接口,底层的SupplierMapper在装载时塞入一个特制的VirtualList

import java.util.*;

// 1. 定义加载器函数式接口
public interface VirtualListLoader {
    List load();
}

// 2. 虚代理列表:实现 List 接口,拦截所有方法调用
public class VirtualList implements List {
    private List source; // 真实的目标列表
    private final VirtualListLoader loader;

    public VirtualList(VirtualListLoader loader) {
        this.loader = loader;
    }

    // 内部自封装检查:首次调用任何方法时触发查库
    private List getSource() {
        if (source == null) {
            source = loader.load();
        }
        return source;
    }

    // 所有常规 List 接口方法全部委托给 getSource()
    @Override public int size() { return getSource().size(); }
    @Override public boolean isEmpty() { return getSource().isEmpty(); }
    @Override public Iterator iterator() { return getSource().iterator(); }
    @Override public Object get(int index) { return getSource().get(index); }
    // ... 其他接口方法按同理实现
}

// 3. 领域对象:Supplier 保持纯粹,完全不知道延迟加载的存在!
public class SupplierVL {
    private Long id;
    private String name;
    private List products; // 声明为标准 List,无任何特殊框架类型!

    public SupplierVL(Long id, String name) {
        this.id = id;
        this.name = name;
    }

    public List getProducts() { return products; }
    public void setProducts(List products) { this.products = products; }
}

// 4. 数据映射器:在读取 Supplier 时组装虚列表代理
public class SupplierMapper {
    public SupplierVL find(Long id) {
        // 假设查库获得 name = "Acme Corp"
        SupplierVL supplier = new SupplierVL(id, "Acme Corp");

        // 装配虚代理:把查询 SQL 逻辑封装在匿名回调中,暂不执行查库
        supplier.setProducts(new VirtualList(() -> {
            System.out.println(">>> [SQL 执行] SELECT * FROM products WHERE supplier_id = " + id);
            return ProductMapper.findForSupplier(id);
        }));

        return supplier; // 此时 products 表尚未被查询!
    }
}

值保持器

当不想为每个关联类编写代理接口时,可以使用通用的ValueHolder容器

// 通用值加载接口
public interface ValueLoader<T> {
    T load();
}

// 泛型值保持器
public class ValueHolder<T> {
    private T value;
    private final ValueLoader<T> loader;

    public ValueHolder(ValueLoader<T> loader) {
        this.loader = loader;
    }

    public T getValue() {
        if (value == null) {
            value = loader.load(); // 首次调用触发查库
        }
        return value;
    }
}

// 领域实体:属性类型被显式声明为 ValueHolder
public class SupplierVH {
    private Long id;
    private ValueHolder<List<Product>> products;

    public SupplierVH(Long id, ValueHolder<List<Product>> products) {
        this.id = id;
        this.products = products;
    }

    // 对外通过 getter 隐藏 ValueHolder 的存在细节
    public List<Product> getProducts() {
        return products.getValue();
    }
}
重影

重影对象的状态模型通常由层超类型统一维护

// 领域层超类型:维护 Ghost 状态机
public abstract class DomainObject {
    public enum LoadStatus { GHOST, LOADING, LOADED }

    private Long id;
    private LoadStatus status = LoadStatus.GHOST; // 初始均为重影状态

    public DomainObject(Long id) { this.id = id; }
    public boolean isGhost() { return status == LoadStatus.GHOST; }

    // 核心拦截钩子:在任何属性被访问前触发
    protected void checkAndLoad() {
        if (isGhost()) {
            status = LoadStatus.LOADING;
            DataSource.load(this); // 通过统一的数据源入口触发当前实体的全量字段填充
            status = LoadStatus.LOADED;
        }
    }
}

// 具体实体:所有 Getter 都先调用 checkAndLoad()
public class Employee extends DomainObject {
    private String name;
    private String department;

    public Employee(Long id) { super(id); } // 初始只装载 ID

    public String getName() {
        checkAndLoad(); // 若为重影,一举填满 name, department 等所有列
        return name;
    }
    public void setName(String name) { this.name = name; }
}

9.N+1问题

介绍

虽然延迟加载避免了一次性加载海量无用数据,但当它遭遇集合循环遍历时,就会暴露出致命缺陷

[执行 1 次主查询] ──> 获取 N 条订单记录 (SELECT * FROM orders WHERE ...)
        │
        ├─> 循环遍历第 1 条订单 ──> 触发延迟加载 ──> SELECT * FROM customers WHERE id = 101;
        ├─> 循环遍历第 2 条订单 ──> 触发延迟加载 ──> SELECT * FROM customers WHERE id = 102;
        ├─> ...
        └─> 循环遍历第 N 条订单 ──> 触发延迟加载 ──> SELECT * FROM customers WHERE id = 100+N;
                                                  ──────────────────────────────────────────
                                                  总计向数据库发送了 (1 + N) 次独立查询!

问题

  • 网络往返延迟:执行100次单条查询意味着100次网络数据包往返、连接借还与协议握手,总体耗时远高于单次批量查询
  • 数据库引擎压力:数据库需要重复执行100次SQL词法语法解析、权限检查、查询计划生成与上下文切换
  • 连接池耗尽:高并发场景下,单个请求霸占数据库连接池发起几十上百次微小查询,极易迅速耗尽连接池,导致整个服务雪崩

案例

我们通过以订单与客户关联为例,假设我们需要展示最近的100笔订单及其所属客户的姓名,如下代码会产生N+

1问题

// 实体映射:Order 对 Customer 采用延迟加载 (FetchType.LAZY)
@Entity
public class Order {
    @Id
    private Long id;
    
    @ManyToOne(fetch = FetchType.LAZY) // 延迟加载占位符
    @JoinColumn(name = "customer_id")
    private Customer customer;
    
    // ...
}

// 业务调用代码
@Transactional(readOnly = true)
public void printOrderReport() {
    // 【第 1 次查询】:拉取 100 条订单
    List<Order> orders = orderRepository.findRecentOrders(); 

    for (Order order : orders) {
        // 🚨 灾难触发点:访问 customer.getName() 时,由于是代理占位符,
        // ORM 在循环内部向数据库逐条发送 SELECT 查询对应客户!
        System.out.println("订单ID: " + order.getId() + ", 客户: " + order.getCustomer().getName());
    }
}
-- 第 1 次查询
SELECT id, customer_id, order_date FROM orders LIMIT 100;

-- 随后的 100 次查询(循环触发)
SELECT id, name FROM customers WHERE id = 1;
SELECT id, name FROM customers WHERE id = 2;
...
SELECT id, name FROM customers WHERE id = 100;

解决方案

  • 预先加载
  • 计数器缓存
  • 严格加载

预先加载

介绍

将原本分散在循环体中的N次随用随查,通过显式前置意图声明,合并为1到2次高内聚的批量数据库往返

实现思路

预先加载并非简单的把数据一次全拉出来,在底层SQL执行层面,主流框架与架构实现主要分为两大物理流派:

                           ┌──────────────────────────────────────────────┐
                           │            预先加载 (Eager Loading)           │
                           └──────────────────────┬───────────────────────┘
                                                  │
                 ┌────────────────────────────────┴────────────────────────────────┐
                 ▼                                                                 ▼
      [ 流派 A:批量分步抓取 (IN 子句) ]                               [ 流派 B:单次显式联表 (JOIN) ]
     (如 Rails preload / JPA @BatchSize)                            (如 JPA JOIN FETCH / Rails eager_load)
  1. SELECT * FROM parents WHERE ...                             1. SELECT p.*, c.* FROM parents p
  2. SELECT * FROM children WHERE parent_id IN (...)                LEFT OUTER JOIN children c ON c.p_id = p.id
对比

现代ORM(如Ruby on Rails ActiveRecord、Java JPA/Hibernate等)针对预先加载提供了非常细致的方法分类:

模式策略底层 SQL行为能否用关联表条件过滤最佳适用场景
preload / BatchFetch始终使用独立的IN (...) 批量查询否大数据集、纯集合关联展示、无需用子表字段过滤主表
eager_load / JOIN FETCH始终使用LEFT OUTER JOIN单条查出是需要按关联表的列排序/过滤主记录,或数据量较小
includes(智能适配)默认采用IN (...);一旦发现查询中包含对子表的过滤条件,自动切换为LEFT JOIN是(自动降级为JOIN)日常业务开发推荐的首选方案
问题

计数器缓存

介绍

前端仅仅需要显示一个数字(例如评论数post.comments.count)完全不需要具体的关联数据详情

如果此时依然使用预先加载,会导致数据库查出成千上万条明细数据并在内存中实例化大量不必要的对象,引发严重的对象水化与内存膨胀

针对这种聚合统计型的N+1问题,计数器缓存是一种极致优雅且高效的解决方案

计数器缓存的本质是经典的反范式化设计与读写权衡

工作流程
  • 冗余字段存储:在父表/所属表(如posts或articles)中直接增加一个整型列(如comments_count)
  • 写入时自动维护:当子表(如comments)发生插入、物理删除、级联删除或转移所属父级时,由框架的生命周期钩子、事件监听器或数据库触发器自动对父表字段执行原子的+1或-1操作
  • 读取时零额外成本:展示列表时,查询语句只读取父表本身;访问数量时直接读取该数字,实现O(1)复杂度读取,子表完全不需要发起任何SQL查询,网络开销和对象装载成本归零
【写操作:新增/删除一条评论】
  INSERT INTO comments (...) VALUES (...)
       │ (框架生命周期钩子 / 数据库触发器自动同步)
       ▼
  UPDATE posts SET comments_count = comments_count + 1 WHERE id = ?;

【读操作:渲染包含 100 篇文章的列表页】
  SELECT id, title, comments_count FROM posts LIMIT 100;
       │
       ▼ (遍历文章读取 post.comments_count 时,已是内存就绪字段,无后续 SQL!)
  总查询数:只有 1 次!
优缺点
  • 优点:彻底消除了为了计算数量而产生的N+1次count查询,并且完美避免了把成千上万个根本用不上的关联对象拉进内存(对象水合)而导致的内存溢出瓶颈
  • 缺点:
    • 不好应对带条件的统计:它很难处理带条件的统计。如果你只想要统计状态为已审核的评论数,原生的计数器缓存就无能为力了,你可能得被迫手动维护多个不同维度的计数字段
    • 不好应对并发写入:对于超高并发写入的场景(例如千万级粉丝大V发帖,瞬间涌入数十万条点赞或评论)所有并发写入请求都会对父表的同一行记录争抢排他写锁,导致数据库行锁等待甚至死锁

严格加载

介绍

严格加载是一种主动防御性的架构策略。它规定:如果在加载某个模型实体时没有显式声明预先加载其关联对象,则该实体在后续运行中被严禁触发任何隐式的延迟加载

一旦代码试图在内存中访问未被预加载的关联属性,ORM不再默默替你向数据库发送单条SQL,而是立即抛出致命异常(或记录严重警告日志)

工作流程
【常规模式(默认 Lazy Load)】
  访问 post.author ──(未预先加载)──> ORM 默默执行:SELECT * FROM authors WHERE id = ? ──> 引发 N+1!

【严格加载模式(Strict Loading)】
  访问 post.author ──(未预先加载)──> 🚨 立即抛出 ActiveRecord::StrictLoadingViolationError / 异常!
                                     强迫开发者在查询入口显式声明 includes/preload!
核心思想

严格加载把N+1问题的发现时机从"线上生产环境的APM告警/慢SQL审计",直接前移到了"本地开发环境"与"CI/CD单元测试阶段"

  • 剥夺隐式特权:延迟加载虽然便利,但这种隐蔽的数据库网络调用是破坏系统吞吐量的大敌。严格加载剥夺了这种随意性
  • 暴露未预见的数据访问:促使前端模板和API序列化器与数据查询层形成契约,杜绝在View视图层或模型方法中漫无目的地穿透数据库
优缺点
  • 优点:它能在开发和测试阶段直接拦截意外的延迟加载并报错,彻底将N+1性能隐患扼杀在摇篮里,避免拖垮生产环境的性能。此外它的配置非常灵活,支持在全局、单一模型或单次查询级别开启
  • 缺点:容错率极低。只要代码中漏写了预先加载声明,系统就会直接抛出错误异常导致业务中断。这迫使开发者必须时刻保持警惕,显式声明所需的所有关联数据,增加了一定的编码心智负担

10.案例

介绍

还是以收入确认为例子来讲解工作单元和标识映射,由于这俩经常一起配合使用,所以这里把案例单独弄出来

包结构

Controller


/**
 * ThreadLocal 版工作单元 + 标识映射案例的 REST 薄封装。
 */
@RestController
@RequestMapping("/api/tls")
public class ThreadLocalUnitOfWorkController {

    private final ContractApplicationService contractApplicationService;

    public ThreadLocalUnitOfWorkController(ContractApplicationService contractApplicationService) {
        this.contractApplicationService = contractApplicationService;
    }

    @PostMapping("/contracts")
    public ResponseEntity<ContractResponse> signContract(@RequestBody SignContractRequest request) {
        ContractDetail detail = contractApplicationService.signContract(new SignContractCommand(
                request.customerName(),
                request.productType(),
                request.revenue(),
                request.signedOn()));
        return ResponseEntity.status(HttpStatus.CREATED).body(ContractResponse.from(detail));
    }

    @PutMapping("/contracts/{id}/revenue")
    public ContractResponse adjustRevenue(@PathVariable("id") long id,
                                          @RequestBody AdjustRevenueRequest request) {
        ContractDetail detail = contractApplicationService.adjustRevenue(
                id, new AdjustRevenueCommand(request.revenue()));
        return ContractResponse.from(detail);
    }

    @GetMapping("/contracts/{id}")
    public ContractResponse getContract(@PathVariable("id") long id) {
        return ContractResponse.from(contractApplicationService.getContract(id));
    }

    @GetMapping("/contracts/{id}/recognized-revenue")
    public RevenueResponse recognizedRevenue(@PathVariable("id") long id,
                                             @RequestParam("asOf") LocalDate asOf) {
        return new RevenueResponse(id, asOf,
                contractApplicationService.recognizedRevenue(id, asOf));
    }

    @GetMapping("/recognized-revenue")
    public TotalRevenueResponse totalRecognizedRevenue(@RequestParam("asOf") LocalDate asOf) {
        return new TotalRevenueResponse(asOf,
                contractApplicationService.totalRecognizedRevenue(asOf));
    }
}

Filter


/**
 * 请求级会话边界:每个 /api/tls 请求打开一个 PersistenceSession,
 * 绑定到当前线程;请求结束(无论成功失败)解绑并关闭。
 */
@Component
public class PersistenceSessionFilter extends OncePerRequestFilter {

    private final PersistenceSessionFactory sessionFactory;

    public PersistenceSessionFilter(PersistenceSessionFactory sessionFactory) {
        this.sessionFactory = sessionFactory;
    }

    @Override
    protected boolean shouldNotFilter(HttpServletRequest request) {
        return !request.getRequestURI().startsWith("/api/tls");
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain) throws ServletException, IOException {
        PersistenceSession session = sessionFactory.openSession();
        CurrentSession.bind(session);
        try {
            filterChain.doFilter(request, response);
        } finally {
            CurrentSession.unbind();
            session.close();
        }
    }
}

工作单元


/**
 * 工作单元:登记一次会话中新增、修改、删除的合同,flush 时统一写入。
 *
 * <p>登记是显式的;工作单元不控制事务,flush 只写库、不提交事务。</p>
 */
public final class UnitOfWork {

    private final TlsContractMapper contractMapper;
    private final IdentityMap identityMap;
    private final List<Contract> newContracts = new ArrayList<>();
    private final Map<Long, Contract> dirtyContracts = new LinkedHashMap<>();
    private final Map<Long, Contract> deletedContracts = new LinkedHashMap<>();

    UnitOfWork(TlsContractMapper contractMapper, IdentityMap identityMap) {
        this.contractMapper = contractMapper;
        this.identityMap = identityMap;
    }

    public void registerNew(Contract contract) {
        requireNotNull(contract);
        if (contract.getId() != null) {
            throw new IllegalArgumentException("已有 id 的合同应登记为 dirty");
        }
        if (!newContracts.contains(contract)) {
            newContracts.add(contract);
        }
    }

    public void registerDirty(Contract contract) {
        requireNotNull(contract);
        if (contract.getId() == null) {
            throw new IllegalArgumentException("未持久化的合同应登记为 new");
        }
        if (deletedContracts.containsKey(contract.getId())) {
            throw new IllegalStateException("已登记删除的合同不能再登记为 dirty");
        }
        if (newContracts.contains(contract)) {
            return;
        }
        dirtyContracts.put(contract.getId(), contract);
    }

    public void registerDeleted(Contract contract) {
        requireNotNull(contract);
        if (contract.getId() == null) {
            throw new IllegalArgumentException("未持久化的合同不能登记删除");
        }
        newContracts.remove(contract);
        dirtyContracts.remove(contract.getId());
        deletedContracts.put(contract.getId(), contract);
    }

    /**
     * 按 insert → update → delete 的顺序统一写库,完成后清空登记表。
     *
     * <p>flush 不提交事务;事务由应用服务上的 {@code @Transactional} 控制。</p>
     */
    public void commit() {
        for (Contract contract : newContracts) {
            contractMapper.insert(contract);
            identityMap.put(Contract.class, contract.getId(), contract);
        }
        for (Contract contract : dirtyContracts.values()) {
            contractMapper.update(contract);
        }
        for (Contract contract : deletedContracts.values()) {
            contractMapper.deleteById(contract.getId());
            identityMap.evict(Contract.class, contract.getId());
        }
        clear();
    }

    public boolean isEmpty() {
        return newContracts.isEmpty() && dirtyContracts.isEmpty() && deletedContracts.isEmpty();
    }

    public void clear() {
        newContracts.clear();
        dirtyContracts.clear();
        deletedContracts.clear();
    }

    private void requireNotNull(Contract contract) {
        if (contract == null) {
            throw new IllegalArgumentException("登记对象不能为空");
        }
    }
}


/**
 * 当前线程工作单元的单例门面。
 *
 * <p>应用服务注入本类即可登记变更和 flush,不需要接触 PersistenceSession;
 * 具体状态存放在当前线程绑定的会话里。</p>
 */
@Component("tlsCurrentUnitOfWork")
public class CurrentUnitOfWork {

    public void registerNew(Contract contract) {
        CurrentSession.require().registerNew(contract);
    }

    public void registerDirty(Contract contract) {
        CurrentSession.require().registerDirty(contract);
    }

    public void registerDeleted(Contract contract) {
        CurrentSession.require().registerDeleted(contract);
    }

    public void flush() {
        CurrentSession.require().flush();
    }
}

标识映射


/**
 * 标识映射:在当前线程的 PersistenceSession 内,保证同一张表的同一行
 * 只对应一个领域对象实例。
 */
public final class IdentityMap {

    private final Map<Key, Object> objects = new HashMap<>();

    @SuppressWarnings("unchecked")
    public <T> Optional<T> get(Class<T> type, long id) {
        return Optional.ofNullable((T) objects.get(new Key(type, id)));
    }

    public <T> void put(Class<T> type, long id, T object) {
        if (object == null) {
            throw new IllegalArgumentException("缓存对象不能为空");
        }
        objects.put(new Key(type, id), object);
    }

    public int size() {
        return objects.size();
    }

    /** 从会话缓存中移除已被删除的对象。 */
    public void evict(Class<?> type, long id) {
        objects.remove(new Key(type, id));
    }

    public void clear() {
        objects.clear();
    }

    private record Key(Class<?> type, long id) {
    }
}

Session


/**
 * 一次持久化会话:持有标识映射与工作单元,并把自己挂到当前事务上。
 *
 * <p>会话由请求级 Filter 打开并绑定到 ThreadLocal;本类不负责绑定。</p>
 */
public final class PersistenceSession implements AutoCloseable {

    private final IdentityMap identityMap = new IdentityMap();
    private final UnitOfWork unitOfWork;
    private boolean synchronizationRegistered;

    PersistenceSession(TlsContractMapper contractMapper) {
        this.unitOfWork = new UnitOfWork(contractMapper, identityMap);
    }

    public IdentityMap identityMap() {
        return identityMap;
    }

    public void registerNew(Contract contract) {
        unitOfWork.registerNew(contract);
    }

    public void registerDirty(Contract contract) {
        unitOfWork.registerDirty(contract);
    }

    public void registerDeleted(Contract contract) {
        unitOfWork.registerDeleted(contract);
    }

    /** 把当前登记写入数据库,但不提交事务(类似 EntityManager.flush)。 */
    public void flush() {
        unitOfWork.commit();
    }

    public boolean hasPendingChanges() {
        return !unitOfWork.isEmpty();
    }

    /**
     * 在活动事务中注册同步回调:提交前兜底 flush,即使调用方忘记显式 flush。
     *
     * <p>由 {@link CurrentSession#require()} 触发;同一事务只注册一次。</p>
     */
    void registerWithTransactionSynchronization() {
        if (synchronizationRegistered) {
            return;
        }
        if (!TransactionSynchronizationManager.isActualTransactionActive()
                || !TransactionSynchronizationManager.isSynchronizationActive()) {
            return;
        }
        TransactionSynchronizationManager.registerSynchronization(new TransactionSynchronization() {
            @Override
            public void beforeCommit(boolean readOnly) {
                if (!readOnly) {
                    flush();
                }
            }

            @Override
            public void afterCompletion(int status) {
                synchronizationRegistered = false;
            }
        });
        synchronizationRegistered = true;
    }

    @Override
    public void close() {
        unitOfWork.clear();
        identityMap.clear();
    }
}


/**
 * 会话工厂:单例,每次调用返回一个新的 {@link PersistenceSession}。
 */
@Component("tlsPersistenceSessionFactory")
public class PersistenceSessionFactory {

    private final TlsContractMapper contractMapper;

    public PersistenceSessionFactory(TlsContractMapper contractMapper) {
        this.contractMapper = contractMapper;
    }

    public PersistenceSession openSession() {
        return new PersistenceSession(contractMapper);
    }
}


/**
 * 当前线程的持久化会话。
 *
 * <p>请求级 Filter 在请求开始时 bind、结束时 unbind;仓储和工作单元门面
 * 通过 {@link #require()} 隐式取得会话。未绑定说明调用发生在 Web 边界之外
 * 或线程上下文已经丢失,直接抛异常暴露问题。</p>
 */
public final class CurrentSession {

    private static final ThreadLocal<PersistenceSession> CURRENT = new ThreadLocal<>();

    private CurrentSession() {
    }

    public static void bind(PersistenceSession session) {
        if (session == null) {
            throw new IllegalArgumentException("会话不能为空");
        }
        if (CURRENT.get() != null) {
            throw new IllegalStateException("当前线程已经绑定 PersistenceSession");
        }
        CURRENT.set(session);
    }

    public static PersistenceSession require() {
        PersistenceSession session = CURRENT.get();
        if (session == null) {
            throw new IllegalStateException("当前线程没有绑定 PersistenceSession");
        }
        session.registerWithTransactionSynchronization();
        return session;
    }

    public static Optional<PersistenceSession> current() {
        return Optional.ofNullable(CURRENT.get());
    }

    public static void unbind() {
        CURRENT.remove();
    }
}

Repository


/**
 * 合同读取门面:Spring 单例,但每次调用都从当前线程的会话取标识映射。
 *
 * <p>这是与 10 案例最大的差别:仓储不再由 Session 创建,也没有 Session 字段。</p>
 */
@Repository("tlsContractRepository")
public class ContractRepository {

    private final TlsContractMapper contractMapper;
    private final ProductResolver productResolver;

    public ContractRepository(TlsContractMapper contractMapper,
                              ProductRepository productResolver) {
        this.contractMapper = contractMapper;
        this.productResolver = productResolver;
    }

    public Optional<Contract> findById(long contractId) {
        PersistenceSession session = CurrentSession.require();
        IdentityMap identityMap = session.identityMap();

        Optional<Contract> cached = identityMap.get(Contract.class, contractId);
        if (cached.isPresent()) {
            return cached;
        }
        Optional<Contract> loaded = contractMapper.findById(contractId, productResolver);
        loaded.ifPresent(contract -> identityMap.put(Contract.class, contractId, contract));
        return loaded;
    }

    public List<Contract> findAll() {
        IdentityMap identityMap = CurrentSession.require().identityMap();
        return contractMapper.findAll(productResolver).stream()
                .map(contract -> identityMap.get(Contract.class, contract.getId())
                        .orElseGet(() -> {
                            identityMap.put(Contract.class, contract.getId(), contract);
                            return contract;
                        }))
                .toList();
    }
}


/**
 * 产品读取门面:Spring 单例,内部使用当前线程会话的标识映射。
 *
 * <p>实现 {@link ProductResolver},供合同映射器在加载聚合时解析产品,
 * 从而保证同一会话内同一产品只有一个实例。</p>
 */
@Repository("tlsProductRepository")
public class ProductRepository implements ProductResolver {

    private final TlsProductMapper productMapper;

    public ProductRepository(TlsProductMapper productMapper) {
        this.productMapper = productMapper;
    }

    @Override
    public Product findById(long productId) {
        IdentityMap identityMap = CurrentSession.require().identityMap();

        Optional<Product> cached = identityMap.get(Product.class, productId);
        if (cached.isPresent()) {
            return cached.get();
        }
        Product product = productMapper.findById(productId)
                .orElseThrow(() -> new IllegalStateException("产品不存在:" + productId));
        identityMap.put(Product.class, productId, product);
        return product;
    }

    public Product findByType(ProductType productType) {
        IdentityMap identityMap = CurrentSession.require().identityMap();

        Product loaded = productMapper.findByType(productType)
                .orElseThrow(() -> new IllegalStateException("产品未初始化:" + productType
                        + ",请先执行 db/tls/data.sql"));

        Optional<Product> cached = identityMap.get(Product.class, loaded.getId());
        if (cached.isPresent()) {
            return cached.get();
        }
        identityMap.put(Product.class, loaded.getId(), loaded);
        return loaded;
    }
}

数据映射器


/**
 * 合同映射器加载聚合时用来解析产品的回调。
 *
 * <p>由单例的 {@code ProductRepository} 实现,因此产品加载也会经过
 * 当前线程会话的标识映射。</p>
 */
@FunctionalInterface
public interface ProductResolver {

    Product findById(long productId);
}


/**
 * 合同聚合的数据映射器:{@link Contract} ↔ tls_contract + tls_revenue_recognition。
 *
 * <p>工作单元在 flush 时调用它的 insert/update/deleteById;
 * 它本身不控制事务,也不决定何时写库。</p>
 */
@Repository("tlsContractMapper")
public class TlsContractMapper {

    private final TlsContractRowMapper contractRowMapper;
    private final TlsRevenueRecognitionRowMapper recognitionRowMapper;

    public TlsContractMapper(TlsContractRowMapper contractRowMapper,
                             TlsRevenueRecognitionRowMapper recognitionRowMapper) {
        this.contractRowMapper = contractRowMapper;
        this.recognitionRowMapper = recognitionRowMapper;
    }

    public Optional<Contract> findById(long contractId, ProductResolver productResolver) {
        TlsContractRow row = contractRowMapper.selectOneById(contractId);
        if (row == null) {
            return Optional.empty();
        }
        return Optional.of(toDomain(row, productResolver));
    }

    /** 加载全部合同;每个合同都会单独解析产品和确认记录(N+1)。 */
    public List<Contract> findAll(ProductResolver productResolver) {
        return contractRowMapper.selectAll().stream()
                .map(row -> toDomain(row, productResolver))
                .toList();
    }

    public void insert(Contract contract) {
        if (contract.getId() != null) {
            throw new IllegalArgumentException("已持久化的合同不能重复 insert");
        }
        TlsContractRow row = toRow(contract);
        contractRowMapper.insert(row);
        contract.assignId(row.getId());
        insertRecognitions(contract);
    }

    /** 更新合同行,并用当前计划替换旧的确认记录。 */
    public void update(Contract contract) {
        if (contract.getId() == null) {
            throw new IllegalArgumentException("未持久化的合同不能 update");
        }
        contractRowMapper.update(toRow(contract));
        recognitionRowMapper.deleteByContractId(contract.getId());
        insertRecognitions(contract);
    }

    /** 先删确认记录,再删合同(外键顺序)。 */
    public void deleteById(long contractId) {
        recognitionRowMapper.deleteByContractId(contractId);
        contractRowMapper.deleteById(contractId);
    }

    private Contract toDomain(TlsContractRow row, ProductResolver productResolver) {
        Product product = productResolver.findById(row.getProductId());

        Contract contract = new Contract(
                row.getId(),
                row.getCustomerName(),
                row.getRevenue(),
                row.getSignedOn(),
                product);

        for (TlsRevenueRecognitionRow recognition : recognitionRowMapper.selectByContractId(row.getId())) {
            contract.addRevenueRecognition(
                    new RevenueRecognition(recognition.getAmount(), recognition.getRecognizedOn()));
        }
        return contract;
    }

    private TlsContractRow toRow(Contract contract) {
        TlsContractRow row = new TlsContractRow();
        row.setId(contract.getId());
        row.setCustomerName(contract.getCustomerName());
        row.setProductId(contract.getProduct().getId());
        row.setRevenue(contract.getRevenue());
        row.setSignedOn(contract.getSignedOn());
        return row;
    }

    private void insertRecognitions(Contract contract) {
        for (RevenueRecognition recognition : contract.getRevenueRecognitions()) {
            TlsRevenueRecognitionRow row = new TlsRevenueRecognitionRow();
            row.setContractId(contract.getId());
            row.setAmount(recognition.amount());
            row.setRecognizedOn(recognition.recognizedOn());
            recognitionRowMapper.insert(row);
        }
    }
}

/**
 * 产品的数据映射器:tls_product 行 ↔ 领域产品。
 */
@Repository("tlsProductMapper")
public class TlsProductMapper {

    private final TlsProductRowMapper rowMapper;

    public TlsProductMapper(TlsProductRowMapper rowMapper) {
        this.rowMapper = rowMapper;
    }

    public Optional<Product> findById(long id) {
        return Optional.ofNullable(rowMapper.selectOneById(id)).map(this::toDomain);
    }

    public Optional<Product> findByType(ProductType productType) {
        return Optional.ofNullable(rowMapper.selectByType(productType.name())).map(this::toDomain);
    }

    public List<Product> findAll() {
        return rowMapper.selectAll().stream()
                .map(this::toDomain)
                .toList();
    }

    private Product toDomain(TlsProductRow row) {
        return ProductFactory.create(row.getId(), row.getName(), parseType(row.getType()));
    }

    private ProductType parseType(String value) {
        try {
            return ProductType.valueOf(value);
        } catch (IllegalArgumentException ex) {
            throw new IllegalStateException("未知产品类型:" + value);
        }
    }
}

领域模型

参考业务逻辑那一章节的领域模型

应用服务


/**
 * 应用服务:<strong>完全不感知 PersistenceSession</strong>。
 *
 * <p>会话由请求级 Filter 绑定到 ThreadLocal,仓储与工作单元门面内部自行取用。
 * 写用例在返回前 flush 一次以取得自增 id;事务同步会在提交前兜底 flush。</p>
 */
@Service("tlsContractApplicationService")
public class ContractApplicationService {

    private final ContractRepository contractRepository;
    private final ProductRepository productRepository;
    private final CurrentUnitOfWork currentUnitOfWork;

    public ContractApplicationService(ContractRepository contractRepository,
                                      ProductRepository productRepository,
                                      CurrentUnitOfWork currentUnitOfWork) {
        this.contractRepository = contractRepository;
        this.productRepository = productRepository;
        this.currentUnitOfWork = currentUnitOfWork;
    }

    @Transactional
    public ContractDetail signContract(SignContractCommand command) {
        validate(command);

        Product product = productRepository.findByType(command.productType());
        Contract contract = new Contract(
                null,
                command.customerName(),
                command.revenue(),
                command.signedOn(),
                product);
        contract.calculateRecognitions();
        currentUnitOfWork.registerNew(contract);
        currentUnitOfWork.flush();
        return toDetail(contract);
    }

    @Transactional
    public ContractDetail adjustRevenue(long contractId, AdjustRevenueCommand command) {
        if (command == null) {
            throw new IllegalArgumentException("调整命令不能为空");
        }

        Contract contract = requireContract(contractId);
        contract.adjustRevenue(command.revenue());
        currentUnitOfWork.registerDirty(contract);
        currentUnitOfWork.flush();
        return toDetail(contract);
    }

    @Transactional(readOnly = true)
    public ContractDetail getContract(long contractId) {
        return toDetail(requireContract(contractId));
    }

    @Transactional(readOnly = true)
    public BigDecimal recognizedRevenue(long contractId, LocalDate asOf) {
        requireAsOf(asOf);
        return requireContract(contractId).recognizedRevenue(asOf);
    }

    @Transactional(readOnly = true)
    public BigDecimal totalRecognizedRevenue(LocalDate asOf) {
        requireAsOf(asOf);
        BigDecimal total = contractRepository.findAll().stream()
                .map(contract -> contract.recognizedRevenue(asOf))
                .reduce(BigDecimal.ZERO, BigDecimal::add);
        return total.setScale(2, RoundingMode.HALF_UP);
    }

    private Contract requireContract(long contractId) {
        return contractRepository.findById(contractId)
                .orElseThrow(() -> new NoSuchElementException("合同不存在:" + contractId));
    }

    private ContractDetail toDetail(Contract contract) {
        List<RecognitionDetail> recognitions = contract.getRevenueRecognitions().stream()
                .map(recognition -> new RecognitionDetail(recognition.amount(), recognition.recognizedOn()))
                .toList();
        return new ContractDetail(
                contract.getId(),
                contract.getCustomerName(),
                contract.getProduct().getType(),
                contract.getRevenue(),
                contract.getSignedOn(),
                recognitions);
    }

    private void validate(SignContractCommand command) {
        if (command == null) {
            throw new IllegalArgumentException("签约命令不能为空");
        }
        if (command.productType() == null) {
            throw new IllegalArgumentException("产品类型不能为空");
        }
    }

    private void requireAsOf(LocalDate asOf) {
        if (asOf == null) {
            throw new IllegalArgumentException("查询日期不能为空");
        }
    }
}