Язык запросов REST со спецификациями Spring Data JPA

1. Обзор

В этом уроке – мы построим Search/Filter REST API с использованием Spring Data JPA и спецификаций.

Мы начали рассматривать язык запросов в первой статье этой серии – с решением, основанным на критериях JPA.

Итак – почему язык запросов? Потому что – для любого сложного-достаточно API – поиска/фильтрации ваших ресурсов по очень простым полям просто недостаточно. Язык запросов более гибкий и позволяет отфильтровать именно те ресурсы, которые вам нужны.

2. Сущность пользователя

Во – первых, давайте начнем с простой User сущности для нашего поискового API:

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

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

    private int age;
    
    // standard getters and setters
}

3. Фильтр С Использованием Спецификации

Теперь – давайте сразу перейдем к самой интересной части проблемы – запросу пользовательских данных Spring JPA Спецификации .

Мы создадим Пользовательскую спецификацию , которая реализует Спецификацию интерфейс, и мы собираемся передать наше собственное ограничение для построения фактического запроса :

public class UserSpecification implements Specification {

    private SearchCriteria criteria;

    @Override
    public Predicate toPredicate
      (Root root, CriteriaQuery query, CriteriaBuilder builder) {
 
        if (criteria.getOperation().equalsIgnoreCase(">")) {
            return builder.greaterThanOrEqualTo(
              root. get(criteria.getKey()), criteria.getValue().toString());
        } 
        else if (criteria.getOperation().equalsIgnoreCase("<")) {
            return builder.lessThanOrEqualTo(
              root. get(criteria.getKey()), criteria.getValue().toString());
        } 
        else if (criteria.getOperation().equalsIgnoreCase(":")) {
            if (root.get(criteria.getKey()).getJavaType() == String.class) {
                return builder.like(
                  root.get(criteria.getKey()), "%" + criteria.getValue() + "%");
            } else {
                return builder.equal(root.get(criteria.getKey()), criteria.getValue());
            }
        }
        return null;
    }
}

Как мы видим – мы создаем Спецификацию на основе некоторых простых ограничений , которые мы представляем в следующем классе ” SearchCriteria “:

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

Реализация SearchCriteria содержит базовое представление ограничения – и именно на основе этого ограничения мы будем строить запрос:

ключ : имя поля – например, Имя , возраст , … и т.д.
операция : операция – например, равенство, меньше, … и т. Д.
значение : значение поля – например, джон, 25, … и т. Д.

Конечно, реализация упрощена и может быть улучшена; однако это прочная основа для мощных и гибких операций, в которых мы нуждаемся.

4. Пользовательская база данных

Далее – давайте взглянем на UserRepository ; мы просто расширяем JpaSpecificationExecutor , чтобы получить новые API спецификации:

public interface UserRepository 
  extends JpaRepository, JpaSpecificationExecutor {}

5. Проверьте поисковые запросы

Теперь – давайте протестируем новый API поиска.

Во-первых, давайте создадим несколько пользователей, чтобы они были готовы к запуску тестов:

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(classes = { PersistenceJPAConfig.class })
@Transactional
@TransactionConfiguration
public class JPASpecificationsTest {

    @Autowired
    private UserRepository repository;

    private User userJohn;
    private User userTom;

    @Before
    public void init() {
        userJohn = new User();
        userJohn.setFirstName("John");
        userJohn.setLastName("Doe");
        userJohn.setEmail("[email protected]");
        userJohn.setAge(22);
        repository.save(userJohn);

        userTom = new User();
        userTom.setFirstName("Tom");
        userTom.setLastName("Doe");
        userTom.setEmail("[email protected]");
        userTom.setAge(26);
        repository.save(userTom);
    }
}

Далее давайте посмотрим, как найти пользователей с заданной фамилией :

@Test
public void givenLast_whenGettingListOfUsers_thenCorrect() {
    UserSpecification spec = 
      new UserSpecification(new SearchCriteria("lastName", ":", "doe"));
    
    List results = repository.findAll(spec);

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

Теперь давайте посмотрим, как найти пользователя с заданным именем и фамилией :

@Test
public void givenFirstAndLastName_whenGettingListOfUsers_thenCorrect() {
    UserSpecification spec1 = 
      new UserSpecification(new SearchCriteria("firstName", ":", "john"));
    UserSpecification spec2 = 
      new UserSpecification(new SearchCriteria("lastName", ":", "doe"));
    
    List results = repository.findAll(Specification.where(spec1).and(spec2));

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

Примечание: Мы использовали ” где ” и ” и ” для объединения спецификаций .

Далее давайте посмотрим, как найти пользователя с заданной фамилией и минимальным возрастом :

@Test
public void givenLastAndAge_whenGettingListOfUsers_thenCorrect() {
    UserSpecification spec1 = 
      new UserSpecification(new SearchCriteria("age", ">", "25"));
    UserSpecification spec2 = 
      new UserSpecification(new SearchCriteria("lastName", ":", "doe"));

    List results = 
      repository.findAll(Specification.where(spec1).and(spec2));

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

Теперь давайте посмотрим, как искать Пользователя , которого на самом деле не существует :

@Test
public void givenWrongFirstAndLast_whenGettingListOfUsers_thenCorrect() {
    UserSpecification spec1 = 
      new UserSpecification(new SearchCriteria("firstName", ":", "Adam"));
    UserSpecification spec2 = 
      new UserSpecification(new SearchCriteria("lastName", ":", "Fox"));

    List results = 
      repository.findAll(Specification.where(spec1).and(spec2));

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

Наконец – давайте посмотрим, как найти Пользователя с учетом только части имени :

@Test
public void givenPartialFirst_whenGettingListOfUsers_thenCorrect() {
    UserSpecification spec = 
      new UserSpecification(new SearchCriteria("firstName", ":", "jo"));
    
    List results = repository.findAll(spec);

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

6. Комбинируйте Технические характеристики

Далее – давайте рассмотрим объединение наших пользовательских Спецификаций для использования нескольких ограничений и фильтрации в соответствии с несколькими критериями.

Мы собираемся реализовать конструктор – UserSpecificationsBuilder – для легкого и плавного объединения Спецификаций :

public class UserSpecificationsBuilder {
    
    private final List params;

    public UserSpecificationsBuilder() {
        params = new ArrayList();
    }

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

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

        List specs = params.stream()
          .map(UserSpecification::new)
          .collect(Collectors.toList());
        
        Specification result = specs.get(0);

        for (int i = 1; i < params.size(); i++) {
            result = params.get(i)
              .isOrPredicate()
                ? Specification.where(result)
                  .or(specs.get(i))
                : Specification.where(result)
                  .and(specs.get(i));
        }       
        return result;
    }
}

7. UserController

Наконец – давайте воспользуемся этой новой функцией поиска/фильтра персистентности и настроим REST API – создав UserController с помощью простой операции поиска :

@Controller
public class UserController {

    @Autowired
    private UserRepository repo;

    @RequestMapping(method = RequestMethod.GET, value = "/users")
    @ResponseBody
    public List search(@RequestParam(value = "search") String search) {
        UserSpecificationsBuilder builder = new UserSpecificationsBuilder();
        Pattern pattern = Pattern.compile("(\\w+?)(:|<|>)(\\w+?),");
        Matcher matcher = pattern.matcher(search + ",");
        while (matcher.find()) {
            builder.with(matcher.group(1), matcher.group(2), matcher.group(3));
        }
        
        Specification spec = builder.build();
        return repo.findAll(spec);
    }
}

Обратите внимание, что для поддержки других неанглоязычных систем объект Pattern может быть изменен следующим образом:

Pattern pattern = Pattern.compile("(\\w+?)(:|<|>)(\\w+?),", Pattern.UNICODE_CHARACTER_CLASS);

Вот пример тестового URL-адреса для тестирования API:

http://localhost:8080/users?search=lastName:doe,age>25

И ответ:

[{
    "id":2,
    "firstName":"tom",
    "lastName":"doe",
    "email":"[email protected]",
    "age":26
}]

Поскольку поиск разделен на “,” в нашем примере Pattern , условия поиска не могут содержать этот символ. Шаблон также не соответствует пробелам.

Если мы хотим искать значения, содержащие запятые, то мы можем рассмотреть возможность использования другого разделителя, такого как “;”.

Другим вариантом было бы изменить шаблон для поиска значений между кавычками, а затем удалить их из поискового запроса:

Pattern pattern = Pattern.compile("(\\w+?)(:|<|>)(\"([^\"]+)\")");

8. Заключение

В этом руководстве описана простая реализация, которая может стать основой мощного языка запросов REST. Мы хорошо использовали спецификации данных Spring, чтобы убедиться, что мы держим API подальше от домена и имеем возможность обрабатывать многие другие типы операций .

полную реализацию этой статьи можно найти в проекте GitHub – это проект на основе Maven, поэтому его должно быть легко импортировать и запускать как есть.