Introduction à l’Architecture Hexagonale

L’architecture hexagonale, également connue sous le nom de Ports & Adapters, est un pattern architectural créé par Alistair Cockburn en 2005.

Ce guide vous expliquera pourquoi et comment utiliser l’architecture hexagonale avec Micronaut.

Pourquoi “Hexagonale” ?

Le nom vient de la représentation visuelle avec un hexagone au centre (le domain) et des ports sur chaque face, permettant de connecter différents adapters.


          ┌─────────────────────────┐
          │      Web UI             │
          │     (Adapter)           │
          └───────────┬─────────────┘
                      │
           ┌──────────▼──────────┐
           │      Port IN        │
           │   (Interface)       │
           ├─────────────────────┤
           │                     │          ┌──────────────────┐
           │       DOMAIN        │◄─────────┤   Port OUT       │
           │   (Business Logic)  │          │  (Interface)     │
           │                     │          └────────┬─────────┘
           └─────────────────────┘                   │
                                             ┌───────▼──────────┐
                                             │    Database      │
                                             │    (Adapter)     │
                                             └──────────────────┘

Le nombre de côtés n’a aucune importance ! L’idée clé est que le cœur métier (domain) est isolé et ne dépend de rien.

Problème Résolu

Pourquoi l’architecture hexagonale existe-t-elle ? Quel problème résout-elle ?

❌ Architecture Traditionnelle

Le Problème : Couplage Fort


// ❌ Problème : couplage fort
public class UserController {
    private UserService service = new UserService();
    // Controller dépend directement du Service
}
 
public class UserService {
    private MySQLUserRepository repository = new MySQLUserRepository();
    // Service dépend directement de MySQL
    // Impossible de tester sans BDD réelle !
}

Problèmes majeurs :

❌ Impossible de changer de BDD sans casser le code
❌ Tests difficiles (besoin d’une vraie BDD)
❌ Le code métier dépend du framework
❌ Couplage fort entre les couches
❌ Difficile de remplacer une dépendance

Les 3 Couches

L’architecture hexagonale s’organise en 3 couches concentriques avec le domain au centre.

1. Domain

Domain (Cœur Métier)

C’est le centre de l’application. Il contient :

Entités : Les objets métier (User, Order, Product)
Value Objects : Objets immuables (Email, Address)
Ports de sortie : Interfaces définissant les besoins (UserRepository)
Règles métier : Logique pure (calculs, validations)


// domain/model/User.java
@Value
public class User {
    Long id;
    String name;
    Email email;
 
    public boolean isActive() {
        return email != null;
    }
}
 
// domain/port/output/UserRepository.java
public interface UserRepository {
    Optional<User> findById(Long id);
    void save(User user);
}

Règle d’or : Le domain ne dépend de RIEN (pas de framework, pas de BDD, pas d’API).

2. Application

Application (Orchestration)

Contient les Use Cases qui orchestrent la logique métier.


// application/usecase/GetUserUseCase.java
@Singleton
@RequiredArgsConstructor
public class GetUserUseCase {
    private final UserRepository userRepository; // Interface du domain
 
    public Optional<User> execute(Long id) {
        // Orchestration simple
        return userRepository.findById(id);
    }
}

Rôle :

Orchestrer plusieurs entités du domain
Coordonner les appels aux ports de sortie
Gérer les transactions
Pas de logique métier (c’est dans le domain)

3. Infrastructure

Infrastructure (Technique)

Contient les Adapters qui implémentent les détails techniques.

Adapters d’entrée (Input) :


// application/port/input/UserController.java
@Controller("/api/users")
@RequiredArgsConstructor
public class UserController {
    private final GetUserUseCase getUserUseCase;
 
    @Get("/{id}")
    public UserDto getUser(Long id) {
        return getUserUseCase.execute(id)
            .map(UserDto::fromDomain)
            .orElseThrow(() -> new NotFoundException());
    }
}

Adapters de sortie (Output) :


// infrastructure/adapter/MySQLUserRepository.java
@Singleton
public class MySQLUserRepository implements UserRepository {
    @Override
    public Optional<User> findById(Long id) {
        // SELECT * FROM users WHERE id = ?
        // Mapper Entity JPA → Domain
    }
}

Principe d’Inversion de Dépendances

C’est le cœur de l’architecture hexagonale : inverser les dépendances pour découpler le code.

❌ Dépendances Traditionnelles

Le Problème


┌──────────────┐
│  Controller  │
└──────┬───────┘
       │ depends on
       ▼
┌──────────────┐
│   Service    │
└──────┬───────┘
       │ depends on
       ▼
┌──────────────┐
│  Repository  │  ← Implémentation concrète
└──────────────┘

Problème : Le haut dépend du bas → couplage fort.

Controller dépend de Service
Service dépend de Repository concret
Impossible de changer Repository sans casser Service
Impossible de tester Service sans Repository réel

Bénéfices

1. Indépendance

Indépendance du Framework

Le domain ne connaît pas Micronaut, Spring, Jakarta, etc.

✅ Bon


// ✅ Domain pur
@Value  // Lombok uniquement
public class User {
    Long id;
    String name;
    Email email;
}

Avantage : Aucune dépendance framework !

2. Testabilité

Testabilité Maximale


@Test
void shouldFindUser() {
    // ARRANGE - Mock du port
    UserRepository mockRepo = mock(UserRepository.class);
    User alice = new User(1L, "Alice", new Email("alice@test.com"));
 
    when(mockRepo.findById(1L))
        .thenReturn(Optional.of(alice));
 
    GetUserUseCase useCase = new GetUserUseCase(mockRepo);
 
    // ACT
    Optional<User> user = useCase.execute(1L);
 
    // ASSERT
    assertThat(user).isPresent();
    assertThat(user.get().getName()).isEqualTo("Alice");
}

Pas besoin de base de données réelle ! Les tests sont ultra rapides 🚀

3. Flexibilité

Flexibilité

Tu peux remplacer un adapter sans toucher au domain.


// Avant : MySQL
@Singleton
@Requires(env = "dev")
public class MySQLUserRepository implements UserRepository {
    // Implémentation MySQL
}
 
// Après : PostgreSQL
@Singleton
@Requires(env = "prod")
public class PostgresUserRepository implements UserRepository {
    // Implémentation PostgreSQL
}
 
// LE DOMAIN NE CHANGE PAS !

Change de BDD, d’API, de cache en production sans toucher à la logique métier !

Couche	Responsabilité	Équipe
Domain	Règles métier	Business Analysts + Devs
Application	Orchestration	Devs Backend
Infrastructure	Détails techniques	Devs Backend + DevOps

Comparaison : Architecture en Couches vs Hexagonale

Critère	Architecture en Couches	Architecture Hexagonale
Dépendances	Haut → Bas (couplage)	Tout → Domain (inversion)
Testabilité	Difficile (besoin BDD/API réelles)	Facile (mock des interfaces)
Flexibilité	Difficile de changer de techno	Facile (juste changer l’adapter)
Complexité initiale	Simple	Plus de fichiers/interfaces
Maintenabilité long terme	Difficile (code couplé)	Excellente (séparation claire)
Indépendance framework	Non (code lié au framework)	Oui (domain pur)

Quand L’Utiliser ?

✅ Utiliser Si…

✅ Utilise l’architecture hexagonale si :

✅ Ton application a une logique métier complexe
✅ Tu veux changer de technologie facilement (BDD, API, framework)
✅ Tu veux des tests rapides et fiables
✅ L’application va évoluer sur plusieurs années
✅ Plusieurs équipes travaillent sur le projet
✅ Tu veux isoler la logique métier du framework
✅ Le domain a des règles complexes

Exemples: E-commerce, Banking, Healthcare, Réservation complexe, SaaS multi-tenant

Résumé

L’architecture hexagonale protège votre logique métier en l’isolant de l’infrastructure technique.

Principe	Description
Domain au centre	Le cœur métier est pur et indépendant
Inversion de dépendances	L’infrastructure dépend du domain
Ports	Interfaces définissant les contrats
Adapters	Implémentations techniques des ports
Testabilité	Tests rapides sans infrastructure réelle

Prochaines Étapes

Maintenant que vous comprenez les principes, explorez comment les appliquer avec Micronaut.

Concepts Micronaut → - IoC, Beans, Dependency Injection
Annotations Guide → - Lombok + Micronaut en détail
Ports & Adapters → - Pattern détaillé avec exemples