Utiliser JFoundry
Objectif
Utilisez cette compétence pour construire des applications métier sur JFoundry sans dériver de l'architecture prévue par le framework. Elle est destinée aux projets applicatifs, et non à la modification des composants internes de JFoundry.
Par défaut, créez un nouveau projet Maven Java 21 avec architecture hexagonale, sauf si l'utilisateur choisit explicitement l'architecture en oignon. Ne définissez pas Spring Boot comme framework d'exécution par défaut ; choisissez Spring uniquement lorsque l'utilisateur sélectionne Spring Framework, Spring Boot ou un starter spécifique à Spring. Préférez copier d'abord les modèles fournis, puis adapter les noms et les packages.
Workflow de première utilisation
- Identifiez la forme du projet : module applicatif unique, application Maven multi-module, ou modules séparés domaine/application/infrastructure. Préférez le multi-module Maven pour les projets DDD classiques.
- Choisissez un style architectural principal. Préférez l'architecture hexagonale pour les nouveaux projets métier ; choisissez l'architecture en oignon uniquement lorsque l'utilisateur la demande ou que le code existant l'utilise déjà. Ne mélangez pas hexagonale et oignon dans la même portée d'analyse ArchUnit.
- Lisez
references/dependencies.md, choisissez le BOM en fonction de l'exécution, et copiez les extraits de modèles Maven correspondants depuisassets/templates/maven/. - Lisez
references/architecture.mdet copiez la structure de package correspondante depuisassets/templates/structure/. - Copiez un modèle de test d'architecture depuis
assets/templates/java/, remplacezPACKAGE_NAME, et ajoutez-le dans le répertoire de test du projet métier. - Lisez
references/repository-and-ports.mdavant de créer des repositories d'agrégats, des ports de lecture, des ports de requête, des ports de consultation, des modèles de lecture ou des ports de maintenance. - Lisez
references/persistence-data-converters.mdavant d'implémenterAggregateData,DataConverter, des objets de données MyBatis-Plus ou des convertisseurs MapStruct. - Lisez
references/outbox-inbox.mduniquement lorsque le projet nécessite une publication fiable d'événements externes ou une consommation de messages idempotente. - Exécutez la commande de vérification Maven la plus pertinente, généralement
mvn test, ou une commande limitée à un module commemvn -pl <module> test.
Règles principales
- Maintenez le code du domaine libre de Spring, MyBatis, modèles de persistance, clients de courtiers de messages et API de cycle de vie du framework.
- Modélisez le comportement métier dans le domaine lorsque les règles et les invariants sont significatifs ; utilisez des scripts CRUD ou de transaction plus simples pour les zones de faible complexité.
- Pour un comportement domaine non trivial, confirmez les hypothèses concernant l'agrégat, la commande, l'invariant, l'événement, le repository et le port de lecture avant de coder ; gardez les questions ouvertes sur le domaine visibles.
- Placez les starters Spring Boot uniquement dans le module d'assemblage boot/exécution, jamais dans les modules domaine ou application.
- Placez l'orchestration des cas d'utilisation et le workflow transactionnel dans la couche application.
- Exprimez les besoins sortants comme des ports secondaires. Placez MyBatis, JPA, Redis, les clients HTTP, les clients MQ et autres détails technologiques dans les adaptateurs d'infrastructure.
- Dans les projets JFoundry hexagonaux ou en oignon, les adaptateurs primaires (contrôleurs, écouteurs de messages, commandes CLI, planificateurs) doivent appeler des ports primaires ou des services d'application, pas directement les adaptateurs secondaires.
- Utilisez les repositories d'agrégats pour le cycle de vie des agrégats et le chargement des agrégats côté commande. Pour les lectures non basées sur des agrégats, préférez les ports de lecture et répartissez-les en rôles lookup/read-model/maintenance uniquement lorsque cette distinction est utile au projet.
- Gardez les convertisseurs de données de persistance locaux à l'infrastructure. Privilégiez les interfaces
@MapperMapStruct avecINSTANCE; gardeztoEntity(...)explicite et appelezrestore(...)sur l'agrégat. - Activez l'Outbox uniquement pour une publication fiable vers un processus ou un courtier externe. Utilisez la distribution d'événements domaine locale lorsque les événements restent dans le même processus.
- Activez l'Inbox uniquement lorsqu'un consommateur doit gérer les doublons de manière sécurisée.
- Ajoutez les tests ArchUnit tôt. Ils font partie du squelette du projet, pas d'un nettoyage tardif.
Modèles fournis
Copiez les modèles plutôt que de les réécrire de mémoire :
assets/templates/java/HexagonalArchitectureTest.javaassets/templates/java/OnionSimpleArchitectureTest.javaassets/templates/maven/dependency-management-core.xmlassets/templates/maven/dependency-management-spring.xmlassets/templates/maven/domain-module-dependencies.xmlassets/templates/maven/application-module-dependencies.xmlassets/templates/maven/infrastructure-mybatis-plus-dependencies.xmlassets/templates/maven/architecture-test-dependencies.xmlassets/templates/maven/spring-boot-app-dependencies.xmlassets/templates/maven/spring-boot-mybatis-plus-dependencies.xmlassets/templates/maven/outbox-dependencies.xmlassets/templates/maven/outbox-mybatis-plus-dependencies.xmlassets/templates/maven/inbox-dependencies.xmlassets/templates/maven/inbox-mybatis-plus-dependencies.xmlassets/templates/maven/broker-dependencies.xmlassets/templates/structure/hexagonal-package-structure.txtassets/templates/structure/onion-simple-package-structure.txt
Remplacez les espaces réservés tels que PACKAGE_NAME et JFOUNDRY_VERSION. Gardez les extraits optionnels optionnels ; n'ajoutez pas les starters Outbox, Inbox, MyBatis-Plus ou courtier sauf si le cas d'utilisation le nécessite.
Acheminement des références
- Lisez
references/first-use.mdlorsque l'utilisateur démarre un nouveau projet ou demande comment invoquer cette compétence. - Lisez
references/architecture.mdpour les rôles des packages, les annotations, la direction des dépendances et la sélection du style architectural. - Lisez
references/dependencies.mdpour la sélection des starters et les extraits Maven. - Lisez
references/repository-and-ports.mdavant de modéliser la persistance, les repositories d'agrégats, les modèles de lecture ou les ports de requête. - Lisez
references/persistence-data-converters.mdavant d'écrire des implémentationsDataConverter, des objets de données de persistance ou des règles de correspondance MapStruct. - Lisez
references/outbox-inbox.mdavant d'ajouter l'externalisation d'événements, les adaptateurs de courtier, les tables Outbox, les répartiteurs ou l'idempotence des consommateurs. - Lisez
references/testing.mdavant d'ajouter ou de modifier des tests d'architecture.
Prompt initial courant
Lorsque vous guidez un nouveau projet, commencez par demander le package de base, la forme du projet/module, la pile d'exécution, le choix de persistance et si une messagerie externe est nécessaire. Si l'utilisateur n'a pas de préférence, poursuivez avec :
- Java 21
- Maven
- aucun framework d'exécution pour l'instant
- architecture hexagonale
- BOM
jfoundry-dependencies - starter
jfoundry-domain-starter - starter
jfoundry-application-starter JFoundryRules.hexagonalStrict()etJFoundryRules.jmoleculesDdd()
Exemple de saisie utilisateur pour un nouveau projet métier :
Utilisez $use-jfoundry pour créer l'architecture initiale d'un nouveau projet Java 21.
Package de base : com.example.order
Forme du projet : multi-module Maven
Exécution : non décidée
Persistance : MyBatis-Plus
Messagerie : Kafka plus tard, pas dans le squelette initial
Architecture : par défaut sauf si vous devez choisir
Si des détails manquent, posez une question concise ou suivez les valeurs par défaut ci-dessus lorsque le choix présente un faible risque.