Stratégies de Migration vers l’Architecture Hexagonale

@Controller("/api/users")
@RequiredArgsConstructor
public class UserController {
 
    private final DataSource dataSource;  // Couplage direct à la BDD
    private final RestTemplate restTemplate;  // Couplage à l'infra HTTP
 
    @Get("/{id}")
    public User getUser(Long id) {
        // Logique métier mélangée avec infrastructure
        String sql = "SELECT * FROM users WHERE id = ?";
        User user = jdbcTemplate.queryForObject(sql, new UserRowMapper(), id);
 
        // Appel API externe direct dans le controller
        String response = restTemplate.getForObject("https://api.example.com/users/" + id, String.class);
 
        // Validation métier dans le controller
        if (user.getAge() < 18) {
            throw new IllegalArgumentException("User must be 18+");
        }
 
        return user;
    }
}

┌─────────────────────────────────────────────────┐
│              Infrastructure                     │
│  UserController → GetUserUseCase                │
│                      ↓                          │
│              Application Layer                  │
│  GetUserUseCase → UserRepository (port)         │
│                      ↓                          │
│               Domain Layer                      │
│  User (entity) + Business Rules                 │
│                      ↓                          │
│  UserRepository (port) ← JpaUserRepository      │
│                      ↓                          │
│              Infrastructure                     │
│  JpaUserRepository (adapter OUT)                │
└─────────────────────────────────────────────────┘

Ancien système (Monolithe)
        ↓
    Réécriture complète (3-6 mois)
        ↓
Nouveau système (Hexagonal)

Itération 1: Migrer feature A
Itération 2: Migrer feature B
Itération 3: Migrer feature C
...
→ L'ancien système est progressivement étranglé

┌─────────────────────────────────────┐
│  Facade / Routing Layer             │
│  ├─ Feature A → Nouveau système     │
│  ├─ Feature B → Nouveau système     │
│  └─ Feature C → Ancien système      │
└─────────────────────────────────────┘
        ↓              ↓
   Hexagonal      Monolithe
   (nouveau)      (ancien)

Requête HTTP
    ↓
Proxy/Router
    ├─ Ancien système → Résultat A
    └─ Nouveau système → Résultat B
    ↓
Comparaison (A == B ?)
    ↓
Retour du résultat A (ancien système)

@Controller("/api/orders")
@RequiredArgsConstructor
public class OrderController {
 
    private final DataSource dataSource;
    private final RestTemplate restTemplate;
    private final EmailService emailService;
 
    @Post("/")
    public OrderResponse createOrder(@Body CreateOrderDto dto) {
        // Validation inline
        if (dto.getUserId() == null) {
            throw new IllegalArgumentException("User ID required");
        }
        if (dto.getItems().isEmpty()) {
            throw new IllegalArgumentException("Order must have items");
        }
 
        // Vérifier que l'utilisateur existe (appel BDD direct)
        String userSql = "SELECT * FROM users WHERE id = ?";
        User user = jdbcTemplate.queryForObject(userSql, new UserRowMapper(), dto.getUserId());
        if (user == null) {
            throw new IllegalArgumentException("User not found");
        }
 
        // Vérifier le stock (appel API direct)
        for (OrderItemDto item : dto.getItems()) {
            String stockUrl = "https://inventory.example.com/products/" + item.getProductId() + "/stock";
            Integer stock = restTemplate.getForObject(stockUrl, Integer.class);
            if (stock < item.getQuantity()) {
                throw new IllegalArgumentException("Insufficient stock for product " + item.getProductId());
            }
        }
 
        // Calculer le total
        BigDecimal total = dto.getItems().stream()
            .map(item -> item.getPrice().multiply(BigDecimal.valueOf(item.getQuantity())))
            .reduce(BigDecimal.ZERO, BigDecimal::add);
 
        // Sauvegarder la commande
        String orderSql = "INSERT INTO orders (user_id, total, status) VALUES (?, ?, ?)";
        jdbcTemplate.update(orderSql, dto.getUserId(), total, "PENDING");
 
        // Envoyer email de confirmation
        emailService.sendOrderConfirmation(user.getEmail(), total);
 
        return new OrderResponse(1L, total, "PENDING");
    }
}

// domain/model/Order.java
@Value
public class Order {
    Long id;
    Long userId;
    List<OrderItem> items;
    BigDecimal total;
    OrderStatus status;
 
    public Order(Long userId, List<OrderItem> items) {
        validateItems(items);
        this.id = null;
        this.userId = userId;
        this.items = items;
        this.total = calculateTotal(items);
        this.status = OrderStatus.PENDING;
    }
 
    private void validateItems(List<OrderItem> items) {
        if (items == null || items.isEmpty()) {
            throw new IllegalArgumentException("Order must have at least one item");
        }
    }
 
    private BigDecimal calculateTotal(List<OrderItem> items) {
        return items.stream()
            .map(OrderItem::getSubtotal)
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}
 
// domain/model/OrderItem.java
@Value
public class OrderItem {
    Long productId;
    int quantity;
    BigDecimal price;
 
    public BigDecimal getSubtotal() {
        return price.multiply(BigDecimal.valueOf(quantity));
    }
}

// application/usecases/CreateOrderUseCase.java
@Singleton
@RequiredArgsConstructor
public class CreateOrderUseCaseImpl implements CreateOrderUseCase {
 
    private final OrderRepository orderRepository;
    private final UserRepository userRepository;
    private final InventoryService inventoryService;
    private final NotificationService notificationService;
 
    @Override
    public Order execute(CreateOrderCommand command) {
        // Vérifier que l'utilisateur existe
        User user = userRepository.findById(command.userId())
            .orElseThrow(() -> new ResourceNotFoundException("User not found"));
 
        // Vérifier le stock pour chaque produit
        for (OrderItemCommand item : command.items()) {
            if (!inventoryService.hasStock(item.productId(), item.quantity())) {
                throw new InsufficientStockException("Product " + item.productId());
            }
        }
 
        // Créer la commande (validation automatique)
        List<OrderItem> items = command.items().stream()
            .map(i -> new OrderItem(i.productId(), i.quantity(), i.price()))
            .toList();
        Order order = new Order(command.userId(), items);
 
        // Sauvegarder
        Order saved = orderRepository.save(order);
 
        // Notifier l'utilisateur (async)
        notificationService.sendOrderConfirmation(user.getEmail(), saved.getTotal());
 
        return saved;
    }
}

// infrastructure/adapters/in/rest/OrderController.java
@Controller("/api/orders")
@RequiredArgsConstructor
public class OrderController {
 
    private final CreateOrderUseCase createOrderUseCase;
 
    @Post("/")
    public OrderResponse createOrder(@Body CreateOrderRequest request) {
        CreateOrderCommand command = toCommand(request);
        Order order = createOrderUseCase.execute(command);
        return toResponse(order);
    }
}

// Test du Use Case (sans infrastructure)
@MicronautTest
class CreateOrderUseCaseTest {
 
    @Inject
    CreateOrderUseCase useCase;
 
    @MockBean(OrderRepository.class)
    OrderRepository orderRepository() { return mock(OrderRepository.class); }
 
    @MockBean(UserRepository.class)
    UserRepository userRepository() { return mock(UserRepository.class); }
 
    @MockBean(InventoryService.class)
    InventoryService inventoryService() { return mock(InventoryService.class); }
 
    @Test
    void shouldCreateOrderSuccessfully() {
        // Given
        User user = new User(1L, "john@example.com", "John", 25);
        when(userRepository.findById(1L)).thenReturn(Optional.of(user));
        when(inventoryService.hasStock(anyLong(), anyInt())).thenReturn(true);
        when(orderRepository.save(any())).thenAnswer(inv -> inv.getArgument(0));
 
        CreateOrderCommand command = new CreateOrderCommand(
            1L,
            List.of(new OrderItemCommand(1L, 2, BigDecimal.valueOf(10.0)))
        );
 
        // When
        Order order = useCase.execute(command);
 
        // Then
        assertThat(order.getTotal()).isEqualByComparingTo(BigDecimal.valueOf(20.0));
        assertThat(order.getStatus()).isEqualTo(OrderStatus.PENDING);
        verify(orderRepository).save(any());
    }
 
    @Test
    void shouldRejectOrderWhenUserNotFound() {
        // Given
        when(userRepository.findById(1L)).thenReturn(Optional.empty());
 
        CreateOrderCommand command = new CreateOrderCommand(1L, List.of());
 
        // When/Then
        assertThatThrownBy(() -> useCase.execute(command))
            .isInstanceOf(ResourceNotFoundException.class)
            .hasMessageContaining("User not found");
    }
 
    @Test
    void shouldRejectOrderWhenInsufficientStock() {
        // Given
        User user = new User(1L, "john@example.com", "John", 25);
        when(userRepository.findById(1L)).thenReturn(Optional.of(user));
        when(inventoryService.hasStock(1L, 10)).thenReturn(false);
 
        CreateOrderCommand command = new CreateOrderCommand(
            1L,
            List.of(new OrderItemCommand(1L, 10, BigDecimal.valueOf(10.0)))
        );
 
        // When/Then
        assertThatThrownBy(() -> useCase.execute(command))
            .isInstanceOf(InsufficientStockException.class);
    }
}

// ❌ MAUVAIS : dépendance directe à JPA
@Singleton
public class CreateUserUseCase {
 
    @PersistenceContext
    private EntityManager entityManager;  // ❌ Couplage à JPA
 
    public User execute(CreateUserCommand command) {
        UserEntity entity = new UserEntity();
        entityManager.persist(entity);  // ❌ Utilisation directe de JPA
        return entity;
    }
}

// ✅ BON : dépendance à une abstraction (port)
@Singleton
@RequiredArgsConstructor
public class CreateUserUseCase {
 
    private final UserRepository userRepository;  // ✅ Interface (port)
 
    public User execute(CreateUserCommand command) {
        User user = new User(command.email(), command.name());
        return userRepository.save(user);  // ✅ Appel via le port
    }
}

// ❌ MAUVAIS : Anemic Domain
@Data
public class Order {
    private Long id;
    private BigDecimal total;
    private List<OrderItem> items;
    // Pas de logique métier !
}
 
// Logique métier dans le Use Case
public class CreateOrderUseCase {
    public Order execute(CreateOrderCommand command) {
        Order order = new Order();
        // Validation ici ❌
        if (command.items().isEmpty()) {
            throw new IllegalArgumentException("Empty order");
        }
        // Calcul du total ici ❌
        BigDecimal total = command.items().stream()
            .map(...)
            .reduce(...);
        order.setTotal(total);
        return orderRepository.save(order);
    }
}

// ✅ BON : Rich Domain Model
@Value
public class Order {
    Long id;
    List<OrderItem> items;
    BigDecimal total;
 
    public Order(List<OrderItem> items) {
        validateItems(items);  // ✅ Validation dans le domain
        this.items = items;
        this.total = calculateTotal(items);  // ✅ Calcul dans le domain
    }
 
    private void validateItems(List<OrderItem> items) {
        if (items == null || items.isEmpty()) {
            throw new IllegalArgumentException("Order must have items");
        }
    }
 
    private BigDecimal calculateTotal(List<OrderItem> items) {
        return items.stream()
            .map(OrderItem::getSubtotal)
            .reduce(BigDecimal.ZERO, BigDecimal::add);
    }
}

// ❌ MAUVAIS : migration sans tests
// 1. Créer le nouveau Use Case
// 2. Router le trafic immédiatement
// 3. Déployer en prod
// 4. 💥 Bug en production

// ✅ BON : TDD pendant la migration
// 1. Écrire les tests pour l'ancien comportement
@Test
void shouldCreateUserWithOldSystem() {
    // Test du comportement existant
}
 
// 2. Migrer vers le nouveau système
@Test
void shouldCreateUserWithNewSystem() {
    // Test du nouveau système
}
 
// 3. Tests de non-régression
@Test
void shouldHaveSameBehavior() {
    // Comparer ancien vs nouveau
}
 
// 4. Déployer avec confiance

Migration initiale : Migrer GET /users/{id}
    ↓
"Tant qu'on y est, ajoutons la pagination"
    ↓
"Et si on ajoutait le tri et les filtres ?"
    ↓
"Et GraphQL tant qu'on y est ?"
    ↓
💥 Migration qui ne finit jamais

✅ Phase 1 : Migration à iso-fonctionnel
  - Reproduire EXACTEMENT le comportement existant
  - Pas de nouvelles features

✅ Phase 2 (après migration) : Nouvelles fonctionnalités
  - Une fois la migration validée et déployée
  - Ajouter les features sur le nouveau système