Dépendances Maven et portées

Les vrais projets Java ne sont presque jamais autonomes. Ils font appel à des frameworks de journalisation, des clients HTTP, des parseurs JSON et des bibliothèques de test écrits par d'autres. Le rôle de Maven est de récupérer ces bibliothèques, de récupérer leurs bibliothèques à leur tour, et d'assembler un classpath cohérent sans que vous ayez à gérer un seul JAR manuellement. Comprendre comment il procède fait la différence entre un build qui fonctionne et un après-midi perdu à cause d'un NoSuchMethodError.

Ce chapitre explique comment une dépendance est nommée (coordonnées), comment les portées contrôlent la visibilité de chaque bibliothèque, comment Maven parcourt le graphe des dépendances transitives, et comment il résout les conflits de version. Il suppose que vous disposez déjà d'un pom.xml ; sinon, commencez par le chapitre Maven POM.

Coordonnées : Comment une dépendance est nommée

Chaque artifact dans l'univers Maven est identifié par un ensemble de coordonnées. Les trois que vous devez toujours fournir sont le groupId (l'éditeur, généralement un domaine inversé), l'artifactId (le nom du projet) et la version. Ensemble, ils pointent vers un seul JAR dans un dépôt.

Vous déclarez une dépendance dans le bloc <dependencies> de votre pom.xml :

<dependencies>
  <dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-lang3</artifactId>
    <version>3.14.0</version>
  </dependency>
</dependencies>

Le raccourci groupId:artifactId:version est appelé une chaîne GAV, et vous la rencontrerez partout : dans les messages d'erreur, dans l'arbre de dépendances, et sur les pages web du dépôt central. Une quatrième coordonnée, le type (jar par défaut), et une cinquième, le classifier (pour les variantes comme sources ou javadoc), complètent l'adresse complète.

Portées : Quand une dépendance est visible

Toutes les dépendances n'ont pas leur place sur chaque classpath. Un framework de test ne doit pas être embarqué dans votre JAR de production, et une API de servlet fournie par le serveur d'application ne doit pas être incluse deux fois. Maven contrôle cela avec l'élément <scope>.

Portée	Compilation	Test	Exécution	Packagé	Utilisation typique
`compile` (défaut)	Oui	Oui	Oui	Oui	Bibliothèques principales que vous appelez directement
`provided`	Oui	Oui	Non	Non	APIs fournies par le conteneur (servlet, pilote JDBC)
`runtime`	Non	Oui	Oui	Oui	Implémentations nécessaires uniquement à l'exécution
`test`	Non	Oui	Non	Non	JUnit, Mockito, bibliothèques d'assertion
`system`	Oui	Oui	Non	Non	JARs locaux par chemin absolu (à éviter)

Une dépendance de portée test est la plus courante en dehors du défaut. JUnit ne se retrouve jamais dans votre artifact livré :

<dependency>
  <groupId>org.junit.jupiter</groupId>
  <artifactId>junit-jupiter</artifactId>
  <version>5.11.0</version>
  <scope>test</scope>
</dependency>

Dépendances transitives

Lorsque vous dépendez d'une bibliothèque, vous dépendez également de tout ce dont elle dépend. Maven lit le pom.xml publié de chaque artifact, suit ces déclarations de manière récursive, et ajoute automatiquement l'ensemble du graphe à votre classpath. Ces entrées indirectes sont des dépendances transitives.

C'est pourquoi une seule ligne <dependency> pour un framework web peut entraîner des dizaines de JARs que vous n'avez jamais nommés. La portée s'applique toujours lors de ce parcours : une dépendance de portée test ne tire pas ses dépendances transitives dans votre classpath de compilation, et les dépendances provided ne sont pas propagées transitivement.

Vous pouvez voir le graphe complet avec le plugin dependency :

$ mvn dependency:tree
[INFO] com.example:app:jar:1.0
[INFO] +- org.web:server:jar:2.4:compile
[INFO] |  +- org.log:log:jar:1.2:compile
[INFO] |  \- org.json:json:jar:1.7:compile - omitted for conflict with 1.9
[INFO] \- org.json:json:jar:1.9:compile

Médiation des conflits de version

Un graphe aussi profond veut presque toujours le même artifact à deux versions différentes. Maven ne peut pas les placer toutes les deux sur un même classpath, il en choisit donc une en utilisant la médiation nearest-wins (le plus proche gagne) : la version déclarée à la profondeur la plus faible par rapport à la racine de votre projet l'emporte, et les autres sont omises pour conflit.

Dans l'arbre ci-dessus, votre projet demande org.json:json:1.9 directement (profondeur 1), tandis que org.web:server demande 1.7 transitivement (profondeur 2). La déclaration à la profondeur 1 gagne. Si deux candidats se trouvent à la même profondeur, celui déclaré en premier dans le pom.xml gagne.

Lorsque le choix automatique est incorrect, vous prenez le contrôle explicitement. Une dépendance directe gagne toujours, ou vous pouvez fixer les versions pour l'ensemble du projet avec <dependencyManagement> :

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.json</groupId>
      <artifactId>json</artifactId>
      <version>1.9</version>
    </dependency>
  </dependencies>
</dependencyManagement>

Pour supprimer entièrement une branche transitive indésirable, utilisez <exclusions> :

<dependency>
  <groupId>org.web</groupId>
  <artifactId>server</artifactId>
  <version>2.4</version>
  <exclusions>
    <exclusion>
      <groupId>org.json</groupId>
      <artifactId>json</artifactId>
    </exclusion>
  </exclusions>
</dependency>

Un exemple complet

Maven lui-même n'est pas disponible sur ce runner de code, donc le programme ci-dessous modélise son résolveur en Java pur. Il publie quelques artifacts dans un petit dépôt en mémoire, puis effectue le même parcours en largeur d'abord et la même médiation nearest-wins que Maven utilise pour aplatir un graphe de dépendances en un seul classpath. Observez comment le org.json:json:1.7 plus profond perd face au 1.9 moins profond.

java— editable, runs on the server

import java.util.*;

public class DependencyResolver {
    // A library is identified by group:artifact and carries a version
    // plus the coordinates of the libraries it depends on.
    record Dep(String ga, String version, List<String> requires) {}

static final Map<String, Dep> REGISTRY = new HashMap<>();

static void publish(String ga, String version, String... requires) {
        REGISTRY.put(ga + ":" + version, new Dep(ga, version, List.of(requires)));
    }

public static void main(String[] args) {
        // A tiny registry that mimics a Maven repository.
        publish("app:app", "1.0", "org.web:server:2.4", "org.json:json:1.9");
        publish("org.web:server", "2.4", "org.log:log:1.2", "org.json:json:1.7");
        publish("org.json:json", "1.9");
        publish("org.json:json", "1.7");
        publish("org.log:log", "1.2");

// Breadth-first walk of the dependency tree: the depth at which a
        // coordinate first appears is its distance from the root.
        Map<String, Integer> depthOf = new LinkedHashMap<>();
        Map<String, String> chosenVersion = new LinkedHashMap<>();
        Deque<String[]> queue = new ArrayDeque<>();
        queue.add(new String[]{"app:app:1.0", "0"});
        int edges = 0;

while (!queue.isEmpty()) {
            String[] item = queue.poll();
            String coord = item[0];
            int depth = Integer.parseInt(item[1]);
            Dep dep = REGISTRY.get(coord);
            String ga = dep.ga();

// Nearest-wins mediation: the first time we reach an artifact
            // is the shallowest, so a later duplicate is simply skipped.
            if (depthOf.containsKey(ga)) {
                continue;
            }
            depthOf.put(ga, depth);
            chosenVersion.put(ga, dep.version());

for (String child : dep.requires()) {
                edges++;
                queue.add(new String[]{child, String.valueOf(depth + 1)});
            }
        }

System.out.println("Resolved classpath (nearest-wins):");
        for (var e : chosenVersion.entrySet()) {
            System.out.printf("  %-16s -> %s (depth %d)%n",
                e.getKey(), e.getValue(), depthOf.get(e.getKey()));
        }

System.out.println("\nVersion conflict on org.json:json");
        System.out.println("  candidates seen: 1.9 (depth 1), 1.7 (depth 2)");
        System.out.println("  winner: " + chosenVersion.get("org.json:json"));

System.out.println("\nTree edges visited: " + edges);
        System.out.println("Distinct artifacts: " + chosenVersion.size());
    }
}

Ce qu'il faut retenir de l'exécution :

Le classpath résolu liste chaque artifact exactement une fois, reflétant la façon dont Maven aplatit un graphe en un ensemble de JARs sans doublons de groupId:artifactId.
org.json:json apparaît à la version 1.9, et non 1.7, car la médiation nearest-wins conserve le candidat trouvé à la profondeur la plus faible (profondeur 1 l'emporte sur profondeur 2).
La colonne depth rend le terme "plus proche" concret : app:app est à la profondeur 0, ses dépendances directes sont à la profondeur 1, et org.log:log tiré transitivement est à la profondeur 2.
"Tree edges visited: 4" compte les relations de dépendance déclarées, tandis que "Distinct artifacts: 4" montre le graphe réduit à quatre coordonnées uniques après médiation.
Une coordonnée est ignorée dès qu'elle est rencontrée à nouveau (depthOf.containsKey(ga)), ce qui explique exactement pourquoi le 1.7 plus profond est "omis pour conflit" plutôt qu'ajouté une seconde fois.

Une fois vos dépendances résolues proprement, la question suivante est de savoir quand Maven les télécharge, compile, teste et package. Cet ordre est régi par les phases de build couvertes dans le chapitre sur le cycle de vie Maven.

Pratique

Dans Maven, deux versions du même artifact apparaissent dans le graphe de dépendances : la version 1.9 déclarée directement dans votre pom (profondeur 1) et la version 1.7 tirée transitivement (profondeur 2). Quelle version se retrouve sur le classpath ?

La version 1.9, car la médiation nearest-wins conserve la déclaration à la profondeur la plus faibleLa version 1.7, car la dépendance transitive a été résolue plus récemmentLe numéro de version le plus élevé, 1.9, car Maven préfère toujours la version la plus récenteLes deux versions, car Maven place chacune dans une entrée de classpath séparée