Guide de UriComponentsBuilder au printemps
1. introduction
Dans ce tutoriel, nous allons nous concentrer sur les SpringUriComponentsBuilder. Plus précisément, nous allons décrire divers exemples pratiques d'implémentation.
Le générateur fonctionne en conjonction avec la classeUriComponents - un conteneur immuable pour les composants URI.
Une nouvelle classeUriComponentsBuilder aide à créer des instancesUriComponents en fournissant un contrôle précis sur tous les aspects de la préparation d'un URI, y compris la construction, l'expansion à partir des variables de modèle et le codage.
2. Dépendances Maven
Afin d'utiliser le générateur, nous devons inclure la section suivante dans lesdependencies de nospom.xml:
org.springframework
spring-web
5.1.0.RELEASE
La dernière version peut être trouvéehere.
Cette dépendance ne couvre que Spring Web, alors n'oubliez pas d'ajouterspring-context pour une application Web complète.
Nous devons bien sûr également configurer la journalisation pour le projet - plus sur cehere.
3. Cas d'utilisation
Il existe de nombreux cas d'utilisation pratiques pour lesUriComponentsBuilder, à partir d'un encodage contextuel de caractères non autorisé dans le composant URI correspondant, en terminant par le remplacement dynamique de parties de l'URL.
L'un des plus grands avantages deUriComponentsBuilder est quewe can inject it right into a controller method:
@RequestMapping(method = RequestMethod.POST)
public ResponseEntity createCustomer(UriComponentsBuilder builder) {
// implementation
}Commençons par décrire les exemples utiles un par un. Nous utiliserons le framework JUnit pour tester immédiatement nos implémentations.
3.1. Construire un URI
Commençons par le plus simple. Nous voulons utiliserUriComponentsBuilder juste pour créer un lien simple:
@Test
public void constructUri() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.com").path("/junit-5").build();
assertEquals("/junit-5", uriComponents.toUriString());
}Comme nous pouvons l'observer, nous avons créé une nouvelle instance deUriComponentsBuilder, puis nous avons fourni le type de schéma, l'hôte et un chemin vers la destination de la requête.
Cet exemple simple peut être utile lorsque nous voulons effectuer une redirection vers une autre partie / lien de notre site Web.
3.2. Construire un URI codé
En plus de créer un lien simple, nous pouvons vouloir encoder le résultat final. Voyons cela en pratique:
@Test
public void constructUriEncoded() {
UriComponents uriComponents = UriComponentsBuilder.newInstance()
.scheme("http").host("www.example.com").path("/junit 5").build().encode();
assertEquals("/junit%205", uriComponents.toUriString());
}La différence dans cet exemple est que nous voulons ajouter un espace entre le motjunit et le nombre5. Selon lesRFC 3986, ce ne serait pas possible. Nous devons encoder le lien pour obtenir le résultat valide, en utilisant la méthodeencode().
3.3. Construire un URI à partir d'un modèle
Les modèles d'URI sont autorisés dans la plupart des composants d'un URI, mais leur valeur est limitée à un élément particulier, que nous indiquons comme modèle. Voyons l'exemple pour clarifier:
@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());
}La différence dans cet exemple réside dans la façon dont nous déclarons le chemin et comment nous construisons l'URI final. Le modèle qui sera remplacé par des mots-clés est indiqué par des crochets -\{…}, dans la méthodepath(). Le mot-clé utilisé pour générer le lien final est utilisé dans la méthode nomméebuildAndExpand(…).
Veuillez noter qu'il peut y avoir plus d'un mot clé à remplacer. En outre, le chemin d'accès à l'URI peut être relatif.
Cet exemple sera très utile lorsque nous souhaitons transmettre des objets de modèle au Spring Controller sur la base desquels nous allons créer un URI.
3.4. Construire un URI avec des paramètres de requête
Un autre cas très utile consiste à créer un URI avec des paramètres de requête.
Nous devons utiliserquery() deUriComponentsBuilder pour spécifier les paramètres de requête URI. Voyons l'exemple suivant:
@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());
}La requête sera ajoutée à la partie principale du lien. Nous pouvons fournir plusieurs paramètres de requête, en utilisant les crochets\{…}. Ils seront remplacés par des mots-clés dans la méthode nomméebuildAndExpand(…).
Cette implémentation deUriComponentsBuilder peut être utilisée pour créer, par exemple, un langage de requête pour une API REST.
3.5. Extension d'un URI avec des expressions régulières
Le dernier exemple montre la construction d'un URI avec validation par regex. Nous ne pourrons étendre lesuriComponents que si la validation de l'expression régulière réussit:
@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());
}Dans l'exemple mentionné ci-dessus, nous pouvons voir que la partie médiane du lien ne doit avoir que des lettres dea-z et la longueur dans une plage entre1-5.
De plus, nous utilisonssingletonMap, pour remplacer le mot cléname par la valeurtest.
Cet exemple est particulièrement utile lorsque nous permettons à un utilisateur de spécifier des liens de manière dynamique, mais que nous souhaitons fournir une sorte de sécurité où seuls les liens valides fonctionnent dans notre application Web.
4. Conclusion
Ce tutoriel présente des exemples utiles desUriComponentsBuilder.
Les principaux avantages deUriComponentsBuilder sont la flexibilité d'utilisation des variables de modèle d'URI et la possibilité de l'injecter directement dans les méthodes Spring Controller.
Tous les exemples et configurations sont disponibles ici surGitHub.