TOC

Linguagem de Consulta REST com Especificações JPA de Dados de Primavera

Linguagem de Consulta REST com Especificações JPA de Dados de Primavera

1. Visão geral

Neste tutorial - construiremos umSearch/Filter REST API usando Spring Data JPA e Especificações.

Começamos a observar uma linguagem de consulta emfirst article dethis series - com uma solução baseada em critérios JPA.

Portanto -why a query language? Porque - para qualquer API suficientemente complexa - pesquisar / filtrar seus recursos por campos muito simples simplesmente não é suficiente. A query language is more flexiblee permite filtrar exatamente os recursos de que você precisa.

2. User Entidade

Primeiro - vamos começar com uma entidadeUser simples para nossa API de pesquisa: 

@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. Filtrar usandoSpecification

Agora - vamos direto para a parte mais interessante do problema - consultar com Spring Data JPASpecifications personalizado.

Vamos criar umUserSpecification que implementa a interfaceSpecification e vamos parapass in our own constraint to construct the actual query: 

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;
    }
}

Como podemos ver -we create a Specification based on some simple constrains que representamos na seguinte classe “SearchCriteria”: 

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

A implementação deSearchCriteria contém uma representação básica de uma restrição - e é com base nessa restrição que iremos construir a consulta:

  • key: o nome do campo - por exemplo,firstName,age, ... etc.

  • operation: a operação - por exemplo, igualdade, menor que, ... etc.

  • value: o valor do campo - por exemplo, john, 25,… etc.

Obviamente, a implementação é simplista e pode ser melhorada; é, no entanto, uma base sólida para as operações poderosas e flexíveis de que precisamos.

4. OUserRepository

A seguir - vamos dar uma olhada emUserRepository; estamos simplesmente estendendoJpaSpecificationExecutor para obter as novas APIs de especificação: 

public interface UserRepository
  extends JpaRepository, JpaSpecificationExecutor {}

5. Teste as consultas de pesquisa

Agora - vamos testar a nova API de pesquisa.

Primeiro, vamos criar alguns usuários para deixá-los prontos quando os testes forem executados: 

@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);
    }
}

A seguir, vamos ver como encontrar usuários comgiven last name: 

@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));
}

Agora, vamos ver como encontrar um usuário com determinadoboth first and last name: 

@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)));
}

Nota: Usamos “where” e “and” paracombine Specifications.

A seguir, vamos ver como encontrar um usuário com determinadoboth last name and minimum age: 

@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)));
}

Agora, vamos ver como pesquisar porUser quedoesn’t actually exist: 

@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)));
}

Finalmente - vamos ver como encontrar umUsergiven only part of the first name: 

@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. CombineSpecifications

A seguir - vamos dar uma olhada na combinação de nossosSpecifications personalizados para usar várias restrições e filtrar de acordo com vários critérios.

Vamos implementar um construtor -UserSpecificationsBuilder - para combinar facilmente e fluentementeSpecifications: 

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

Finalmente - vamos usar esta nova funcionalidade de pesquisa / filtro de persistência eset up the REST API - criando umUserController com uma operaçãosearch simples: 

@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);
    }
}

Observe que para oferecer suporte a outros sistemas não ingleses, o objetoPattern pode ser alterado como: 

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

Aqui está um exemplo de URL de teste para testar a API: 

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

E a resposta: 

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

Since the searches are split by a “,” in our Pattern example, the search terms can’t contain this character. O padrão também não corresponde aos espaços em branco.

Se quisermos procurar valores que contenham vírgulas, podemos considerar o uso de um separador diferente, como ";".

Outra opção seria alterar o padrão para procurar valores entre aspas e depois removê-los do termo de pesquisa: 

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

8. Conclusão

Este tutorial abordou uma implementação simples que pode ser a base de uma poderosa linguagem de consulta REST. Fizemos bom uso das especificações do Spring Data para nos certificar de manter a API longe do domínio ehave the option to handle many other types of operations.

Ofull implementation deste artigo pode ser encontrado emthe GitHub project - este é um projeto baseado em Maven, portanto, deve ser fácil de importar e executar como está.

Related