Implémentation de Logique Métier Complexe dans la Couche de Service

1. La Couche Service : Le Cerveau de l'Application

Votre expérience en développement web vous a déjà familiarisé avec l'idée de séparer les responsabilités. En backend Java avec Spring, l'architecture la plus courante est l'architecture en couches, et plus spécifiquement le pattern Controller - Service - Repository.

Pour bien comprendre le rôle de chaque couche, je vous invite à lire une courte introduction sur ce pattern.

Pour résumer et visualiser cette structure :

• Controller : La porte d'entrée. Il reçoit la requête HTTP, extrait les données (DTOs) et délègue le travail au service. Il ne contient aucune logique métier.
• Service : Le chef d'orchestre. C'est ici que résident les règles et les processus métier. Un service peut appeler un ou plusieurs repositories pour accomplir une tâche.
• Repository : L'expert en données. Il communique directement avec la base de données pour effectuer les opérations CRUD.

Le diagramme suivant illustre parfaitement cette organisation. Notre logique de commande appartiendra à la couche "Business (Métier)".

La vidéo ci-dessous explique très bien cette séparation des rôles et pourquoi la logique métier ne doit pas être dans le contrôleur.

2. Garantir la Cohérence avec @Transactional

Imaginez le processus de création de commande :

1. Enregistrer la nouvelle commande dans la table orders.
2. Pour chaque produit, enregistrer une ligne dans la table order_details.
3. Pour chaque produit, décrémenter le stock dans la table products.

Que se passe-t-il si l'application plante après l'étape 1 mais avant l'étape 3 ? Vous auriez une commande enregistrée, mais le stock ne serait pas à jour. Vos données seraient incohérentes.

La solution à ce problème est le concept de transaction. Une transaction est une opération "tout ou rien" (atomique). Soit toutes les étapes réussissent, soit, en cas d'erreur, toutes les modifications déjà effectuées sont annulées (on parle de rollback).

Spring simplifie énormément la gestion des transactions avec l'annotation @Transactional.

En plaçant @Transactional sur notre méthode de service createOrder(), nous nous assurons que la création de la commande, de ses détails et la mise à jour du stock forment une seule et unique opération indivisible.

3. Implémentation de la Logique de Commande

Passons maintenant au code. Pour nous concentrer sur la couche service, je vais supposer que les étapes suivantes sont déjà réalisées :

1. Repositories : Des interfaces OrderRepository, ProductRepository, et OrderDetailRepository ont été créées, chacune étendant JpaRepository.

2. DTOs : Nous avons des DTOs pour la requête. Le client enverra un JSON qui ressemblera à ceci, mappé sur des classes Java CreateOrderRequest et OrderItemRequest.

   {
     "customerName": "John Doe",
     "items": [
       { "productId": 1, "quantity": 2 },
       { "productId": 3, "quantity": 1 }
     ]
   }
   

3. Entités : L'entité ProductEntity a maintenant un champ private int stock;.

Voici à quoi ressemblerait notre OrderService.

// package com.example.ecommerce.service;

import com.example.ecommerce.dto.CreateOrderRequest;
import com.example.ecommerce.dto.OrderItemRequest;
import com.example.ecommerce.entity.OrderEntity;
import com.example.ecommerce.entity.OrderDetailEntity;
import com.example.ecommerce.entity.ProductEntity;
import com.example.ecommerce.repository.OrderDetailRepository;
import com.example.ecommerce.repository.OrderRepository;
import com.example.ecommerce.repository.ProductRepository;
import jakarta.persistence.EntityNotFoundException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.time.LocalDateTime;

@Service
public class OrderService {

    private final OrderRepository orderRepository;
    private final ProductRepository productRepository;
    private final OrderDetailRepository orderDetailRepository;

    public OrderService(OrderRepository orderRepository, ProductRepository productRepository, OrderDetailRepository orderDetailRepository) {
        this.orderRepository = orderRepository;
        this.productRepository = productRepository;
        this.orderDetailRepository = orderDetailRepository;
    }

    @Transactional // Annotation clé !
    public OrderEntity createOrder(CreateOrderRequest request) {
        // 1. Créer l'entité de commande principale
        OrderEntity order = new OrderEntity();
        order.setCustomerName(request.getCustomerName());
        order.setOrderDate(LocalDateTime.now());
        OrderEntity savedOrder = orderRepository.save(order);

        // 2. Traiter chaque article de la commande
        for (OrderItemRequest itemRequest : request.getItems()) {
            // Règle métier 1 : Vérifier que le produit existe
            ProductEntity product = productRepository.findById(itemRequest.getProductId())
                .orElseThrow(() -> new EntityNotFoundException("Product not found with id: " + itemRequest.getProductId()));
            
            // Règle métier 2 : Vérifier le stock
            if (product.getStock() < itemRequest.getQuantity()) {
                throw new IllegalStateException("Insufficient stock for product: " + product.getName());
            }

            // 3. Créer l'entité de détail de commande
            OrderDetailEntity orderDetail = new OrderDetailEntity();
            orderDetail.setOrder(savedOrder);
            orderDetail.setProduct(product);
            orderDetail.setQuantity(itemRequest.getQuantity());
            orderDetail.setUnitPrice(product.getPrice()); // On "photographie" le prix au moment de l'achat
            orderDetailRepository.save(orderDetail);

            // Règle métier 3 : Mettre à jour le stock du produit
            product.setStock(product.getStock() - itemRequest.getQuantity());
            productRepository.save(product);
        }

        return savedOrder;
    }
}

Analysons cette méthode :

• Elle est annotée avec @Transactional. Si une EntityNotFoundException ou une IllegalStateException est levée, Spring s'assurera que la commande (savedOrder) et tous les orderDetail déjà sauvegardés soient supprimés de la base de données. La transaction est entièrement annulée.
• Elle orchestre des appels à trois repositories différents. C'est typique d'une logique métier complexe.
• Elle implémente plusieurs règles métier :
  • La validation de l'existence du produit.
  • La vérification du stock disponible.
  • La mise à jour du stock.
  • La sauvegarde du prix au moment de l'achat (unitPrice), une règle cruciale pour que l'historique des commandes soit correct même si les prix des produits changent plus tard.

L'exemple de code dans la ressource StudyRaid que vous avez lue est très similaire et renforce cette approche. Il est bon de voir le même pattern appliqué dans différents contextes.

4. Le Rôle Simplifié du Controller

Maintenant que toute la logique est dans le service, à quoi ressemble le contrôleur ? Il devient remarquablement simple.

// package com.example.ecommerce.controller;

@RestController
@RequestMapping("/api/orders")
public class OrderController {

    private final OrderService orderService;

    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    @PostMapping
    public ResponseEntity<OrderDto> createOrder(@RequestBody CreateOrderRequest request) {
        OrderEntity createdOrder = orderService.createOrder(request);
        // On pourrait mapper 'createdOrder' vers un OrderDto avant de le renvoyer
        // Pour l'instant, nous simplifions
        return ResponseEntity.status(HttpStatus.CREATED).body(convertToDto(createdOrder));
    }
    
    // ... méthode privée convertToDto non montrée ...
}

Le contrôleur ne fait que trois choses :

1. Recevoir la requête HTTP et désérialiser le JSON en CreateOrderRequest.
2. Appeler la méthode createOrder du service.
3. Renvoyer une réponse HTTP 201 Created avec les détails de la commande créée.

Il est complètement découplé de la complexité de la logique métier. C'est propre, maintenable et facile à tester.

Conclusion

Dans cette leçon, vous avez franchi une étape essentielle pour devenir un développeur backend professionnel. Vous avez déplacé la logique de l'application dans la couche de service, là où elle doit être, et vous avez appris à utiliser @Transactional pour garantir l'intégrité de vos données lors d'opérations complexes.

Points clés à retenir :

• La logique métier (règles, validations, orchestration) appartient à la couche service.
• L'architecture Controller-Service-Repository permet de séparer clairement les responsabilités.
• L'annotation @Transactional est indispensable pour les opérations qui modifient plusieurs entités, car elle garantit l'atomicité (tout ou rien).
• En cas d'erreur (exception non capturée) dans une méthode transactionnelle, toutes les modifications de la transaction sont annulées (rollback).

Exercice de réflexion :
Imaginez que nous ajoutions une nouvelle règle métier : "Un client ne peut pas commander plus de 5 unités du même produit dans une seule commande". Dans quelle classe et dans quelle méthode ajouteriez-vous cette vérification ?
Indice : La réponse se trouve dans le code de la méthode que nous venons d'écrire.

Dans la prochaine leçon, nous aborderons un sujet fondamental pour toute application exposée sur le web : la sécurité. Vous apprendrez à configurer Spring Security pour protéger les endpoints de notre API, en commençant par une authentification basique.