1. Обзор
В этом руководстве мы создадим REST API поиска/фильтрации с использованием Spring Data JPA и спецификаций.
Мы начали рассматривать язык запросов в первой статье этой серии с решения на основе критериев JPA.
Итак, зачем язык запросов? Потому что поиска/фильтрации наших ресурсов по очень простым полям недостаточно для слишком сложных API. Язык запросов является более гибким и позволяет нам фильтровать именно те ресурсы, которые нам нужны.
2. Объект пользователя
Во-первых, давайте начнем с простой сущности пользователя для нашего 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 Data JPA .
Мы создадим UserSpecification , который реализует интерфейс Specification , и мы собираемся передать наше собственное ограничение для создания фактического запроса :
public class UserSpecification implements Specification<User> {
private SearchCriteria criteria;
@Override
public Predicate toPredicate
(Root<User> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
if (criteria.getOperation().equalsIgnoreCase(">")) {
return builder.greaterThanOrEqualTo(
root.<String> get(criteria.getKey()), criteria.getValue().toString());
}
else if (criteria.getOperation().equalsIgnoreCase("<")) {
return builder.lessThanOrEqualTo(
root.<String> get(criteria.getKey()), criteria.getValue().toString());
}
else if (criteria.getOperation().equalsIgnoreCase(":")) {
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 :
public class SearchCriteria {
private String key;
private String operation;
private Object value;
}
Реализация SearchCriteria содержит базовое представление ограничения, и на основе этого ограничения мы собираемся построить запрос:
key: имя поля, например,firstName,ageи т. д.операция: операция, например, равенство, меньше и т. д.value: значение поля, например, john, 25 и т. д.
Конечно, реализация упрощена и может быть улучшена. Тем не менее, это прочная основа для необходимых нам мощных и гибких операций.
4. Пользовательский репозиторий
Далее давайте взглянем на UserRepository .
Мы просто расширяем JpaSpecificationExecutor , чтобы получить новые API спецификаций:
public interface UserRepository
extends JpaRepository<User, Long>, JpaSpecificationExecutor<User> {}
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("john@doe.com");
userJohn.setAge(22);
repository.save(userJohn);
userTom = new User();
userTom.setFirstName("Tom");
userTom.setLastName("Doe");
userTom.setEmail("tom@doe.com");
userTom.setAge(26);
repository.save(userTom);
}
}
Далее давайте посмотрим, как найти пользователей с заданной фамилией :
@Test
public void givenLast_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec =
new UserSpecification(new SearchCriteria("lastName", ":", "doe"));
List<User> 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<User> results = repository.findAll(Specification.where(spec1).and(spec2));
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
Примечание. Мы использовали where и and для объединения спецификаций.
Далее давайте найдем пользователя с заданной фамилией и минимальным возрастом :
@Test
public void givenLastAndAge_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec1 =
new UserSpecification(new SearchCriteria("age", ">", "25"));
UserSpecification spec2 =
new UserSpecification(new SearchCriteria("lastName", ":", "doe"));
List<User> 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<User> 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<User> results = repository.findAll(spec);
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
6. Комбинируйте спецификации
Далее давайте взглянем на объединение наших пользовательских спецификаций , чтобы использовать несколько ограничений и фильтровать по нескольким критериям.
Мы собираемся реализовать конструктор — UserSpecificationsBuilder — для простого и плавного объединения спецификаций :
public class UserSpecificationsBuilder {
private final List<SearchCriteria> params;
public UserSpecificationsBuilder() {
params = new ArrayList<SearchCriteria>();
}
public UserSpecificationsBuilder with(String key, String operation, Object value) {
params.add(new SearchCriteria(key, operation, value));
return this;
}
public Specification<User> build() {
if (params.size() == 0) {
return null;
}
List<Specification> 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. Пользовательский контроллер
Наконец, давайте воспользуемся этой новой функцией постоянного поиска/фильтрации и настроим REST API , создав UserController с простой операцией поиска :
@Controller
public class UserController {
@Autowired
private UserRepository repo;
@RequestMapping(method = RequestMethod.GET, value = "/users")
@ResponseBody
public List<User> 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<User> 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":"tom@doe.com",
"age":26
}]
Поскольку в нашем примере шаблона поиск разделен символом «,» , условия поиска не могут содержать этот символ. Шаблон также не соответствует пробелам.
Если мы хотим искать значения, содержащие запятые, мы можем рассмотреть возможность использования другого разделителя, например «;».
Другой вариант — изменить шаблон для поиска значений между кавычками, а затем удалить их из условия поиска:
Pattern pattern = Pattern.compile("(\\w+?)(:|<|>)(\"([^\"]+)\")");
8. Заключение
В этой статье была рассмотрена простая реализация, которая может стать основой мощного языка запросов REST.
Мы хорошо использовали Спецификации данных Spring, чтобы убедиться, что API не привязано к домену, и у нас есть возможность обрабатывать многие другие типы операций.
Полную реализацию этой статьи можно найти в проекте GitHub . Это проект на основе Maven, поэтому его легко импортировать и запускать как есть.