Développement Java (Java pur)

Conseils au quotidien pour les projets Java qui ne sont pas liés à un framework. Si le projet utilise Spring Boot, Quarkus, Helidon ou similaire, privilégiez les skills du framework pour les préoccupations du framework et utilisez celui-ci pour les parties Java pur.

Règles qui s'appliquent toujours

1. Détectez avant d'écrire. Lisez pom.xml/build.gradle*, .mvn/, gradle/, .java-version/.sdkmanrc, .editorconfig, les fichiers CI et quelques fichiers source. Correspondez à l'outil de build, à la version Java, au formateur, au nommage, aux bibliothèques de logging et de test déjà en usage.
2. Ne mettez jamais à jour implicitement. Ne changez pas la version Java, la version de l'outil de build, les versions de plugin ou de dépendance, et n'ajoutez pas de formateur/linter/analyseur statique que le projet ne possède pas, comme effet secondaire d'une autre tâche. Suggérez-le et demandez. Les mises à niveau de version sont une tâche en soi (java-upgrade, si installé).
3. Utilisez le wrapper (./mvnw, ./gradlew) s'il est présent ; sinon le mvn/gradle installé. Ne commitez pas un wrapper sans y être invité.
4. Vérifiez avec une build. Après tout changement, lancez la vérification propre au projet (./mvnw -B verify ou ./gradlew build) et signalez le résultat. Lancez une commande plus restrictive d'abord lors des itérations. Si vous n'avez pas pu la lancer, dites-le.
5. Demandez à l'utilisateur avant : de changer les API publiques ou les formats sérialisés/DB/wire, d'élever la version Java, d'ajouter des dépendances à l'exécution, d'ajouter des outils à la build, de supprimer ou affaiblir des tests, de changer la CI, ou quand deux conceptions raisonnables ont des compromis différents.
6. Préférez la bibliothèque standard et le code petit et explicite aux nouvelles dépendances. Pas de Lombok sauf s'il est déjà utilisé.

Choisissez les idiomes selon la version Java du projet

Vérifiez maven.compiler.release/<release>, java.toolchain, ou sourceCompatibility ; n'utilisez jamais une fonctionnalité plus récente que cette version. Résumé (détails et extraits dans references/modern-java.md) :

La concurrence structurée (StructuredTaskScope) est toujours une API preview en 25 et 27 (vérifié : nécessite --enable-preview) ; ne l'utilisez pas dans du code production sauf si l'utilisateur accepte les fonctionnalités preview.

Outils de build en pratique

• Maven : ./mvnw -B verify (compile, tests unitaires, tests d'intégration, packaging), -pl <module> -am pour un module, dependency:tree, -DskipTests seulement quand l'utilisateur le demande. Gradle : ./gradlew build, test --tests 'pkg.Class', dependencies, dependencyInsight --dependency <name>.
• Arborescence standard : src/main/java, src/main/resources, src/test/java, src/test/resources ; packager par fonctionnalité, un type top-level par fichier, pas de split packages.
• Définissez explicitement la version Java (maven.compiler.release / Gradle toolchain avec options.release) et l'encodage UTF-8 ; ne vous fiez pas au JDK qui lance la build.
• Wrapper, BOM et usage de dependency:tree/versions:, version catalogs et multi-module layout : references/build-and-dependencies.md.

Dépendances et vulnérabilités

• Importez les BOMs (junit-bom, testcontainers-bom, le BOM du framework) plutôt que de répéter les versions ; une version par bibliothèque dans tous les modules.
• Inspectez avant de changer : mvn dependency:tree -Dincludes=group:artifact / gradlew dependencyInsight. Résolvez les conflits avec dependencyManagement ou les contraintes Gradle, pas en excluant au hasard.
• Vérifiez les mises à jour avec mvn versions:display-dependency-updates (ajoutez -Dmaven.version.ignore pour masquer alpha/beta/RC) et signalez-les ; n'appliquez pas de mises à niveau majeures sans demander.
• Vulnérabilités : utilisez ce que le projet a (alertes Dependabot/Renovate, OWASP dependency-check, OSV-Scanner, GitHub dependency review). Suggérez-en un s'il n'en existe pas ; ne l'ajoutez pas silencieusement. Gardez les secrets hors de la config du scanner ; les scanners basés sur NVD ont besoin d'une clé API pour être pratiques.

Défaillances dépendantes de la version (vérifiées)

• JDK 23+ ne lance plus les annotation processors implicitement (Lombok, MapStruct, Dagger...) : -proc:none est le défaut sauf si -processor, --processor-path ou --processor-module-path est fourni. Déclarez le chemin du processor dans la build (Maven annotationProcessorPaths, Gradle annotationProcessor) ou passez -proc:full. JDK 21+ imprime un avertissement quand il détecte un usage implicite ; -proc:full est aussi backporté à 17.0.11, 11.0.23 et 8u411. Source : https://inside.java/2024/06/18/quality-heads-up/.
• Virtual threads et synchronized : sur JDK 21-23 un virtual thread qui bloque à l'intérieur de synchronized est épinglé à son carrier ; JEP 491 supprime presque tout ce pinning dans JDK 24+. Sur 21-23 préférez ReentrantLock autour des appels bloquants. Source : https://openjdk.org/jeps/491.
• Error Prone sur JDK 16+ a besoin des flags javac --add-exports/--add-opens, et sur JDK 21 -XDaddTypeAnnotationsToSymbol=true (voir la référence quality).
• N'utilisez jamais une fonctionnalité du langage plus récente que la version du projet (voir le tableau ci-dessus).

Analyse statique et formatage (seulement si déjà présent, ou si l'utilisateur accepte)

Respectez ce qui est configuré : si le projet utilise Spotless/Checkstyle/SpotBugs/Error Prone, lancez-les et corrigez les trouvailles ; sinon, ne les ajoutez pas. Quand on vous demande de les introduire, commencez par -Xlint:all et Spotless (formateur uniquement), puis Error Prone. Les configs vérifiées pour Maven et Gradle sur JDK 21 et 25 (incluant l'exigence -XDaddTypeAnnotationsToSymbol=true pour JDK 21 uniquement et les flags .mvn/jvm.config de Maven) sont dans references/quality-and-packaging.md. Ne reformatez jamais la base de code entière dans un changement sans lien.

Packaging et CI

• Bibliothèque jar simple : mvn package/gradlew jar. App exécutable : shaded/fat jar ou répertoire lib/ plus manifest Main-Class ; runtime personnalisé avec jlink ; installateur natif/app-image avec jpackage (vérifié sur macOS, voir references/quality-and-packaging.md).
• GitHub Actions : actions/checkout, actions/setup-java avec distribution: temurin, une java-version explicite, cache dépendance intégrée, puis ./mvnw -B verify ou ./gradlew build. Extrait et notes dans references/quality-and-packaging.md. Ne changez pas la CI sans demander.

Skills connexes (utilisez quand installés)

java-junit (tests unitaires), java-testcontainers (tests d'intégration avec Docker), java-hibernate-jpa (persistance), java-debugging (défaillances et stack traces), java-diagnostics (performance, mémoire, threads, JFR), java-upgrade (mises à niveau JDK/framework), lsp-setup (serveur de langage Java pour navigation et refactoring).

Références

• references/modern-java.md : idiomes et extraits vérifiés (records, types sealed, switch patterns, text blocks, virtual threads, SequencedCollection, variables anonymes), statut preview, pièges.
• references/build-and-dependencies.md : commandes Maven/Gradle, wrappers, BOMs, diagnostic de conflit, vérification de mise à jour, Dependabot/Renovate, scan de vulnérabilités.
• references/quality-and-packaging.md : setup de logging, -Xlint, Spotless, Error Prone, notes Checkstyle/SpotBugs, jar/jlink/jpackage, GitHub Actions.