Blaze-Persistence：给 JPA 加一层本该有的查询能力

Blaze-Persistence 在 GitHub 上拿到了 855 Star。

它做的事很专一：给 JPA 提供一套更厚的 Criteria API，把用 JPA 时碰到的一堆限制补回来。CTE、递归查询、UNION、RETURNING、键集分页，这些原生 JPA 不支持的东西，它能写。

1、 它要解决的问题

用 JPA 写过复杂查询的人大概都清楚。NamedQuery 写死了 SQL， JPQL 表达能力有限，标准 Criteria API 啰嗦还容易写错，遇到分页深翻就性能崩盘。多投一投，少用一些 SELECT，本来数据库一行 SQL 解决的事，要么拆成多次查询在内存里拼，要么直接绕开 ORM 写原生 SQL。

Blaze-Persistence 把这层补上了。它不是替代 JPA 的 ORM，是架在 JPA 之上的一套查询构造器，底层还是走 Hibernate、EclipseLink、DataNucleus 这些 provider。开发者用它的 fluent API 写查询，它翻译成对应 provider 能跑的 SQL。

2、 核心能力

能做的事大致这么几类:

普通 JPA 写不出来的 SQL 特性，它给做成了 API。CTE 和递归 CTE 可以定义临时结果集，DML CTE 可以在 CTE 里做修改操作。RETURNING 子句让 INSERT/UPDATE/DELETE 后直接拿到改动后的数据，省一次回查。UNION、EXCEPT、INTERSECT 这些集合操作能拼出多结果合并的查询，以前得绕好几道弯。

VALUES 子句可以做报表查询，group_concat、日期截取、日期运算这些函数它内置了一堆，跨 provider 表现一致。键集分页解决了深翻页的性能问题，传统 OFFSET 翻得越深越慢，键集用上一页最后一行的键定位，翻多深都稳定。

3、 Entity View 模块

这个模块单独说一句。它的思路类似数据库的视图，但作用在 JPA 实体上。

实际项目里 DTO 是绕不开的东西。直接查实体出来一堆懒加载和 N+1，手写 DTO 又要维护投影逻辑。Entity View 让你写一个接口描述要哪些字段，框架自动生成 JOIN 和投影 SQL。

写法上像这样：

@EntityView(Cat.class)
public interface CatView {
    @IdMapping
    Integer getId();

    @Mapping("CONCAT(mother.name, 's kitty ', name)")
    String getCuteName();

    SimpleCatView getFather();
}

cuteName 是计算字段，JPQL 表达式直接给。father 关联自动 LEFT JOIN 出来。查询时把 view 应用到 CriteriaBuilder 上，拿到结果前只取了需要的那几列，不发多余的 SQL。

4、 怎么用

Maven 引入，给一个版本属性就够了，模块都按这个版本一起发布：

<properties>
    <blaze-persistence.version>1.6.18</blaze-persistence.version>
</properties>

入口是 CriteriaBuilderFactory，和 EntityManagerFactory 同生命周期：

CriteriaBuilderConfiguration config = Criteria.getDefault();
CriteriaBuilderFactory cbf = config.createCriteriaBuilderFactory(entityManagerFactory);

写一个查询，把关联一起 fetch 进来一行就能完事：

cbf.create(em, Cat.class).fetch("kittens.father").getResultList();

底层生成的 SQL 是带两个 LEFT JOIN FETCH 的语句，路径写错了会基于 metamodel 提前报错，不用等到运行时。

5、 兼容性

支持的版本跨度很宽。Hibernate 从 4.2 一路到 7.1，EclipseLink 2.6+，Spring 4.3+，Spring Data 1.11 到 3.5，Quarkus 1.4+。最低只要 JPA 2.0，能塞进 Java EE 6 或 Spring 4 的老项目。

Java 运行时方面，能跑在 Java 7 上，最新测到 Java 21。Spring Boot、DeltaSpike Data、JAX-RS、GraphQL、Jackson 这些都有现成集成模块，要接进去基本不用自己写胶水代码。

6、 适合哪些人

• 觉得 JPA Criteria 啰嗦难维护、又不想退回原生 SQL 的团队
• 查询里有 UNION、CTE、深分页，原生 JPA 写不出来只能换方案的人
• DTO 投影逻辑散得到处都是、想统一管理前端返回结构的项目
• 老项目里 Hibernate 4.x 还在跑、想升级查询能力但不能动 ORM 的开发者

如果想试水，作者提供了 Maven archetype，core、entity-view、spring-data、spring-boot、quarkus 各种集成模板都有，一条命令生成完整可跑的工程，自己改着试就行。

etype，core、entity-view、spring-data、spring-boot、quarkus 各种集成模板都有，一条命令生成完整可跑的工程，自己改着试就行。