Création d'un service Web RESTful

English Version

https://spring.io/guides/gs/rest-service/

 

Ce guide vous guide tout au long du processus de création d'un service Web RESTful « Hello, World » avec Spring.

Ce que vous allez construire

Vous allez créer un service qui acceptera les requêtes HTTP GET à l'adresse http://localhost:8080/greeting.

Il répondra par une représentation JSON d'un message d'accueil, comme le montre la liste suivante :

{"id":1,"content":"Hello, World!"}

Vous pouvez personnaliser le message d'accueil avec un nameparamètre facultatif dans la chaîne de requête, comme le montre la liste suivante :

http://localhost:8080/greeting?name=User

La namevaleur du paramètre remplace la valeur par défaut Worldet est reflétée dans la réponse, comme le montre la liste suivante :

{"id":1,"content":"Hello, User!"}

De quoi as-tu besoin

Comment remplir ce guide

Comme la plupart des guides de démarrage de Spring , vous pouvez recommencer à zéro et terminer chaque étape ou vous pouvez ignorer les étapes de configuration de base qui vous sont déjà familières. Dans tous les cas, vous vous retrouvez avec un code fonctionnel.

Pour repartir de zéro , passez à Démarrer avec Spring Initializr .

Pour ignorer les bases , procédez comme suit :

Lorsque vous avez terminé , vous pouvez vérifier vos résultats par rapport au code dans gs-rest-service/complete.

À partir de Spring Initializr

Vous pouvez utiliser ce projet pré-initialisé et cliquer sur Générer pour télécharger un fichier ZIP. Ce projet est configuré pour s'adapter aux exemples de ce didacticiel.

Pour initialiser manuellement le projet :

  1. Accédez à https://start.spring.io . Ce service récupère toutes les dépendances dont vous avez besoin pour une application et effectue l'essentiel de la configuration pour vous.

  2. Choisissez Gradle ou Maven et la langue que vous souhaitez utiliser. Ce guide suppose que vous avez choisi Java.

  3. Cliquez sur Dépendances et sélectionnez Spring Web .

  4. Cliquez sur Générer .

  5. Téléchargez le fichier ZIP résultant, qui est une archive d'une application Web configurée avec vos choix.

  Si votre IDE dispose de l'intégration Spring Initializr, vous pouvez effectuer ce processus à partir de votre IDE.
  Vous pouvez également bifurquer le projet depuis Github et l'ouvrir dans votre IDE ou un autre éditeur.

Créer une classe de représentation de ressources

Maintenant que vous avez configuré le projet et le système de construction, vous pouvez créer votre service Web.

Commencez le processus en réfléchissant aux interactions de service.

Le service traitera GETles requêtes pour /greeting, éventuellement avec un nameparamètre dans la chaîne de requête. La GETrequête doit renvoyer une 200 OKréponse avec JSON dans le corps qui représente un message d'accueil. Cela devrait ressembler au résultat suivant :

{
    "id": 1,
    "content": "Hello, World!"
}

Le champ id est un identifiant unique pour le message d'accueil et contentconstitue la représentation textuelle du message d'accueil.

Pour modéliser la représentation du message d'accueil, créez une classe de représentation de ressources. Pour ce faire, fournissez une classe d'enregistrement Java pour les données idet content, comme le montre la liste suivante (à partir de src/main/java/com/example/restservice/Greeting.java) :

package com.example.restservice;

public record Greeting(long id, String content) { }
  Cette application utilise la bibliothèque Jackson JSON pour regrouper automatiquement les instances de type Greetingen JSON. Jackson est inclus par défaut par le web starter.

Créer un contrôleur de ressources

Dans l'approche de Spring pour créer des services Web RESTful, les requêtes HTTP sont gérées par un contrôleur. Ces composants sont identifiés par l' @RestControllerannotation, et ceux GreetingControlleraffichés dans la liste suivante (from src/main/java/com/example/restservice/GreetingController.java) gèrent GETles requêtes /greetingen renvoyant une nouvelle instance de la Greeting classe :

package com.example.restservice;

import java.util.concurrent.atomic.AtomicLong;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

	private static final String template = "Hello, %s!";
	private final AtomicLong counter = new AtomicLong();

	@GetMapping("/greeting")
	public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
		return new Greeting(counter.incrementAndGet(), String.format(template, name));
	}
}

Ce contrôleur est concis et simple, mais il se passe beaucoup de choses sous le capot. Nous le décomposons étape par étape.

L' annotation @GetMapping garantit que les requêtes HTTP GET /greeting sont mappées à la greeting() méthode.

  Il existe des annotations complémentaires pour d'autres verbes HTTP (par exemple @PostMappingpour POST). Il existe également une @RequestMappingannotation dont ils dérivent tous et qui peut servir de synonyme (par exemple @RequestMapping(method=GET)).

@RequestParam lie la valeur du paramètre de chaîne de requête name au name paramètre de la méthodegreeting(). Si le paramètre name est absent dans la requête, le defaultValue of World est utilisé.

L'implémentation du corps de la méthode crée et renvoie un nouvel Greeting objet avec des attributs idet content basés sur la valeur suivante de counter et formate le donné name en utilisant le message d'accueil template.

Une différence clé entre un contrôleur MVC traditionnel et le contrôleur de service Web RESTful présenté précédemment réside dans la manière dont le corps de la réponse HTTP est créé. Plutôt que de s'appuyer sur une technologie d'affichage pour effectuer le rendu côté serveur des données de message d'accueil au format HTML, ce contrôleur de service Web RESTful remplit et renvoie un Greeting objet. Les données de l'objet seront écrites directement dans la réponse HTTP au format JSON.

Ce code utilise l'annotation Spring @RestController, qui marque la classe comme un contrôleur où chaque méthode renvoie un objet de domaine au lieu d'une vue. C'est un raccourci pour inclure à la fois @Controlleret @ResponseBody.

L'objet Greeting doit être converti en JSON. Grâce à la prise en charge du convertisseur de messages HTTP de Spring, vous n'avez pas besoin d'effectuer cette conversion manuellement. Étant donné que Jackson 2 se trouve sur le chemin de classe, celui de Spring MappingJackson2HttpMessageConverterest automatiquement choisi pour convertir l' instance Greeting en JSON.

@SpringBootApplicationest une annotation de commodité qui ajoute tout ce qui suit :

  • @Configuration: marque la classe comme source de définitions de bean pour le contexte de l'application.

  • @EnableAutoConfiguration: demande à Spring Boot de commencer à ajouter des beans en fonction des paramètres de chemin de classe, d'autres beans et de divers paramètres de propriété. Par exemple, si spring-webmvcse trouve sur le chemin de classe, cette annotation marque l'application en tant qu'application Web et active des comportements clés, tels que la configuration d'un fichier DispatcherServlet.

  • @ComponentScan: indique à Spring de rechercher d'autres composants, configurations et services dans le com/example package, lui permettant de trouver les contrôleurs.

La main() méthode utilise la méthode de Spring Boot SpringApplication.run() pour lancer une application. Avez-vous remarqué qu'il n'y avait pas une seule ligne de XML ? Il n'y a pas non plus de fichier web.xml . Cette application Web est 100 % Java pur et vous n'avez pas eu à configurer de plomberie ou d'infrastructure.

Construire un JAR exécutable

Vous pouvez exécuter l'application à partir de la ligne de commande avec Gradle ou Maven. Vous pouvez également créer un seul fichier JAR exécutable contenant toutes les dépendances, classes et ressources nécessaires et l'exécuter. La création d'un jar exécutable facilite l'expédition, la version et le déploiement du service en tant qu'application tout au long du cycle de développement, dans différents environnements, etc.

Si vous utilisez Gradle, vous pouvez exécuter l'application en utilisant ./gradlew bootRun. Vous pouvez également créer le fichier JAR en utilisant ./gradlew build puis en exécutant le fichier JAR, comme suit :

java -jar build/libs/gs-rest-service-0.1.0.jar

Si vous utilisez Maven, vous pouvez exécuter l'application en utilisant ./mvnw spring-boot:run. Vous pouvez également créer le fichier JAR avec ./mvnw clean package puis exécuter le fichier JAR, comme suit :

java -jar cible/gs-rest-service-0.1.0.jar
  Les étapes décrites ici créent un fichier JAR exécutable. Vous pouvez également créer un fichier WAR classique .

La sortie de l’enregistrement s’affiche. Le service devrait être opérationnel en quelques secondes.

Testez le service

Maintenant que le service est opérationnel, visitez http://localhost:8080/greeting, où vous devriez voir :

{"id":1,"content":"Hello, World!"}

Fournissez un paramètre name de chaîne de requête en visitant http://localhost:8080/greeting?name=User. Remarquez comment la valeur de l' content attribut passe de Hello, World!à Hello, User!, comme le montre la liste suivante :

{"id":2,"content":"Hello, User!"}

Cette modification démontre que l' @RequestParamarrangement dans GreetingControllerfonctionne comme prévu. Le nameparamètre a reçu une valeur par défaut de World mais peut être explicitement remplacé via la chaîne de requête.

Notez également comment l' idattribut est passé de 1à 2. Cela prouve que vous travaillez sur la même GreetingController instance sur plusieurs requêtes et que son counter champ est incrémenté à chaque appel comme prévu.

Résumé

Toutes nos félicitations! Vous venez de développer un service web RESTful avec Spring.

Modifié le: mardi 22 août 2023, 08:15