Architecture Hexagonale avec Micronaut

Documentation complète pour maîtriser l’architecture hexagonale (Ports & Adapters) avec Micronaut Framework.

Cette documentation vous guide pas à pas pour créer des applications robustes, testables et maintenables avec Micronaut.

Qu’est-ce que l’architecture hexagonale ?

L’architecture hexagonale (aussi appelée Ports & Adapters) est un pattern architectural qui permet de créer des applications :

Indépendantes du framework - Le cœur métier ne dépend d’aucune technologie
Facilement testables - Isolation totale entre les couches
Flexibles - Remplacer une base de données ou une API sans toucher au code métier
Maintenables - Séparation claire des responsabilités

Principe fondamental


┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│    REST     │──────→  │    DOMAIN    │  ←──────│   Database  │
│  (Adapter)  │         │    (Core)    │         │  (Adapter)  │
└─────────────┘         └──────────────┘         └─────────────┘
     Input                    Pure                    Output
     Port                   Business                   Port
                             Logic

Le domain est au centre et ne dépend de RIEN. Tout le reste dépend du domain.

Pourquoi cette documentation ?

Cette documentation a été créée pour tous les niveaux : débutants, développeurs confirmés et architectes.

Développeurs Débutants

Pour les Développeurs Débutants

Apprendre l’architecture hexagonale pas à pas avec des exemples concrets.

Concepts de base expliqués simplement
Exemples progressifs du simple au complexe
Tutoriels guidés avec des Steps
FAQ et pièges courants

Développeurs Micronaut

Pour les Développeurs Micronaut

Maîtriser les patterns avancés avec Micronaut Framework.

Injection de dépendances avec @Singleton
Annotations Lombok et Micronaut
Tests avec @MicronautTest
Optimisations et performance

Parcours recommandés

Choisissez votre parcours selon votre niveau et vos objectifs.

🚀 Je débute

Je débute avec l’architecture hexagonale

Comprendre les bases

Introduction - Qu’est-ce que l’architecture hexagonale ?

Maîtriser Micronaut

Concepts Micronaut - IoC, Beans, Dependency Injection

Comprendre le pattern

Ports & Adapters - Le pattern en détail

Créer vos premiers ports

Guide des Ports - Créer des ports Input/Output

Garantir la conformité

Tests d’Architecture - Garantir la conformité avec ArchUnit

Sections principales

1. Fondamentaux

1. Fondamentaux

Les bases de l’architecture hexagonale et des concepts Micronaut.

- introduction.mdx
- micronaut-concepts.mdx
- annotations.mdx
- ports-and-adapters.mdx

Contenus :

Introduction - Qu’est-ce que l’architecture hexagonale ?
Concepts Micronaut - IoC, Beans, DI, AOT
Annotations - Guide complet Lombok + Micronaut
Ports & Adapters - Pattern en profondeur

Exemple rapide

Voici comment créer un endpoint complet avec l’architecture hexagonale en 4 étapes.

1. Domain

1. Domain (cœur métier)

Le domain contient les entités et les interfaces (ports de sortie).

domain/model/Trend.java


@Value
public class Trend {
    String keyword;
    Integer score;
}

domain/port/output/TrendRepository.java


public interface TrendRepository {
    Optional<Trend> findByKeyword(String keyword);
}

Le domain ne dépend de RIEN - pas de framework, pas de BDD, pas d’API.

2. Application

2. Application (use cases)

Les use cases orchestrent la logique métier.

application/usecase/GetTrendUseCase.java


@Singleton
@RequiredArgsConstructor
public class GetTrendUseCase {
    private final TrendRepository trendRepository;
 
    public Optional<Trend> execute(String keyword) {
        return trendRepository.findByKeyword(keyword);
    }
}

application/port/input/TrendController.java


@Controller("/api/trends")
@RequiredArgsConstructor
public class TrendController {
    private final GetTrendUseCase getTrendUseCase;
 
    @Get("/{keyword}")
    public Trend getTrend(String keyword) {
        return getTrendUseCase.execute(keyword)
            .orElseThrow(() -> new NotFoundException());
    }
}

3. Infrastructure

3. Infrastructure (adapters)

L’infrastructure implémente les ports avec des adapters concrets.

infrastructure/adapter/MockTrendRepositoryAdapter.java


@Singleton
public class MockTrendRepositoryAdapter implements TrendRepository {
    @Override
    public Optional<Trend> findByKeyword(String keyword) {
        // Mock simple - retourne toujours un score de 85
        return Optional.of(new Trend(keyword, 85));
    }
}

Facile de remplacer le mock par un vrai adapter MySQL ou Redis !

4. Test

4. Test

Tester le use case sans infrastructure réelle.


@Test
void shouldGetTrendWhenKeywordExists() {
    // ARRANGE - Mock du repository
    TrendRepository mockRepo = mock(TrendRepository.class);
    Trend javaTrend = new Trend("java", 92);
 
    when(mockRepo.findByKeyword("java"))
        .thenReturn(Optional.of(javaTrend));
 
    GetTrendUseCase useCase = new GetTrendUseCase(mockRepo);
 
    // ACT
    Optional<Trend> result = useCase.execute("java");
 
    // ASSERT
    assertThat(result).isPresent();
    assertThat(result.get().getScore()).isEqualTo(92);
}

Tests ultra rapides sans base de données réelle !

Résultat : Le domain est pur, l’infrastructure est remplaçable, tout est testable.

Technologies

Stack technique recommandée pour l’architecture hexagonale avec Micronaut.

Technologie	Usage	Pourquoi ?
Micronaut 4.x	Framework principal	Moderne, rapide, AOT compilation
Lombok	Réduction boilerplate	Génère getters, constructeurs, etc.
Jackson	Sérialisation JSON	Standard pour APIs REST
JUnit 5	Tests unitaires	Framework de test moderne
AssertJ	Assertions	Assertions fluides et lisibles
ArchUnit	Tests architecture	Garantir conformité hexagonale
Mockito	Mocking	Isoler les dépendances dans les tests

Commencer maintenant

Prêt à maîtriser l’architecture hexagonale ? Choisis ton parcours et plonge dans la documentation !

Débutant

Parcours Débutant

Comprendre les bases

Introduction - Comprendre les bases

Découvrir Micronaut

Concepts Micronaut - IoC, Beans, DI

Créer ton premier port

Créer ton premier port

Architecture Hexagonale avec Micronaut

Qu’est-ce que l’architecture hexagonale ?

Principe fondamental

Pourquoi cette documentation ?

Développeurs Débutants

Développeurs Micronaut

Architectes

Équipes

Parcours recommandés

🚀 Je débute

💪 Je maîtrise le concept

🔄 Migration d’un projet

Sections principales

1. Fondamentaux

2. Architecture

3. Mise en Pratique

4. Tests

5. Bonnes Pratiques

6. Avancé