REST 查询语言在 Spring 和 JPA Criteria 中的实现

最后修改:2024年1月29日

by Eugen Paraschiv

1. 概述

在本系列文章的第一篇中，我们将探索如何为 REST API 构建一个简单的查询语言。后端我们使用 Spring，数据访问层则采用 JPA 2 的 Criteria API 来实现查询逻辑。

为什么要引入查询语言？
因为对于稍微复杂一点的 API 来说，仅仅通过简单的字段进行资源过滤是远远不够的。一个设计良好的查询语言可以提供更高的灵活性，让你更精准地筛选出需要的资源。

2. User 实体类

我们以一个简单的 User 类作为示例实体类，用于后续的查询操作：

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

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

    private int age;
}

3. 使用 JPA Criteria 构建动态查询

现在进入核心部分：如何在持久层构建灵活的查询逻辑。

构建查询抽象层的关键在于平衡灵活性和复杂度。我们希望提供足够的查询能力，同时不让代码变得难以维护。

核心逻辑是：传入一组查询条件，返回匹配的结果集。

来看一个示例实现：

@Repository
public class UserDAO implements IUserDAO {

    @PersistenceContext
    private EntityManager entityManager;

    @Override
    public List<User> searchUser(List<SearchCriteria> params) {
        CriteriaBuilder builder = entityManager.getCriteriaBuilder();
        CriteriaQuery<User> query = builder.createQuery(User.class);
        Root<User> root = query.from(User.class);

        Predicate predicate = builder.conjunction();

        UserSearchQueryCriteriaConsumer searchConsumer = 
          new UserSearchQueryCriteriaConsumer(predicate, builder, root);
        params.forEach(searchConsumer);
        predicate = searchConsumer.getPredicate();
        query.where(predicate);

        return entityManager.createQuery(query).getResultList();
    }

    @Override
    public void save(User entity) {
        entityManager.persist(entity);
    }
}

接着看 UserSearchQueryCriteriaConsumer 类的实现：

public class UserSearchQueryCriteriaConsumer implements Consumer<SearchCriteria> {

    private Predicate predicate;
    private CriteriaBuilder builder;
    private Root<User> root;

    public UserSearchQueryCriteriaConsumer(Predicate predicate, CriteriaBuilder builder, Root<User> root) {
        this.predicate = predicate;
        this.builder = builder;
        this.root = root;
    }

    @Override
    public void accept(SearchCriteria param) {
        if (param.getOperation().equalsIgnoreCase(">")) {
            predicate = builder.and(predicate, builder
              .greaterThanOrEqualTo(root.get(param.getKey()), param.getValue().toString()));
        } else if (param.getOperation().equalsIgnoreCase("<")) {
            predicate = builder.and(predicate, builder.lessThanOrEqualTo(
              root.get(param.getKey()), param.getValue().toString()));
        } else if (param.getOperation().equalsIgnoreCase(":")) {
            if (root.get(param.getKey()).getJavaType() == String.class) {
                predicate = builder.and(predicate, builder.like(
                  root.get(param.getKey()), "%" + param.getValue() + "%"));
            } else {
                predicate = builder.and(predicate, builder.equal(
                  root.get(param.getKey()), param.getValue()));
            }
        }
    }

    public Predicate getPredicate() {
        return predicate;
    }
}

最后是 SearchCriteria 查询条件类：

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

该类包含三个字段：

  • ✅ key：对应实体字段名，如 firstName, age 等
  • ✅ operation：支持的操作符，如 :, <, > 等
  • ✅ value：对应的值，如 john, 25 等

4. 单元测试查询逻辑

我们通过几个单元测试来验证查询逻辑是否正确。

先准备测试数据：

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = { PersistenceConfig.class })
@Transactional
@TransactionConfiguration
public class JPACriteriaQueryTest {

    @Autowired
    private IUserDAO userApi;

    private User userJohn;
    private User userTom;

    @Before
    public void init() {
        userJohn = new User();
        userJohn.setFirstName("John");
        userJohn.setLastName("Doe");
        userJohn.setEmail("john@example.com");
        userJohn.setAge(22);
        userApi.save(userJohn);

        userTom = new User();
        userTom.setFirstName("Tom");
        userTom.setLastName("Doe");
        userTom.setEmail("tom@example.com");
        userTom.setAge(26);
        userApi.save(userTom);
    }
}

测试用例1：按 firstName 和 lastName 查询用户：

@Test
public void givenFirstAndLastName_whenGettingListOfUsers_thenCorrect() {
    List<SearchCriteria> params = new ArrayList<>();
    params.add(new SearchCriteria("firstName", ":", "John"));
    params.add(new SearchCriteria("lastName", ":", "Doe"));

    List<User> results = userApi.searchUser(params);

    assertThat(userJohn, isIn(results));
    assertThat(userTom, not(isIn(results)));
}

测试用例2：只按 lastName 查询：

@Test
public void givenLast_whenGettingListOfUsers_thenCorrect() {
    List<SearchCriteria> params = new ArrayList<>();
    params.add(new SearchCriteria("lastName", ":", "Doe"));

    List<User> results = userApi.searchUser(params);
    assertThat(userJohn, isIn(results));
    assertThat(userTom, isIn(results));
}

测试用例3：按 age > 25 查询：

@Test
public void givenLastAndAge_whenGettingListOfUsers_thenCorrect() {
    List<SearchCriteria> params = new ArrayList<>();
    params.add(new SearchCriteria("lastName", ":", "Doe"));
    params.add(new SearchCriteria("age", ">", "25"));

    List<User> results = userApi.searchUser(params);

    assertThat(userTom, isIn(results));
    assertThat(userJohn, not(isIn(results)));
}

测试用例4：按不存在的字段值查询：

@Test
public void givenWrongFirstAndLast_whenGettingListOfUsers_thenCorrect() {
    List<SearchCriteria> params = new ArrayList<>();
    params.add(new SearchCriteria("firstName", ":", "Adam"));
    params.add(new SearchCriteria("lastName", ":", "Fox"));

    List<User> results = userApi.searchUser(params);
    assertThat(userJohn, not(isIn(results)));
    assertThat(userTom, not(isIn(results)));
}

测试用例5：模糊匹配 firstName：

@Test
public void givenPartialFirst_whenGettingListOfUsers_thenCorrect() {
    List<SearchCriteria> params = new ArrayList<>();
    params.add(new SearchCriteria("firstName", ":", "jo"));

    List<User> results = userApi.searchUser(params);

    assertThat(userJohn, isIn(results));
    assertThat(userTom, not(isIn(results)));
}

5. 控制器层对接 REST 接口

最后，我们将查询逻辑接入 REST API，实现一个支持查询语言的接口。

@Controller
public class UserController {

    @Autowired
    private IUserDao api;

    @RequestMapping(method = RequestMethod.GET, value = "/users")
    @ResponseBody
    public List<User> findAll(@RequestParam(value = "search", required = false) String search) {
        List<SearchCriteria> params = new ArrayList<>();
        if (search != null) {
            Pattern pattern = Pattern.compile("(\\w+?)(:|<|>)(\\w+?),");
            Matcher matcher = pattern.matcher(search + ",");
            while (matcher.find()) {
                params.add(new SearchCriteria(matcher.group(1), 
                  matcher.group(2), matcher.group(3)));
            }
        }
        return api.searchUser(params);
    }
}

你可以这样调用接口进行查询：

http://localhost:8082/spring-rest-query-language/auth/users?search=lastName:doe,age%3E25

返回结果如下：

[{
    "id":2,
    "firstName":"tom",
    "lastName":"doe",
    "email":"tom@example.com",
    "age":26
}]

6. 小结

这个实现虽然还比较粗糙，但已经具备了基本的查询能力。它为我们提供了一个灵活、可扩展的 REST 查询基础。在后续文章中我们会继续优化这个查询语言，比如加入分页、排序、更复杂的逻辑操作等。

完整代码可以在 GitHub 上找到：GitHub 项目地址 ✅

如果你正在构建自己的 REST API，不妨试试这个思路。它简单、灵活、不依赖第三方库，适合中大型项目快速搭建查询功能。

原始标题:REST Query Language with Spring and JPA Criteria

« 上一篇： Spring JDBC教程
» 下一篇： 使用 Spring Data JPA Specifications 构建 REST 查询语言