Tutoriel

Démarrage rapide.
5 minutes pour comprendre.

Configurez HexaGlue, générez votre première documentation vivante, et découvrez comment l'audit protège votre architecture.

Cloner hexaglue-demo Voir les étapes

Prérequis

Java 17+
Maven 3.8+
Un IDE
Le parcours

5 étapes pour maîtriser HexaGlue

Suivez ce tutoriel avec l'application hexaglue-demo pour une expérience pratique.

1

Cloner le projet de démonstration

Commencez par cloner l'application de démonstration qui contient un domaine métier prêt à l'emploi.

git clone https://github.com/hexaglue/hexaglue-demo.git
cd hexaglue-demo
2

Activer la Living Documentation

Décommentez le plugin HexaGlue et hexaglue-plugin-living-doc dans le pom.xml, puis compilez.

mvn clean compile

Résultat attendu

[INFO] --- hexaglue:6.1.1:generate (default-hexaglue-generate) @ hexaglue-demo ---
[INFO] HexaGlue analyzing: io.hexaglue.demo
.../...
[INFO] Executing plugin: io.hexaglue.plugin.livingdoc
[INFO] [io.hexaglue.plugin.livingdoc] Generating living documentation in: living-doc
[INFO] [io.hexaglue.plugin.livingdoc] Generated architecture overview
[INFO] [io.hexaglue.plugin.livingdoc] Generated domain model documentation
[INFO] [io.hexaglue.plugin.livingdoc] Generated ports documentation
[INFO] [io.hexaglue.plugin.livingdoc] Generated architecture diagrams
[INFO] [io.hexaglue.plugin.livingdoc] Living documentation complete: 0 aggregate roots, 1 entities, 1 value objects, 1 driving ports, 1 driven ports
[INFO] [io.hexaglue.plugin.livingdoc] Additional types: 1 identifiers, 0 domain events, 0 domain services
[WARNING] [io.hexaglue.plugin.livingdoc] Classification quality: 85,7% (1 types may need review)
[INFO] Plugin io.hexaglue.plugin.livingdoc completed in 20ms, generated 4 files
.../...
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Consultez les fichiers Markdown générés dans target/hexaglue/reports/living-doc/ : README.md, domain.md, ports.md et diagrams.md.

3

Activer l'Audit. Le build échoue !

Décommentez hexaglue-plugin-audit dans le pom.xml. L'audit va détecter une violation architecturale dans Task.java.

Commande

mvn clean verify -DskipTests

L'option -DskipTests est nécessaire car les tests échoueraient. l'infrastructure JPA n'est pas encore générée.

Résultat attendu

[INFO] --- hexaglue:6.1.1:audit (default-hexaglue-audit) @ hexaglue-demo ---
[INFO] HexaGlue auditing: io.hexaglue.demo
.../...
[INFO] Executing plugin: io.hexaglue.plugin.audit
[INFO] [io.hexaglue.plugin.audit] Audit complete: 2 violations, 20 metrics
[INFO] [io.hexaglue.plugin.audit]
======================================================================
  HEXAGLUE ARCHITECTURE AUDIT REPORT
======================================================================


  Score:  76/100  |  Grade: C  |  Status: FAILED


  Your application has critical issues that should be addressed.


----------------------------------------------------------------------
  ISSUES
----------------------------------------------------------------------


  Total: 2 issue(s)


    █ CRITICAL: 1
    █ MAJOR:    1


    [CRITICAL]  Domain purity violation
    [MAJOR]     Driven port without adapter


----------------------------------------------------------------------


[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] AUDIT SUMMARY
[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] Total Violations: 2
[INFO]   Errors:   1
[INFO]   Warnings: 1
[INFO] Status: FAILED
[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
[ERROR] Audit failed with 1 error-level violations (BLOCKER/CRITICAL)

Le rapport d'audit est généré dans target/hexaglue/reports/audit/ en 3 formats : audit-report.json, AUDIT-REPORT.md et audit-report.html.

4

Corriger la violation

Le domaine ne doit pas dépendre de l'infrastructure. Corrigez Task.java pour respecter ce principe.

Modifications à effectuer

  • Supprimez l'annotation @Entity sur la classe
  • Supprimez l'import jakarta.persistence.Entity

Commande

mvn clean verify -DskipTests

Résultat attendu

[INFO] --- hexaglue:6.1.1:audit (default-hexaglue-audit) @ hexaglue-demo ---
[INFO] HexaGlue auditing: io.hexaglue.demo
.../...
[INFO] Executing plugin: io.hexaglue.plugin.audit
[INFO] [io.hexaglue.plugin.audit] Audit complete: 1 violations, 20 metrics
[INFO] [io.hexaglue.plugin.audit]
======================================================================
  HEXAGLUE ARCHITECTURE AUDIT REPORT
======================================================================


  Score:  77/100  |  Grade: C  |  Status: PASSED (with warnings)


  Your application is generally healthy but has some issues that should be reviewed.


----------------------------------------------------------------------
  ISSUES
----------------------------------------------------------------------


  Total: 1 issue(s)


    █ MAJOR:    1


    [MAJOR]     Driven port without adapter


----------------------------------------------------------------------


[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] AUDIT SUMMARY
[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] Total Violations: 1
[INFO]   Errors:   0
[INFO]   Warnings: 1
[INFO] Status: PASSED
[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] Audit completed: PASSED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
5

Générer l'infrastructure

Décommentez hexaglue-plugin-jpa et hexaglue-plugin-rest dans le pom.xml. Les sources générées sont ajoutées automatiquement au classpath grâce à <extensions>true</extensions>.

Commande

mvn clean verify

Résultat attendu

[INFO] --- hexaglue:6.1.1:generate (default-hexaglue-generate) @ hexaglue-demo ---
[INFO] HexaGlue analyzing: io.hexaglue.demo
.../...
[INFO] Executing plugin: io.hexaglue.plugin.rest
[INFO] [io.hexaglue.plugin.rest] REST plugin generated @Configuration class with 1 @Bean method(s).
[INFO] [io.hexaglue.plugin.rest] REST plugin generated 1 controller(s) and 2 DTO(s).
[INFO] Plugin io.hexaglue.plugin.rest completed in 19ms, generated 5 files
.../...
[INFO] Executing plugin: io.hexaglue.plugin.jpa
[INFO] [io.hexaglue.plugin.jpa] Generated entity: TaskEntity
[INFO] [io.hexaglue.plugin.jpa] Generated repository: TaskJpaRepository
[INFO] [io.hexaglue.plugin.jpa] Generated mapper: TaskMapper
[INFO] [io.hexaglue.plugin.jpa] Generated adapter: TaskRepositoryAdapter implementing TaskRepository
[INFO] [io.hexaglue.plugin.jpa] JPA generation complete: 1 entities, 0 embeddables, 1 repositories, 1 mappers, 1 adapters
[INFO] Plugin io.hexaglue.plugin.jpa completed in 16ms, generated 4 files
[INFO] Plugins executed: 3 plugins, 13 files generated
.../...
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped: 0
.../...
[INFO] --- hexaglue:6.1.1:audit (default-hexaglue-audit) @ hexaglue-demo ---
.../...
[INFO] [io.hexaglue.plugin.audit] Audit complete: 0 violations, 20 metrics
[INFO] [io.hexaglue.plugin.audit]
======================================================================
  HEXAGLUE ARCHITECTURE AUDIT REPORT
======================================================================


  Score:  71/100  |  Grade: C  |  Status: PASSED


  Congratulations! Your application follows all architectural best practices.


----------------------------------------------------------------------
  ISSUES
----------------------------------------------------------------------


  ✓ No issues detected!


----------------------------------------------------------------------


[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] AUDIT SUMMARY
[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] Total Violations: 0
[INFO] Status: PASSED
[INFO] ────────────────────────────────────────────────────────────────────────────────
[INFO] Audit completed: PASSED
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------

Ordre d'exécution des plugins

HexaGlue exécute les plugins dans un ordre précis selon leur catégorie :

  1. Générateurs (phase generate-sources) : living-doc, jpa puis rest génèrent le code
  2. Compilation : Maven compile les sources générées avec MapStruct
  3. Tests : Spring Boot démarre avec l'infrastructure générée
  4. Audit (phase verify) : audit valide l'architecture finale

Cette séparation garantit que l'audit valide le code après génération et que les tests utilisent l'infrastructure complète.

Configuration

Le plugin Maven

Déclarez le plugin HexaGlue puis ajoutez en dépendance uniquement les plugins qui correspondent à vos besoins. Toutes les dépendances transitoires (MapStruct, Jakarta Persistence) sont configurées automatiquement.

pom.xml
<!-- HexaGlue Maven Plugin (dans <build><plugins>) -->
<plugin>
    <groupId>io.hexaglue</groupId>
    <artifactId>hexaglue-maven-plugin</artifactId>
    <version>6.1.1</version>
    <extensions>true</extensions>
    <configuration>
        <basePackage>io.hexaglue.demo</basePackage>
    </configuration>
    <dependencies>
        <!-- Ajoutez uniquement les plugins dont vous avez besoin -->


        <!-- Documentation vivante auto-générée -->
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-living-doc</artifactId>
            <version>3.1.1</version>
        </dependency>


        <!-- Audit de conformité DDD / Architecture Hexagonale -->
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-audit</artifactId>
            <version>3.1.1</version>
        </dependency>


        <!-- Génération JPA (entities, repositories, mappers) -->
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-jpa</artifactId>
            <version>3.1.1</version>
        </dependency>


        <!-- Génération REST (controllers, DTOs, configuration, exception handler) -->
        <dependency>
            <groupId>io.hexaglue.plugins</groupId>
            <artifactId>hexaglue-plugin-rest</artifactId>
            <version>3.1.1</version>
        </dependency>
    </dependencies>
</plugin>
Récapitulatif

Ce que vous avez découvert

Living Documentation

Documentation générée automatiquement, toujours synchronisée avec votre code.

Audit d'architecture

Détection des violations architecturales dès la compilation.

Génération de code

Infrastructure JPA et controllers REST générés depuis vos ports driving et driven.

Classification automatique

HexaGlue identifie agrégats, value objects, ports sans configuration.

Le tutoriel est terminé.
Votre architecture ne fait que commencer.

Explorez les exemples avancés ou contactez-nous pour un accompagnement sur mesure.

Explorer une étude de cas Se faire accompagner