REST Query Language - Операции расширенного поиска
1. обзор
В этой статье мы расширим язык запросов REST, который мы разработали вthe previous parts изthe series, доinclude more search operations.
Теперь мы поддерживаем следующие операции: Равенство, Отрицание, Больше чем, Меньше чем, Начинается с, Завершается с, Содержит и Нравится.
Обратите внимание, что мы исследовали три реализации - критерии JPA, спецификации Spring Data JPA и DSL запросов; в этой статье мы продолжим работу со спецификациями, потому что это чистый и гибкий способ представления наших операций.
2. SearchOperationenum
Во-первых, давайте начнем с определения лучшего представления наших различных поддерживаемых операций поиска - с помощью перечисления:
public enum SearchOperation {
EQUALITY, NEGATION, GREATER_THAN, LESS_THAN, LIKE, STARTS_WITH, ENDS_WITH, CONTAINS;
public static final String[] SIMPLE_OPERATION_SET = { ":", "!", ">", "<", "~" };
public static SearchOperation getSimpleOperation(char input) {
switch (input) {
case ':':
return EQUALITY;
case '!':
return NEGATION;
case '>':
return GREATER_THAN;
case '<':
return LESS_THAN;
case '~':
return LIKE;
default:
return null;
}
}
}
У нас есть два набора операций:
1. Simple - может быть представлен одним символом:
-
Равенство: представлено двоеточием (:)
-
Отрицание: представлено восклицательным знаком (!)
-
Больше чем: представлено (>)
-
Меньше чем: представлено (<)
-
Как: представлен тильдой (~)
2. Complex - необходимо представить более одного символа:
-
Начинается с: представлен (=prefix*)
-
Заканчивается на: представлен (=*suffix)
-
Содержит: представлено (=*substring*)
Нам также нужно изменить наш классSearchCriteria, чтобы использовать новыйSearchOperation:
public class SearchCriteria {
private String key;
private SearchOperation operation;
private Object value;
}
3. ИзменитьUserSpecification
А теперь давайте включим новые поддерживаемые операции в нашу реализациюUserSpecification:
public class UserSpecification implements Specification {
private SearchCriteria criteria;
@Override
public Predicate toPredicate(
Root root, CriteriaQuery> query, CriteriaBuilder builder) {
switch (criteria.getOperation()) {
case EQUALITY:
return builder.equal(root.get(criteria.getKey()), criteria.getValue());
case NEGATION:
return builder.notEqual(root.get(criteria.getKey()), criteria.getValue());
case GREATER_THAN:
return builder.greaterThan(root. get(
criteria.getKey()), criteria.getValue().toString());
case LESS_THAN:
return builder.lessThan(root. get(
criteria.getKey()), criteria.getValue().toString());
case LIKE:
return builder.like(root. get(
criteria.getKey()), criteria.getValue().toString());
case STARTS_WITH:
return builder.like(root. get(criteria.getKey()), criteria.getValue() + "%");
case ENDS_WITH:
return builder.like(root. get(criteria.getKey()), "%" + criteria.getValue());
case CONTAINS:
return builder.like(root. get(
criteria.getKey()), "%" + criteria.getValue() + "%");
default:
return null;
}
}
}
4. Тесты на стойкость
Далее - давайте протестируем наши новые операции поиска - на уровне постоянства:
4.1. Тест на равенство
В следующем примере мы будем искать пользователяby their first and last name:
@Test
public void givenFirstAndLastName_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("firstName", SearchOperation.EQUALITY, "john"));
UserSpecification spec1 = new UserSpecification(
new SearchCriteria("lastName", SearchOperation.EQUALITY, "doe"));
List results = repository.findAll(Specification.where(spec).and(spec1));
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
4.2. Отрицание теста
Затем давайте поищем пользователей, которые поtheir first name not “john”:
@Test
public void givenFirstNameInverse_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("firstName", SearchOperation.NEGATION, "john"));
List results = repository.findAll(Specification.where(spec));
assertThat(userTom, isIn(results));
assertThat(userJohn, not(isIn(results)));
}
4.3. Тест больше, чем
Далее - будем искать пользователей сage greater than “25”:
@Test
public void givenMinAge_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("age", SearchOperation.GREATER_THAN, "25"));
List results = repository.findAll(Specification.where(spec));
assertThat(userTom, isIn(results));
assertThat(userJohn, not(isIn(results)));
}
4.4. Тест начинается с
Далее - пользователи сtheir first name starting with “jo”:
@Test
public void givenFirstNamePrefix_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("firstName", SearchOperation.STARTS_WITH, "jo"));
List results = repository.findAll(spec);
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
4.5. Тест заканчивается
Затем мы будем искать пользователей сtheir first name ending with “n”:
@Test
public void givenFirstNameSuffix_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("firstName", SearchOperation.ENDS_WITH, "n"));
List results = repository.findAll(spec);
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
4.6. Тест содержит
Теперь поищем пользователей сtheir first name containing “oh”:
@Test
public void givenFirstNameSubstring_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("firstName", SearchOperation.CONTAINS, "oh"));
List results = repository.findAll(spec);
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
4.7. Диапазон испытаний
Наконец, мы будем искать пользователей сages between “20” and “25”:
@Test
public void givenAgeRange_whenGettingListOfUsers_thenCorrect() {
UserSpecification spec = new UserSpecification(
new SearchCriteria("age", SearchOperation.GREATER_THAN, "20"));
UserSpecification spec1 = new UserSpecification(
new SearchCriteria("age", SearchOperation.LESS_THAN, "25"));
List results = repository.findAll(Specification.where(spec).and(spec1));
assertThat(userJohn, isIn(results));
assertThat(userTom, not(isIn(results)));
}
5. UserSpecificationBuilder
Теперь, когда настойчивость выполнена и протестирована, давайте перейдем к веб-слою.
Мы будем использовать реализациюUserSpecificationBuilder из предыдущей статьи доincorporate the new new search operations:
public class UserSpecificationsBuilder {
private List params;
public UserSpecificationsBuilder with(
String key, String operation, Object value, String prefix, String suffix) {
SearchOperation op = SearchOperation.getSimpleOperation(operation.charAt(0));
if (op != null) {
if (op == SearchOperation.EQUALITY) {
boolean startWithAsterisk = prefix.contains("*");
boolean endWithAsterisk = suffix.contains("*");
if (startWithAsterisk && endWithAsterisk) {
op = SearchOperation.CONTAINS;
} else if (startWithAsterisk) {
op = SearchOperation.ENDS_WITH;
} else if (endWithAsterisk) {
op = SearchOperation.STARTS_WITH;
}
}
params.add(new SearchCriteria(key, op, value));
}
return this;
}
public Specification build() {
if (params.size() == 0) {
return null;
}
Specification result = new UserSpecification(params.get(0));
for (int i = 1; i < params.size(); i++) {
result = params.get(i).isOrPredicate()
? Specification.where(result).or(new UserSpecification(params.get(i)))
: Specification.where(result).and(new UserSpecification(params.get(i)));
}
return result;
}
}
6. UserController
Далее - нам нужно правильно изменить нашUserController наparse the new operations:
@RequestMapping(method = RequestMethod.GET, value = "/users")
@ResponseBody
public List findAllBySpecification(@RequestParam(value = "search") String search) {
UserSpecificationsBuilder builder = new UserSpecificationsBuilder();
String operationSetExper = Joiner.on("|").join(SearchOperation.SIMPLE_OPERATION_SET);
Pattern pattern = Pattern.compile(
"(\\w+?)(" + operationSetExper + ")(\p{Punct}?)(\\w+?)(\p{Punct}?),");
Matcher matcher = pattern.matcher(search + ",");
while (matcher.find()) {
builder.with(
matcher.group(1),
matcher.group(2),
matcher.group(4),
matcher.group(3),
matcher.group(5));
}
Specification spec = builder.build();
return dao.findAll(spec);
}
Теперь мы можем использовать API и получить правильные результаты с любой комбинацией критериев. Например - вот как будет выглядеть сложная операция при использовании API с языком запросов:
http://localhost:8080/users?search=firstName:jo*,age<25
И ответ:
[{
"id":1,
"firstName":"john",
"lastName":"doe",
"email":"[email protected]",
"age":24
}]
7. Тесты для Search API
Наконец, давайте убедимся, что наш API работает правильно, написав набор тестов API.
Начнем с простой настройки теста и инициализации данных:
@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(
classes = { ConfigTest.class, PersistenceConfig.class },
loader = AnnotationConfigContextLoader.class)
@ActiveProfiles("test")
public class JPASpecificationLiveTest {
@Autowired
private UserRepository repository;
private User userJohn;
private User userTom;
private final String URL_PREFIX = "http://localhost:8080/users?search=";
@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);
}
private RequestSpecification givenAuth() {
return RestAssured.given().auth()
.preemptive()
.basic("username", "password");
}
}
7.1. Тест на равенство
Во-первых, давайте найдем пользователя сthe first name “john” and last name “doe“:
@Test
public void givenFirstAndLastName_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "firstName:john,lastName:doe");
String result = response.body().asString();
assertTrue(result.contains(userJohn.getEmail()));
assertFalse(result.contains(userTom.getEmail()));
}
7.2. Отрицание теста
Теперь - будем искать пользователей, когдаtheir first name isn’t “john”:
@Test
public void givenFirstNameInverse_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "firstName!john");
String result = response.body().asString();
assertTrue(result.contains(userTom.getEmail()));
assertFalse(result.contains(userJohn.getEmail()));
}
7.3. Тест больше, чем
Далее - будем искать пользователей сage greater than “25”:
@Test
public void givenMinAge_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "age>25");
String result = response.body().asString();
assertTrue(result.contains(userTom.getEmail()));
assertFalse(result.contains(userJohn.getEmail()));
}
7.4. Тест начинается с
Далее - пользователи сtheir first name starting with “jo”:
@Test
public void givenFirstNamePrefix_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "firstName:jo*");
String result = response.body().asString();
assertTrue(result.contains(userJohn.getEmail()));
assertFalse(result.contains(userTom.getEmail()));
}
7.5. Тест заканчивается
Теперь - пользователи сtheir first name ending with “n”:
@Test
public void givenFirstNameSuffix_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "firstName:*n");
String result = response.body().asString();
assertTrue(result.contains(userJohn.getEmail()));
assertFalse(result.contains(userTom.getEmail()));
}
7.6. Тест содержит
Далее мы будем искать пользователей сtheir first name containing “oh”:
@Test
public void givenFirstNameSubstring_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "firstName:*oh*");
String result = response.body().asString();
assertTrue(result.contains(userJohn.getEmail()));
assertFalse(result.contains(userTom.getEmail()));
}
7.7. Диапазон испытаний
Наконец, мы будем искать пользователей сages between “20” and “25”:
@Test
public void givenAgeRange_whenGettingListOfUsers_thenCorrect() {
Response response = givenAuth().get(URL_PREFIX + "age>20,age<25");
String result = response.body().asString();
assertTrue(result.contains(userJohn.getEmail()));
assertFalse(result.contains(userTom.getEmail()));
}
8. Заключение
В этой статье мы перенесли язык запросов нашего REST Search API наa mature, tested, production-grade implementation. Теперь мы поддерживаем широкий спектр операций и ограничений, которые должны упростить элегантный переход к любому набору данных и доступ к именно тем ресурсам, которые нам нужны.
full implementation в этой статье можно найти вthe GitHub project - это проект на основе Maven, поэтому его должно быть легко импортировать и запускать как есть.