Création de contrôleurs REST avec Spring Boot

1. Le Rôle du Contrôleur dans notre Architecture

Jusqu'à présent, notre application ressemble à un moteur bien huilé mais isolé dans son garage. Le contrôleur est la carrosserie et le tableau de bord qui permettent à un utilisateur d'interagir avec ce moteur.

Dans une architecture logicielle en couches, le contrôleur appartient à la couche de Présentation (ou Presentation Layer). Son unique rôle est de :

1. Recevoir les requêtes HTTP entrantes.
2. Valider et extraire les informations nécessaires de la requête (paramètres, corps de la requête).
3. Déléguer le traitement métier à la couche de Service appropriée.
4. Recevoir le résultat du service et le formater en une réponse HTTP (souvent en JSON), avec le code de statut adéquat (200 OK, 201 Created, 404 Not Found, etc.).

Pour approfondir ce concept d'architecture en couches, que vous connaissez probablement déjà via des frameworks comme Laravel, je vous invite à regarder cette courte introduction.

Un point crucial à retenir : le contrôleur ne doit contenir aucune logique métier. Il est un chef d'orchestre, pas un musicien.

2. Anatomie d'un Contrôleur REST avec Spring

Pour créer un contrôleur REST, Spring nous fournit des annotations très expressives qui simplifient grandement le travail.

• @RestController: C'est l'annotation principale. Elle indique à Spring que cette classe est un contrôleur et que les valeurs retournées par ses méthodes doivent être directement écrites dans le corps de la réponse HTTP. Par défaut, Spring convertira les objets Java en JSON, ce qui est exactement ce que nous voulons pour une API REST.

• @RequestMapping("/api/..."): Placée au niveau de la classe, cette annotation définit un préfixe d'URL pour toutes les méthodes du contrôleur. C'est une excellente pratique pour organiser vos endpoints. Par exemple, tous les endpoints liés aux utilisateurs pourraient être sous /api/users.

• @GetMapping, @PostMapping, @PutMapping, @DeleteMapping: Ces annotations sont des spécialisations de @RequestMapping pour les verbes HTTP correspondants. Elles rendent le code plus lisible et moins verbeux.

Voici un exemple minimaliste de ce à quoi ressemble un contrôleur.

3. Implémentation des Endpoints (Points de terminaison)

Maintenant, mettons en pratique la création d'endpoints pour les opérations CRUD (Create, Read, Update, Delete). La vidéo suivante est un excellent tutoriel qui couvre la création d'une application CRUD complète. Nous allons nous en servir de guide, en nous concentrant sur la couche contrôleur.

Étape 1 : Créer la structure du contrôleur et injecter le service

Comme nous l'avons appris, le contrôleur délègue à un service. Dans la leçon précédente, nous avons créé un UserService. Créons maintenant un UserController qui l'utilisera.

// src/main/java/com/.../web/UserController.java
package com.votreentreprise.premierprojetspring.web;

import com.votreentreprise.premierprojetspring.services.UserService;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/users") // Tous les endpoints de ce contrôleur commenceront par /api/users
public class UserController {

    private final UserService userService;

    // Injection du service par le constructeur (bonne pratique)
    public UserController(UserService userService) {
        this.userService = userService;
    }
    
    // Nos méthodes d'endpoints viendront ici...
}

Notez que la vidéo Coding With Armand injecte directement le Repository dans le Controller pour simplifier (voir à 19:10). Dans une application professionnelle, on injecte toujours un service, comme nous le faisons ici.

Étape 2 : Lire des données (GET)

Pour lire des données, on utilise le verbe HTTP GET.

• Récupérer toutes les ressources : On utilise @GetMapping sans chemin supplémentaire.

  // Dans UserController.java
  
  @GetMapping
  public ResponseEntity<List<User>> getAllUsers() {
      // Pour l'instant, nous n'avons pas de base de données, 
      // alors nous allons simuler en demandant au service de nous renvoyer une liste.
      // Imaginons que userService a une méthode getUsers().
      List<User> users = userService.getUsers(); 
      return ResponseEntity.ok(users);
  }
  

  La vidéo Coding With Armand montre un exemple concret à 20:52 (@GetMapping pour findAll).

• Récupérer une ressource par son ID : On utilise un chemin variable avec @PathVariable.

  // Dans UserController.java
  
  @GetMapping("/{userId}")
  public ResponseEntity<User> getUserById(@PathVariable Long userId) {
      // Le service devrait avoir une méthode pour trouver un utilisateur par son ID.
      User user = userService.findUserById(userId);
      if (user != null) {
          return ResponseEntity.ok(user);
      } else {
          return ResponseEntity.notFound().build();
      }
  }
  

  La vidéo Coding With Armand illustre parfaitement l'utilisation de @PathVariable à 28:15.

Étape 3 : Créer une ressource (POST)

C'est ici que votre expérience full-stack est précieuse. Pour créer une ressource, le client (votre frontend React, par exemple) envoie une requête POST avec les données du nouvel objet en format JSON dans le corps de la requête.

Comment Spring récupère-t-il ce JSON ? Avec l'annotation @RequestBody.

Avant d'écrire le code, il est crucial de bien comprendre la différence entre passer des données dans l'URL (paramètres de requête) et dans le corps de la requête.

Fort de cette compréhension, voici comment l'implémenter :

// D'abord, on définit un 'DTO' pour représenter les données de création.
// C'est une simple classe Java (POJO).
public class CreateUserDto {
    private String username;
    private String email;
    // Getters et Setters...
}

// Puis, dans UserController.java
@PostMapping
public ResponseEntity<User> createUser(@RequestBody CreateUserDto createUserDto) {
    User newUser = userService.createUser(createUserDto);
    // Le code 201 Created est la réponse standard pour une création réussie.
    return new ResponseEntity<>(newUser, HttpStatus.CREATED); 
}

Spring, en coulisses, utilise une bibliothèque comme Jackson pour lire le JSON de la requête et instancier automatiquement votre objet CreateUserDto. C'est extrêmement puissant.

La vidéo Coding With Armand montre un exemple pratique de @PostMapping avec @RequestBody à 25:10.

4. Exercice Pratique

Pour consolider ces connaissances, je vous propose de recréer une partie du projet de la vidéo Coding With Armand, mais en respectant l'architecture en couches que nous avons établie.

1. Créez les couches de base :

   • Créez une classe d'entité Person comme montré à 11:13.
   • Créez une interface PersonRepository qui étend JpaRepository comme montré à 15:01. (Nous verrons JpaRepository en détail plus tard, pour l'instant, suivez l'exemple).

2. Ajoutez la couche Service (notre amélioration) :

   • Créez une classe PersonService.
   • Injectez PersonRepository dans PersonService.
   • Créez des méthodes dans PersonService qui appellent le repository. Par exemple :

     public List<Person> getAllPersons() {
         return personRepository.findAll();
     }
     
     public Person createPerson(Person person) {
         return personRepository.save(person);
     }
     

3. Créez le PersonController :

   • Créez la classe PersonController annotée avec @RestController et @RequestMapping("/api/persons").
   • Injectez votre PersonService (et non le PersonRepository directement).

4. Implémentez les Endpoints :

   • Créez une méthode getAllPersons() annotée avec @GetMapping qui appelle personService.getAllPersons(). Inspirez-vous de la vidéo à 20:52.
   • Créez une méthode createPerson() annotée avec @PostMapping qui prend un @RequestBody Person. Elle appellera personService.createPerson(). Inspirez-vous de la vidéo à 25:10.

5. Testez avec Postman :

   • Lancez votre application.
   • Utilisez Postman pour envoyer une requête POST à http://localhost:8080/api/persons avec un corps JSON comme {"name": "John Doe", "city": "Paris", "phoneNumber": "12345"}. N'oubliez pas de mettre le Content-Type à application/json.
   • Envoyez une requête GET à http://localhost:8080/api/persons pour vérifier que votre personne a bien été créée.

Cet exercice vous permettra de mettre en pratique la création de contrôleurs tout en renforçant les bonnes pratiques d'architecture vues dans la leçon précédente.

Conclusion

Félicitations ! Vous avez franchi une étape décisive en exposant la logique de votre application au monde extérieur. Vous savez maintenant comment créer des points d'entrée pour une API REST.

Points clés à retenir :

• Le @RestController est le stéréotype pour les contrôleurs d'API dans Spring.
• Le @RequestMapping permet de mapper des URL à des contrôleurs et à des méthodes.
• @GetMapping, @PostMapping, etc., sont des raccourcis spécifiques aux verbes HTTP.
• Le @PathVariable sert à extraire des valeurs de l'URL (ex: /users/123).
• Le @RequestBody est essentiel pour désérialiser le corps JSON d'une requête (typiquement POST ou PUT) en un objet Java.
• Un contrôleur doit rester "maigre" et déléguer toute la logique métier à la couche de service.

Dans la prochaine leçon, nous allons nous intéresser à un aspect plus opérationnel mais tout aussi crucial : gérer la configuration de l'application pour différents environnements (développement, production) avec application.properties et les profils Spring.