REST Query Language with Spring Data JPA and Querydsl – 使用Spring Data JPA和Querydsl的REST查询语言

最后修改: 2015年 1月 31日

1. Overview


In this tutorial, we’re looking at building a query language for a REST API using Spring Data JPA and Querydsl.

在本教程中,我们将研究如何使用Spring Data JPA和Querydsl,为REST API构建查询语言。

In the first two articles of this series, we built the same search/filtering functionality using JPA Criteria and Spring Data JPA Specifications.

本系列的前两篇文章中,我们使用JPA Criteria和Spring Data JPA Specifications构建了相同的搜索/过滤功能。

So – why a query language? Because – for any complex enough API – searching/filtering your resources by very simple fields is simply not enough. A query language is more flexible, and allows you to filter down to exactly the resources you need.

那么 – 为什么要使用查询语言?因为对于任何足够复杂的 API 来说,通过非常简单的字段搜索/过滤您的资源是远远不够的。查询语言更加灵活,并允许您精确地过滤到您所需要的资源。

2. Querydsl Configuration


First – let’s see how to configure our project to use Querydsl.


We need to add the following dependencies to pom.xml:



We also need to configure the APT – Annotation processing tool – plugin as follows:



This will generate the Q-types for our entities. 


3. The MyUser Entity


Next – let’s take a look at the “MyUser” entity which we are going to use in our Search API:


public class MyUser {
    @GeneratedValue(strategy = GenerationType.AUTO)
    private Long id;

    private String firstName;
    private String lastName;
    private String email;

    private int age;

4. Custom Predicate With PathBuilder


Now – let’s create a custom Predicate based on some arbitrary constraints.


We’re using PathBuilder here instead of the automatically generated Q-types because we need to create paths dynamically for more abstract usage:


public class MyUserPredicate {

    private SearchCriteria criteria;

    public BooleanExpression getPredicate() {
        PathBuilder<MyUser> entityPath = new PathBuilder<>(MyUser.class, "user");

        if (isNumeric(criteria.getValue().toString())) {
            NumberPath<Integer> path = entityPath.getNumber(criteria.getKey(), Integer.class);
            int value = Integer.parseInt(criteria.getValue().toString());
            switch (criteria.getOperation()) {
                case ":":
                    return path.eq(value);
                case ">":
                    return path.goe(value);
                case "<":
                    return path.loe(value);
        else {
            StringPath path = entityPath.getString(criteria.getKey());
            if (criteria.getOperation().equalsIgnoreCase(":")) {
                return path.containsIgnoreCase(criteria.getValue().toString());
        return null;

Note how the implementation of the predicate is generically dealing with multiple types of operations. This is because the query language is by definition an open language where you can potentially filter by any field, using any supported operation.


To represent that kind of open filtering criteria, we’re using a simple but quite flexible implementation – SearchCriteria:

为了表示这种开放的过滤标准,我们使用了一个简单但相当灵活的实现 – SearchCriteria

public class SearchCriteria {
    private String key;
    private String operation;
    private Object value;

The SearchCriteria holds the details we need to represent a constraint:


  • key: the field name – for example: firstName, age, … etc
  • operation: the operation – for example: Equality, less than, … etc
  • value: the field value – for example: john, 25, … etc

5. MyUserRepository


Now – let’s take a look at our MyUserRepository.


We need our MyUserRepository to extend QuerydslPredicateExecutor so that we can use Predicates later to filter search results:


public interface MyUserRepository extends JpaRepository<MyUser, Long>, 
  QuerydslPredicateExecutor<MyUser>, QuerydslBinderCustomizer<QMyUser> {
    default public void customize(
      QuerydslBindings bindings, QMyUser root) {
          .first((SingleValueBinding<StringPath, String>) StringExpression::containsIgnoreCase);

Note that we’re using here the generated Q-type for the MyUser entity, which will be named QMyUser.


6. Combine Predicates


Next– let’s take a look at combining Predicates to use multiple constraints in results filtering.


In the following example – we work with a builder – MyUserPredicatesBuilder – to combine Predicates:


public class MyUserPredicatesBuilder {
    private List<SearchCriteria> params;

    public MyUserPredicatesBuilder() {
        params = new ArrayList<>();

    public MyUserPredicatesBuilder with(
      String key, String operation, Object value) {
        params.add(new SearchCriteria(key, operation, value));
        return this;

    public BooleanExpression build() {
        if (params.size() == 0) {
            return null;

        List predicates = -> {
            MyUserPredicate predicate = new MyUserPredicate(param);
            return predicate.getPredicate();
        BooleanExpression result = Expressions.asBoolean(true).isTrue();
        for (BooleanExpression predicate : predicates) {
            result = result.and(predicate);
        return result;

7. Test the Search Queries


Next – let’s test our Search API.


We’ll start by initializing the database with a few users – to have these ready and available for testing:


@ContextConfiguration(classes = { PersistenceConfig.class })
public class JPAQuerydslIntegrationTest {

    private MyUserRepository repo;

    private MyUser userJohn;
    private MyUser userTom;

    public void init() {
        userJohn = new MyUser();

        userTom = new MyUser();

Next, let’s see how to find users with given last name:


public void givenLast_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder().with("lastName", ":", "Doe");

    Iterable<MyUser> results = repo.findAll(;
    assertThat(results, containsInAnyOrder(userJohn, userTom));

Now, let’s see how to find a user with given both first and last name:


public void givenFirstAndLastName_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder()
      .with("firstName", ":", "John").with("lastName", ":", "Doe");

    Iterable<MyUser> results = repo.findAll(;

    assertThat(results, contains(userJohn));
    assertThat(results, not(contains(userTom)));

Next, let’s see how to find user with given both last name and minimum age


public void givenLastAndAge_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder()
      .with("lastName", ":", "Doe").with("age", ">", "25");

    Iterable<MyUser> results = repo.findAll(;

    assertThat(results, contains(userTom));
    assertThat(results, not(contains(userJohn)));

Now, let’s see how to search for MyUser that doesn’t actually exist:


public void givenWrongFirstAndLast_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder()
      .with("firstName", ":", "Adam").with("lastName", ":", "Fox");

    Iterable<MyUser> results = repo.findAll(;
    assertThat(results, emptyIterable());

Finally – let’s see how to find a MyUser given only part of the first name – as in the following example:


public void givenPartialFirst_whenGettingListOfUsers_thenCorrect() {
    MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder().with("firstName", ":", "jo");

    Iterable<MyUser> results = repo.findAll(;

    assertThat(results, contains(userJohn));
    assertThat(results, not(contains(userTom)));

8. UserController


Finally, let’s put everything together and build the REST API.

最后,让我们把一切放在一起,建立REST API。

We’re defining a UserController that defines a simple method findAll() with a “search“ parameter to pass in the query string:


public class UserController {

    private MyUserRepository myUserRepository;

    @RequestMapping(method = RequestMethod.GET, value = "/myusers")
    public Iterable<MyUser> search(@RequestParam(value = "search") String search) {
        MyUserPredicatesBuilder builder = new MyUserPredicatesBuilder();

        if (search != null) {
            Pattern pattern = Pattern.compile("(\w+?)(:|<|>)(\w+?),");
            Matcher matcher = pattern.matcher(search + ",");
            while (matcher.find()) {
        BooleanExpression exp =;
        return myUserRepository.findAll(exp);

Here is a quick test URL example:



And the response:



9. Conclusion


This third article covered the first steps of building a query language for a REST API, making good use of the Querydsl library.

这第三篇文章涵盖了为REST API构建查询语言的第一步,很好地利用了Querydsl库。

The implementation is of course early on, but it can easily be evolved to support additional operations.


The full implementation of this article can be found in the GitHub project – this is a Maven-based project, so it should be easy to import and run as it is.

本文的完整实现可以在GitHub项目中找到 – 这是一个基于Maven的项目,所以应该很容易导入并按原样运行。

Next »

REST Query Language – Advanced Search Operations

« Previous

REST Query Language with Spring Data JPA Specifications