Guia para UriComponentsBuilder na primavera
1. Introdução
Neste tutorial, vamos nos concentrar no SpringUriComponentsBuilder.. Mais especificamente, descreveremos vários exemplos de implementação prática.
O construtor trabalha em conjunto com a classeUriComponents - um contêiner imutável para componentes URI.
Uma nova classeUriComponentsBuilder ajuda a criar instâncias deUriComponents fornecendo controle refinado sobre todos os aspectos da preparação de um URI, incluindo construção, expansão de variáveis de modelo e codificação.
2. Dependências do Maven
Para usar o construtor, precisamos incluir a seguinte seção nodependencies do nossopom.xml:
org.springframework
spring-web
5.1.0.RELEASE
A versão mais recente pode ser encontradahere.
Esta dependência cobre apenas Spring Web, então não se esqueça de adicionarspring-context para um aplicativo web completo.
É claro que também precisamos configurar o registro para o projeto - mais emhere.
3. Casos de Uso
Existem muitos casos de uso prático para oUriComponentsBuilder, começando com uma codificação contextual de caracteres não permitidos no componente URI correspondente, terminando na substituição de partes da URL dinamicamente.
Uma das maiores vantagens deUriComponentsBuilder é quewe can inject it right into a controller method:
@RequestMapping(method = RequestMethod.POST)
public ResponseEntity createCustomer(UriComponentsBuilder builder) {
// implementation
}Vamos começar descrevendo exemplos úteis, um por um. Usaremos a estrutura JUnit para testar nossas implementações imediatamente.
3.1. Construindo um URI
Vamos começar com o mais simples. Queremos usarUriComponentsBuilder apenas para criar um link simples:
@Test
public void constructUri() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.com").path("/junit-5").build();
assertEquals("/junit-5", uriComponents.toUriString());
}Como podemos observar, criamos uma nova instância deUriComponentsBuilder, então fornecemos o tipo de esquema, host e um caminho para o destino da solicitação.
Este exemplo simples pode ser útil quando queremos realizar um redirecionamento para outra parte / link de nosso site.
3.2. Construindo um URI codificado
Além de criar um link simples, podemos codificar o resultado final. Vamos ver isso na prática:
@Test
public void constructUriEncoded() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.com").path("/junit 5").build().encode();
assertEquals("/junit%205", uriComponents.toUriString());
}A diferença neste exemplo é que queremos adicionar espaço entre a palavrajunite o número5. De acordo comRFC 3986, isso não seria possível. Precisamos codificar o link para obter o resultado válido, usando o métodoencode().
3.3. Construindo um URI a partir de um modelo
Modelos de URI são permitidos na maioria dos componentes de um URI, mas seu valor é restrito a um elemento específico, que indicamos como modelo. Vejamos o exemplo para esclarecer:
@Test
public void constructUriFromTemplate() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.com").path("/{article-name}")
.buildAndExpand("junit-5");
assertEquals("/junit-5", uriComponents.toUriString());
}A diferença neste exemplo está na maneira como declaramos o caminho e como construímos o URI final. O modelo que será substituído por palavras-chave é indicado por colchetes -\{…}, dentro do métodopath(). A palavra-chave usada para gerar o link final é usada no método denominadobuildAndExpand(…).
Observe que pode haver mais de uma palavra-chave a ser substituída. Além disso, o caminho para o URI pode ser relativo.
Este exemplo será muito útil quando quisermos passar objetos de modelo para o Spring Controller com base no qual construiremos um URI.
3.4. Construindo um URI com parâmetros de consulta
Outro caso muito útil é criar URI com parâmetros de consulta.
Precisamos usarquery() deUriComponentsBuilder para especificar os parâmetros de consulta URI. Vejamos o seguinte exemplo:
@Test
public void constructUriWithQueryParameter() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.google.com")
.path("/").query("q={keyword}").buildAndExpand("example");
assertEquals("http://www.google.com/?q=example", uriComponents.toUriString());
}A consulta será adicionada à parte principal do link. Podemos fornecer vários parâmetros de consulta, usando colchetes\{…}.. Eles serão substituídos por palavras-chave no método denominadobuildAndExpand(…).
Esta implementação deUriComponentsBuilder pode ser usada para construir - por exemplo - uma linguagem de consulta para uma API REST.
3.5. Expandindo um URI com expressões regulares
O último exemplo está mostrando uma construção de um URI com validação de regex. Poderemos expandir ouriComponents apenas se a validação de regex for bem-sucedida:
@Test
public void expandWithRegexVar() {
String template = "/myurl/{name:[a-z]{1,5}}/show";
UriComponents uriComponents = UriComponentsBuilder.fromUriString(template)
.build();
uriComponents = uriComponents.expand(Collections.singletonMap("name", "test"));
assertEquals("/myurl/test/show", uriComponents.getPath());
}No exemplo mencionado acima, podemos ver que a parte do meio do link precisa ter apenas letras dea-ze o comprimento em um intervalo entre1-5.
Além disso, estamos usandosingletonMap, para substituir a palavra-chavename pelo valortest.
Este exemplo é particularmente útil quando permitimos que um usuário especifique links dinamicamente, mas queremos fornecer uma espécie de segurança onde apenas links válidos funcionam em nosso aplicativo da web.
4. Conclusão
Este tutorial apresenta exemplos úteis deUriComponentsBuilder.
As principais vantagens deUriComponentsBuilder são a flexibilidade de usar variáveis de template URI e a possibilidade de injetá-las diretamente nos métodos do Spring Controller.
Todos os exemplos e configurações estão disponíveis aqui emGitHub.