在开始讲解之前,请先思考几个问题:
- JpaSpecificationExecutor 如何创建?
- 它的使用方法有哪些?
- toPredicate 方法如何实现?
带着这些问题,我们开始探索。先看一个例子感受一下 JpaSpecificationExecutor 具体的用法。
JpaSpecificationExecutor 使用案例
我们假设一个后台管理页面根据 name 模糊查询、sex 精准查询、age 范围查询、时间区间查询、address 的 in 查询这样一个场景,来查询 user 信息,我们看看这个例子应该怎么写。
第一步:创建 User 和 UserAddress 两个实体。 代码如下:
复制代码
package com.example.jpa.example1;
import com.fasterxml.jackson.annotation.JsonIgnore;
import lombok.*;
import javax.persistence.*;
import java.io.Serializable;
import java.time.Instant;
import java.util.Date;
import java.util.List;
/**
* 用户基本信息表
**/
@Entity
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ToString(exclude = "addresses")
public class User implements Serializable {
@Id
@GeneratedValue(strategy= GenerationType.AUTO)
private Long id;
private String name;
private String email;
@Enumerated(EnumType.STRING)
private SexEnum sex;
private Integer age;
private Instant createDate;
private Date updateDate;
@OneToMany(mappedBy = "user")
@JsonIgnore
private List<UserAddress> addresses;
}
enum SexEnum {
BOY,GIRL
}
package com.example.jpa.example1;
import lombok.*;
import javax.persistence.*;
/**
* 用户地址表
*/
@Entity
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
@ToString(exclude = "user")
public class UserAddress {
@Id
@GeneratedValue(strategy= GenerationType.AUTO)
private Long id;
private String address;
@ManyToOne(cascade = CascadeType.ALL)
private User user;
}
第二步:创建 UserRepository 继承 JpaSpecificationExecutor 接口。
复制代码
package com.example.jpa.example1;
import org.springframework.data.jpa.repository.JpaRepository;
import org.springframework.data.jpa.repository.JpaSpecificationExecutor;
public interface UserRepository extends JpaRepository<User,Long>, JpaSpecificationExecutor<User> {
}
第三步:创建一个测试用例进行测试。
复制代码
@DataJpaTest
@TestInstance(TestInstance.Lifecycle.PER_CLASS)
public class UserJpeTest {
@Autowired
private UserRepository userRepository;
@Autowired
private UserAddressRepository userAddressRepository;
private Date now = new Date();
/**
* 提前创建一些数据
*/
@BeforeAll
@Rollback(false)
@Transactional
void init() {
User user = User.builder()
.name("jack")
.email("123456@126.com")
.sex(SexEnum.BOY)
.age(20)
.createDate(Instant.now())
.updateDate(now)
.build();
userAddressRepository.saveAll(Lists.newArrayList(UserAddress.builder().user(user).address("shanghai").build(),
UserAddress.builder().user(user).address("beijing").build()));
}
@Test
public void testSPE() {
//模拟请求参数
User userQuery = User.builder()
.name("jack")
.email("123456@126.com")
.sex(SexEnum.BOY)
.age(20)
.addresses(Lists.newArrayList(UserAddress.builder().address("shanghai").build()))
.build();
//假设的时间范围参数
Instant beginCreateDate = Instant.now().plus(-2, ChronoUnit.HOURS);
Instant endCreateDate = Instant.now().plus(1, ChronoUnit.HOURS);
//利用Specification进行查询
Page<User> users = userRepository.findAll(new Specification<User>() {
@Override
public Predicate toPredicate(Root<User> root, CriteriaQuery<?> query, CriteriaBuilder cb) {
List<Predicate> ps = new ArrayList<Predicate>();
if (StringUtils.isNotBlank(userQuery.getName())) {
//我们模仿一下like查询,根据name模糊查询
ps.add(cb.like(root.get("name"),"%" +userQuery.getName()+"%"));
}
if (userQuery.getSex()!=null){
//equal查询条件,这里需要注意,直接传递的是枚举
ps.add(cb.equal(root.get("sex"),userQuery.getSex()));
}
if (userQuery.getAge()!=null){
//greaterThan大于等于查询条件
ps.add(cb.greaterThan(root.get("age"),userQuery.getAge()));
}
if (beginCreateDate!=null&&endCreateDate!=null){
//根据时间区间去查询创建
ps.add(cb.between(root.get("createDate"),beginCreateDate,endCreateDate));
}
if (!ObjectUtils.isEmpty(userQuery.getAddresses())) {
//联表查询,利用root的join方法,根据关联关系表里面的字段进行查询。
ps.add(cb.in(root.join("addresses").get("address")).value(userQuery.getAddresses().stream().map(a->a.getAddress()).collect(Collectors.toList())));
}
return query.where(ps.toArray(new Predicate[ps.size()])).getRestriction();
}
}, PageRequest.of(0, 2));
System.out.println(users);
}
}
我们看一下执行结果。
复制代码
Hibernate: select user0_.id as id1_1_, user0_.age as age2_1_, user0_.create_date as create_d3_1_, user0_.email as email4_1_, user0_.name as name5_1_, user0_.sex as sex6_1_, user0_.update_date as update_d7_1_ from user user0_ inner join user_address addresses1_ on user0_.id=addresses1_.user_id where (user0_.name like ?) and user0_.sex=? and user0_.age>20 and (user0_.create_date between ? and ?) and (addresses1_.address in (?)) limit ?
此 SQL 的参数如下:
此 SQL 就是查询 User inner Join user_address 之后组合成的查询 SQL,基本符合我们的预期,即不同的查询条件。我们通过这个例子大概知道了 JpaSpecificationExecutor 的用法,那么它具体是什么呢?
JpaSpecificationExecutor 语法详解
我们依然通过看 JpaSpecificationExecutor 的源码,来了解一下它的几个使用方法,如下所示:
复制代码
public interface JpaSpecificationExecutor<T> {
//根据 Specification 条件查询单个对象,要注意的是,如果条件能查出来多个会报错
T findOne(@Nullable Specification<T> spec);
//根据 Specification 条件,查询 List 结果
List<T> findAll(@Nullable Specification<T> spec);
//根据 Specification 条件,分页查询
Page<T> findAll(@Nullable Specification<T> spec, Pageable pageable);
//根据 Specification 条件,带排序的查询结果
List<T> findAll(@Nullable Specification<T> spec, Sort sort);
//根据 Specification 条件,查询数量
long count(@Nullable Specification<T> spec);
}
其返回结果和 Pageable、Sort,我们在前面课时都有介绍过,这里我们重点关注一下 Specification。看一下 Specification 接口的代码。
通过看其源码就会发现里面提供的方法很简单。其中,下面一段代码表示组合的 and 关系的查询条件。
复制代码
default Specification<T> and(@Nullable Specification<T> other) {
return composed(this, other, (builder, left, rhs) -> builder.and(left, rhs));
}
下面是静态方法,创建 where 后面的 Predicate 集合。
复制代码
static <T> Specification<T> where(@Nullable Specification<T> spec)
下面是默认方法,创建 or 条件的查询参数。
复制代码
default Specification<T> or(@Nullable Specification<T> other)
这是静态方法,创建 Not 的查询条件。
复制代码
static <T> Specification<T> not(@Nullable Specification<T> spec)
上面这几个方法比较简单,我就不一一细说了,我们主要看一下需要实现的方法:toPredicate。
复制代码
Predicate toPredicate(Root<T> root, CriteriaQuery<?> query, CriteriaBuilder criteriaBuilder);
toPredicate 这个方法是我们用到的时候需要自己去实现的,接下来我们详细介绍一下。
首先我们在刚才的 Demo 里面设置一个断点,看到如下界面。
这里可以分别看到 Root 的实现类是 RootImpl,CriteriaQuery 的实现类是 CriteriaQueryImpl,CriteriaBuilder 的实现类是 CriteriaBuilderImpl。
复制代码
javax.persistence.criteria.Root
javax.persistence.criteria.CriteriaQuery
javax.persistence.criteria.CriteriaBuilder
其中,上面三个接口是 Java Persistence API 定义的接口。
复制代码
org.hibernate.query.criteria.internal.path.RootImpl
rg.hibernate.query.criteria.internal.CriteriaQueryImpl
org.hibernate.query.criteria.internal.CriteriaBuilderImpl
而这个三个实现类都是由 Hibernate 进行实现的,也就是说 JpaSpecificationExecutor 封装了原本需要我们直接操作 Hibernate 中 Criteria 的 API 方法。
下面分别解释上述三个参数。
Root`` root
代表了可以查询和操作的实体对象的根,如果将实体对象比喻成表名,那 root 里面就是这张表里面的字段,而这些字段只是 JPQL 的实体字段而已。我们可以通过里面的 Path get(String attributeName),来获得我们想要操作的字段。
复制代码
类似于我们上面的:root.get("createDate")等操作
CriteriaQuery<?> query
代表一个 specific 的顶层查询对象,它包含着查询的各个部分,比如 select 、from、where、group by、order by 等。CriteriaQuery 对象只对实体类型或嵌入式类型的 Criteria 查询起作用。简单理解为,它提供了查询 ROOT 的方法。常用的方法有如下几种:
复制代码
正如我们上面where的用法:query.where(.....)一样
这个语法比较简单,我们在其方法后面加上相应的参数即可。下面看一个 group by 的例子。
如上图所示,我们加入 groupyBy 某个字段,SQL 也会有相应的变化。那么我们再来看第三个参数。
CriteriaBuilder cb
CriteriaBuilder 是用来构建 CritiaQuery 的构建器对象,其实就相当于条件或者条件组合,并以 Predicate 的形式返回。它基本上提供了所有常用的方法,如下所示:
我们直接通过此类的 Structure 视图就可以看到都有哪些方法。其中,and、any 等用来做查询条件的组合;类似 between、equal、exist、ge、gt、isEmpty、isTrue、in 等用来做查询条件的查询,类似下图的一些方法。
而其中 Expression 很简单,都是通过 root.get(…) 某些字段即可返回,正如下面的用法。
复制代码
Predicate p1=cb.like(root.get(“name”).as(String.class), “%”+uqm.getName()+“%”);
Predicate p2=cb.equal(root.get("uuid").as(Integer.class), uqm.getUuid());
Predicate p3=cb.gt(root.get("age").as(Integer.class), uqm.getAge());
我们利用 like、equal、gt 可以生产 Predicate,而 Predicate 可以组合查询。比如我们预定它们之间是 and 或 or 的关系:Predicate p = cb.and(p3,cb.or(p1,p2));
我们让 p1 和 p2 是 or 的关系,并且得到的 Predicate 和 p3 又构成了 and 的关系。你可以发现它的用法还是比较简单的,正如我们开篇所说的 Junit 中 test 里面一样的写法。
关于 JpaSpecificationExecutor 的语法我们就介绍完了,其实它里面的功能相当强大,只是我们发现 Spring Data JPA 介绍得并不详细,只是一笔带过,可能他们认为写框架的人才能用到,所以介绍得不多。
如果你想了解更多语法的话,可以参考 Hibernate 的文档:https://docs.jboss.org/hibernate/orm/5.2/userguide/html_single/Hibernate_User_Guide.html#criteria。我们再来看看 JpaSpecificationExecutor 的实现原理。
JpaSpecificationExecutor 原理分析
我们先看一下 JpaSpecificationExecutor 的类图。
从图中我们可以看得出来:
- JpaSpecificationExecutor 和 JpaRepository 是平级接口,而它们对应的实现类都是 SimpleJpaRepository;
- Specification 被 ExampleSpecification 和 JpaSpecificationExector 使用,用来创建查询;
- Predicate 是 JPA 协议里面提供的查询条件的根基;
- SimpleJpaRepository 利用 EntityManager 和 criteria 来实现由 JpaSpecificationExector 组合的 query。
那么我们再直观地看一下 JpaSpecificationExecutor 接口里面的方法 findAll 对应的 SimpleJpaRepository 里面的实现方法 findAl,我们通过工具可以很容易地看到相应的实现方法,如下所示:
你要知道,得到 TypeQuery 就可以直接操作JPA协议里面相应的方法了,那么我们看下 getQuery(spec,pageable)的实现过程。
之后一步一步 debug 就可以了。
到了上图所示这里,就可以看到:
- Specification`` spec 是我们测试用例写的 specification 的匿名实现类;
- 由于是方法传递,所以到第 693 行断点的时候,才会执行我们在测试用里面写的 Specification;
- 我们可以看到这个方法最后是调用的 EntityManager,而 EntitytManger 是 JPA 操作实体的核心原理,我在下一课时讲自定义 Repsitory 的时候再详细介绍;
- 从上面的方法实现过程中我们可以看得出来,所谓的JpaSpecificationExecutor原理,用一句话概况,就是利用Java Persistence API定义的接口和Hibernate的实现,做了一个简单的封装,方便我们操作JPA协议中 criteria 的相关方法。
到这里,原理和使用方法,我们基本介绍完了。你可能会有疑问:这个感觉有点重要,但是一般用不到吧?那么接下来我们看看 JpaSpecificationExecutor 的实战应用场景是什么样的。
JpaSpecificationExecutor 实战应用场景
其实JpaSpecificationExecutor 的目的不是让我们做日常的业务查询,而是给我们提供了一种自定义 Query for rest 的架构思路,如果做日常的增删改查,肯定不如我们前面介绍的 Defining Query Methods 和 @Query 方便。
那么来看下,实战过程中如何利用 JpaSpecificationExecutor 写一个框架。
MySpecification 自定义
我们可以自定义一个Specification 的实现类,它可以实现任何实体的动态查询和各种条件的组合。
复制代码
package com.example.jpa.example1.spe;
import org.springframework.data.jpa.domain.Specification;
import javax.persistence.criteria.*;
public class MySpecification<Entity> implements Specification<Entity> {
private SearchCriteria criteria;
public MySpecification (SearchCriteria criteria) {
this.criteria = criteria;
}
/**
* 实现实体根据不同的字段、不同的Operator组合成不同的Predicate条件
*
* @param root must not be {@literal null}.
* @param query must not be {@literal null}.
* @param builder must not be {@literal null}.
* @return a {@link Predicate}, may be {@literal null}.
*/
@Override
public Predicate toPredicate(Root<Entity> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
if (criteria.getOperation().compareTo(Operator.GT)==0) {
return builder.greaterThanOrEqualTo(
root.<String> get(criteria.getKey()), criteria.getValue().toString());
}
else if (criteria.getOperation().compareTo(Operator.LT)==0) {
return builder.lessThanOrEqualTo(
root.<String> get(criteria.getKey()), criteria.getValue().toString());
}
else if (criteria.getOperation().compareTo(Operator.LK)==0) {
if (root.get(criteria.getKey()).getJavaType() == String.class) {
return builder.like(
root.<String>get(criteria.getKey()), "%" + criteria.getValue() + "%");
} else {
return builder.equal(root.get(criteria.getKey()), criteria.getValue());
}
}
return null;
}
}
我们通过 `` 泛型,解决不同实体的动态查询(当然了,我只是举个例子,这个方法可以进行无限扩展)。我们通过 SearchCriteria 可以知道不同的字段是什么、值是什么、如何操作的,看一下代码:
复制代码
package com.example.jpa.example1.spe;
import lombok.*;
/**
* @author jack,实现不同的查询条件,不同的操作,针对Value;
*/
@Data
@Builder
@AllArgsConstructor
@NoArgsConstructor
public class SearchCriteria {
private String key;
private Operator operation;
private Object value;
}
其中的 Operator 也是我们自定义的。
复制代码
package com.example.jpa.example1.spe;
public enum Operator {
/**
* 等于
*/
EQ("="),
/**
* 等于
*/
LK(":"),
/**
* 不等于
*/
NE("!="),
/**
* 大于
*/
GT(">"),
/**
* 小于
*/
LT("<"),
/**
* 大于等于
*/
GE(">=");
Operator(String operator) {
this.operator = operator;
}
private String operator;
}
在 Operator 枚举里面定义了逻辑操作符(大于、小于、不等于、等于、大于等于……也可以自己扩展),并在 MySpecification 里面进行实现。那么我们来看看它是怎么用的,写一个测试用例试一下。
复制代码
/**
* 测试自定义的Specification语法
*/
@Test
public void givenLast_whenGettingListOfUsers_thenCorrect() {
MySpecification<User> name =
new MySpecification<User>(new SearchCriteria("name", Operator.LK, "jack"));
MySpecification<User> age =
new MySpecification<User>(new SearchCriteria("age", Operator.GT, 2));
List<User> results = userRepository.findAll(Specification.where(name).and(age));
System.out.println(results.get(0).getName());
}
你就会发现,我们在调用findAll 组合 Predicate 的时候就会非常简单,省去了各种条件的判断和组合,而省去的这些逻辑可以全部在我们的框架代码 MySpecification 里面实现。
那么如果把这个扩展到 API 接口层面会是什么样的结果呢?我们来看下。
利用 Specification 创建 search 为查询条件的 Rest API 接口
先创建一个 Controller,用来接收 search 这样的查询条件:类似 userssearch=lastName:doe,age>25 的参数。
复制代码
package com.example.jpa.example1.web;
import com.example.jpa.example1.User;
import com.example.jpa.example1.UserRepository;
import com.example.jpa.example1.spe.SpecificationsBuilder;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.data.jpa.domain.Specification;
import org.springframework.web.bind.annotation.*;
import java.util.List;
@RestController
public class UserController {
@Autowired
private UserRepository repo;
@RequestMapping(method = RequestMethod.GET, value = "/users")
@ResponseBody
public List<User> search(@RequestParam(value = "search") String search) {
Specification<User> spec = new SpecificationsBuilder<User>().buildSpecification(search);
return repo.findAll(spec);
}
}
Controller 里面非常简单,利用 SpecificationsBuilder 生成我们需要的 Specification 即可。那么我们看看 SpecificationsBuilder 里面是怎么写的。
复制代码
package com.example.jpa.example1.spe;
import com.example.jpa.example1.User;
import org.springframework.data.jpa.domain.Specification;
import java.util.ArrayList;
import java.util.List;
import java.util.regex.Matcher;
import java.util.regex.Pattern;
import java.util.stream.Collectors;
/**
* 处理请求参数
* @param <Entity>
*/
public class SpecificationsBuilder<Entity> {
private final List<SearchCriteria> params;
//初始化params,保证每次实例都是一个新的ArrayList
public SpecificationsBuilder() {
params = new ArrayList<SearchCriteria>();
}
//利用正则表达式取我们search参数里面的值,解析成SearchCriteria对象
public Specification<Entity> buildSpecification(String search) {
Pattern pattern = Pattern.compile("(\\w+?)(:|<|>)(\\w+?),");
Matcher matcher = pattern.matcher(search + ",");
while (matcher.find()) {
this.with(matcher.group(1), Operator.fromOperator(matcher.group(2)), matcher.group(3));
}
return this.build();
}
//根据参数返回我们刚才创建的SearchCriteria
private SpecificationsBuilder with(String key, Operator operation, Object value) {
params.add(new SearchCriteria(key, operation, value));
return this;
}
//根据我们刚才创建的MySpecification返回所需要的Specification
private Specification<Entity> build() {
if (params.size() == 0) {
return null;
}
List<Specification> specs = params.stream()
.map(MySpecification<User>::new)
.collect(Collectors.toList());
Specification result = specs.get(0);
for (int i = 1; i < params.size(); i++) {
result = Specification.where(result)
.and(specs.get(i));
}
return result;
}
}
通过上面的代码,我们可以看到通过自定义的 SpecificationsBuilder,来处理请求参数 search 里面的值,然后转化成我们上面写的 SearchCriteria 对象,再调用 MySpecification 生成我们需要的 Specification,从而利用 JpaSpecificationExecutor 实现查询效果。