Skip to content

数据访问:JdbcTemplate、Spring Data JPA 与 jOOQ ​

本篇要点:能在同一个项目里给四条数据访问路线划清边界,遇到慢查询时先判断是 N+1、全量 UPDATE 还是分页写法的问题,而不是先换框架。前置要求:完成《Web 层:REST 控制器、参数校验与统一异常处理》,能写 REST 接口和统一异常处理,知道 HTTP 请求会落到哪个 Controller 方法。

为什么需要它 ​

去年十一月,一个订单后台的列表页打开要 11 秒。EXPLAIN 显示单条 SQL 只扫了 200 行,索引也没问题。那 11 秒是 201 条 SQL 累出来的。

场景很普通:findByCustomerId 派生查询返回 Page<Order>,每页 200 条。应用容器在广州,数据库在上海,跨可用区 RTT 38 毫秒。打开 SQL 日志数一遍:一条分页查询、一条 count,然后整整齐齐 200 条 SELECT * FROM t_order_item WHERE order_id = ?。

201 次往返,平均每次 55 毫秒(含语句准备和结果映射),串行执行,加起来 11 秒。同一段代码在本地开发机上只要 300 毫秒——RTT 0.02 毫秒,差两个数量级。N+1 最难受的地方就在这里:开发环境几乎看不见,一上跨区部署就现形。

Spring Data JDBC 的文档对这个行为只有一句轻描淡写的话:集合属性会被额外查询,范围是 map、list、set 和实体数组。翻成人话:只要聚合里有 List<OrderItem>,它不猜你的 join 意图,一律补一条。

根子上的错不是框架,是把订单和订单明细硬塞进了一个聚合。它们在写的时候是一个一致性边界,在读的时候是两种跨度完全不同的数据。

先把立场摆在前面:这一章要给的是一条能落地的边界——写路径走聚合仓库,读路径走显式 SQL,谁都别越界。

核心概念 ​

概念一:四条路线,先分清各自在解决哪一层 ​

JdbcTemplate 是底座。它用连接、绑定参数、映射结果集,把 JDBC 那套 try-finally 收进 RowMapper。它的定位不是“低级方案”,而是所有上层框架最后都会落到的那一层,批量、存储过程、复杂 upsert 时你得回到它。

Spring Data JPA 的抽象层次最高:实体(entity)、持久化上下文(persistence context)、脏检查(dirty checking)、懒加载代理(lazy proxy)。这套东西让你写 order.getItems() 就能拿到明细,代价是 SQL 什么时候发、发几条,由框架决定。

Spring Data JDBC 换了一个模型:聚合(aggregate)是一致性边界,一次 save 只保证一个聚合的原子性。它没有 Session、没有一级缓存、没有脏检查、没有懒加载代理。

jOOQ 走的是另一条路:把表结构生成 Java 常量,让 SQL 变成类型安全的 API,limit/offset、窗口函数、CTE、ON CONFLICT 都能直接写。

四条路线没有全局最优,能分出优劣的只有“这次操作在干什么”,如图 4-1 所示。

图 4-1 写路径与读路径在同一个 Service 后分岔

两条分支的入口不是“谁更好”,而是“这次操作在做哪件事”。如果把这个判断交给自动配置,它会按“能跑就行”的标准给你拼一条 SQL,代价留给你在监控里发现。

概念二:聚合是 Spring Data JDBC 的全部 ​

聚合(aggregate)是一组必须一起改的数据,聚合根是唯一入口。订单和它的明细可以是一个聚合,订单和客户不是——客户是另一个聚合根,跨聚合只存 ID。

这个模型的好处是行为可预测。序列化一个对象不会偷偷触发十条 SQL,因为你根本没有代理;save 之后内存里的对象和库里的一行是什么关系,你一眼能说清。

代价也很直接:跨聚合查询没有任何抽象可用,必须显式写 SQL。官方文档里专门留了一章 MyBatis 集成,那就是在承认这条边界。

JPA 在这一层上正好相反。它有持久化上下文,同一个事务里查两次同一个 ID 只会发一条 SQL;改一个字段,flush 时只更新脏字段。但托管之外(detached)的实体走 merge,那是一整行 UPDATE,和下面要讲的 save 行为上很像。

反例:把一个 200 条的订单分页读出来做展示,却按聚合整体加载。这件事在任何框架下都慢,Spring Data JDBC 只是让它慢得更明显。

还有一层容易被跳过的配合:一次 save 的原子性由事务给,不由仓库给。事务从代理入口开始就握着同一条连接,直到提交才归还。把 HTTP 请求、远程调用、文件解析都圈进一个事务,连接池再大也会被长事务耗干。连接池容量和事务长度要一起算,这一点《事务管理:传播行为、隔离级别与失效场景》会展开。

概念三:分页只有三档,第四档要自己写 ​

派生查询(derived query)配 Pageable,返回 Page 会额外发一条 count;返回 Slice 只多取一行判断 hasNext。这是第一档和第二档。

派生查询只能作用于聚合根自己的列,不能 join,不能按子表字段过滤——这一点和 JPA 不同,JPA 的派生查询能顺着属性路径解析关联。

第三档是字符串 @Query,而它不支持 Pageable、Sort、Limit 参数。原因是框架得重写你的 SQL 才能塞进方言的分页语法,它选择不猜。

java
// Spring Data JDBC 4.1.x:字符串 @Query 不能带 Pageable,分页参数得自己绑
public interface OrderRepository extends CrudRepository<Order, Long> {

    Page<Order> findByCustomerId(Long customerId, Pageable pageable);   // 会额外发 count

    Slice<Order> findByStatus(OrderStatus status, Pageable pageable);   // 只多取 1 行

    @Query("SELECT * FROM t_order WHERE customer_id = :cid ORDER BY id DESC LIMIT :limit OFFSET :offset")
    List<Order> pageByCustomer(@Param("cid") Long cid,
                               @Param("limit") int limit,
                               @Param("offset") int offset);
}

运行结果:调用 findByCustomerId 时日志里有两条 SQL,主查询加一条 SELECT count(*);调用 findByStatus 只有一条,LIMIT 是 size + 1;调用 pageByCustomer 只有你写的那一条,没有总数。

一旦开始手写 LIMIT :limit OFFSET :offset,三件事同时失守:没有编译期校验、没有总数、下次加动态条件还得再写一条。三周之后你会得到一个既没有类型安全、也没有 MyBatis 灵活性的东西。

概念四:jOOQ 把 SQL 当 API ​

jOOQ 3.21 的用法是把查询写成链式调用,由代码生成器产出的 T_ORDER 常量保证列名和类型正确。换数据库方言时改配置,不改查询。

java
// jOOQ 3.21.x,T_ORDER 由代码生成器产出
public PageResult<OrderRow> search(OrderCriteria c, int page, int size) {
    Condition where = DSL.noCondition();
    if (c.customerId() != null) where = where.and(T_ORDER.CUSTOMER_ID.eq(c.customerId()));
    if (c.status() != null)     where = where.and(T_ORDER.STATUS.eq(c.status().name()));
    if (c.keyword() != null && !c.keyword().isBlank())
        where = where.and(T_ORDER.ORDER_NO.contains(c.keyword()));

    int total = dsl.fetchCount(dsl.selectFrom(T_ORDER).where(where));

    // 排序键必须唯一,否则翻页会重复或漏行
    List<OrderRow> rows = dsl.select(T_ORDER.ID, T_ORDER.ORDER_NO, T_ORDER.STATUS, T_ORDER.CREATED_AT)
            .from(T_ORDER).where(where)
            .orderBy(T_ORDER.CREATED_AT.desc(), T_ORDER.ID.desc())
            .limit(size).offset(page * size)
            .fetchInto(OrderRow.class);

    return new PageResult<>(rows, total, page, size);
}

预期输出:同一份 200 条的数据,日志里只有两条 SQL(count 一条、列表一条),耗时从 11 秒降到 190 毫秒左右,容器规格不变。

说得老实一点,省下来的 10.8 秒里只有一小部分是 jOOQ 的功劳。真正起作用的是不再返回 200 个聚合,只 select 四个列。这个改动用 JdbcTemplate 手写也能做到。

概念五:写读分治的那条线 ​

线是这么画的:写路径只走聚合仓库,读路径只走 jOOQ 查询对象,jOOQ 不承担写聚合的职责。

反过来不成立。一旦同一个聚合既能被 save 又能被 DSL 更新,缓存失效和领域事件就无处安放——你不知道该在哪一层挂监听,最后结果是两边都挂,事件重复投递。

维度Spring Data JDBC 4.1jOOQ 3.21MyBatis 3.5
建模驱动聚合根,无 Session 无脏检查表结构 + 代码生成SQL / XML 为主
复杂查询弱,得手写 @Query强,窗口函数、CTE 都有强,但无编译期校验
分页派生查询支持 Page/Slice;字符串查询不支持limit/offset + fetchCount插件改写,隐式行为多
批量写得借 JdbcTemplate原生 batchInsertforeach 拼接,注意包体大小
类型安全实体属性安全,SQL 不安全列名与类型都编译期校验无
授权Apache 2.0OSS 版覆盖开源数据库,Oracle/SQL Server 需商业版Apache 2.0

还有一条判断给得很硬:如果服务里一半以上的查询都带动态条件、聚合函数、窗口函数,不要选 Spring Data JDBC 再靠 @Query 硬撑。那不是用它,是拿它当 MyBatis,还顺手放弃了两边各自的好处。

动手实践 ​

步骤 1:先把往返次数数出来 ​

打开 SQL 日志,不要靠猜。本地跑一次,跨区跑一次,对比同一段代码的 SQL 条数。

yaml
logging:
  level:
    org.springframework.jdbc.core.JdbcTemplate: DEBUG
    org.springframework.jdbc.core.StatementCreatorUtils: TRACE
spring:
  datasource:
    url: jdbc:mysql://db:3306/shop?rewriteBatchedStatements=true&useSSL=false

预期输出:列表页一次请求,日志里 201 条 Executing prepared SQL statement,其中 200 条是 SELECT * FROM t_order_item WHERE order_id = ?。看到这个数字,就不用再怀疑索引了。

步骤 2:把跨聚合查询从 @Query 抽到独立的 QueryDao ​

这一步不改框架,只改边界。所有带 join、带聚合函数、带动态条件的查询从 Repository 里搬到一个 XxxQueryDao,方法返回扁平的行对象,不返回聚合。

步骤 3:给所有分页接口的排序键补主键兜底 ​

ORDER BY created_at DESC 单独用是不安全的:同一秒创建的订单顺序由数据库自由决定,翻页时会出现重复或漏行。改成 ORDER BY created_at DESC, id DESC,并且让这个组合有索引。这一步不花钱,但必须做。

步骤 4:引入 jOOQ 代码生成并接进 CI ​

schema 变了不重新生成,所谓类型安全就是个谎言,症状是编译通过、运行报 column not found。生成任务要挂在构建里,而不是靠谁记得手动跑一次。多数据源或分库场景下还要显式配 spring.jooq.sql-dialect,别依赖自动探测。

步骤 5:批量写不要用 saveAll ​

saveAll 不是批量插入,它逐条执行、逐条提交。十万行对账数据跑过 4 分 12 秒,慢得让人以为连错了库。

java
// MySQL 上必须确认 JDBC URL 带 rewriteBatchedStatements=true,否则驱动仍逐条发
public void writeWithJooq(List<OrderItemRecord> rows) { dsl.batchInsert(rows).execute(); }

public void writeWithJdbc(List<OrderItem> items) {
    namedJdbc.batchUpdate(
        "INSERT INTO t_order_item(order_id, sku_id, qty) VALUES (:orderId, :skuId, :qty)",
        SqlParameterSourceUtils.createBatch(items.stream()
            .map(i -> Map.of("orderId", i.orderId(), "skuId", i.skuId(), "qty", i.qty()))
            .toList()));
}

预期输出:MySQL 的 general_log 里出现一条多值 INSERT INTO t_order_item ... VALUES (...),(...),(...),而不是十万条单行 INSERT。PostgreSQL 反过来,单批别超过 500 到 1000 行,批次太大只是把事务拉长、锁等待放大。

常见误解 ​

误解一:saveAll 是批量插入。它只是把循环写进了框架,一次一行往返。真要批量,得用 JdbcTemplate.batchUpdate 或 jOOQ 的 batchInsert,并且在 MySQL 的 JDBC URL 上打开 rewriteBatchedStatements。

误解二:save 是增量更新。Spring Data JDBC 的 save 生成全量 UPDATE,因为它不生成动态 SQL。做 PATCH 接口时这一条能直接吃掉你的字段:前端只传了 status,聚合里没赋值的 remark 以 null 写回去,客户备注就没了。正确做法是在事务里先读出聚合、改字段、再 save,或者写一条 @Modifying 的定向 UPDATE。

误解三:分页加上 Pageable 就完事了。除了排序键必须唯一,fetchCount 也有坑:它会去掉 ORDER BY 再包一层 COUNT(*),如果原查询带 GROUP BY,拿到的是分组数而不是行数。这时得用子查询包一层,包完之后 where 条件要跟着重写一遍,任何一边漏掉条件,总数就开始飘。

误解四:聚合越大越省事。订单带明细看着自然,读路径却要为它付 200 次往返。写的时候是一致性边界,读的时候是两种跨度,把它们分开不丢一致性,只是承认了两件事不一样。

小结 ​

  • JdbcTemplate 是底座,批量、upsert、存储过程最后都要回到它;聚合决定 Spring Data JDBC 的能力边界,跨聚合查询没有抽象,必须显式写 SQL,这是设计而不是缺陷。
  • 分页只有三档:Page 发 count、Slice 多取一行、字符串 @Query 自己绑 LIMIT/OFFSET。第四档意味着你放弃了类型安全和总数。
  • saveAll 逐条执行,save 是全量 UPDATE。PATCH 和批量写这两个场景,换框架也躲不过去。
  • 写路径走聚合仓库,读路径走 jOOQ,jOOQ 不更新聚合。这条线守不住,缓存失效和领域事件就会重复投递。
  • 迁移顺序:抽 QueryDao → 排序键补主键 → jOOQ 生成进 CI → 最后才考虑把简单 CRUD 迁到 Spring Data JDBC,那一步可以永远不做。

相关主题 ​

数据访问里每一个 save、每一条 batchUpdate,都挂在一个事务上。《事务管理:传播行为、隔离级别与失效场景》讲事务管理:@Transactional 的代理边界为什么决定了它会不会生效、七种传播行为分别会把连接借给谁、异常在哪一步被吃掉,以及事务提交之后才该做的事(事务管理)。本篇那个“先读出聚合、改字段、再 save”的修法,成立的前提就是它在同一个事务里。