Introdução ao Apache Maven para Java

Maven é a ferramenta padrão de automação de build e gerenciamento de dependências para Java. Ele transforma um projeto em uma descrição declarativa — o que ele é, do que depende, como é construído — e executa o build por você. Em vez de gerenciar manualmente arquivos JAR e flags do javac, você declara suas necessidades em um único arquivo e o Maven baixa as dependências, compila, testa e empacota seu código por meio de um ciclo de vida previsível e reproduzível.

O POM: um projeto como dados

Todo projeto Maven é descrito por um pom.xml (Project Object Model). Ele identifica o projeto com três coordenadas — groupId, artifactId e version (juntas chamadas de "GAV") — e lista as bibliotecas necessárias. O mesmo esquema de coordenadas nomeia seu projeto e cada dependência, e é assim que o Maven localiza os artefatos em um repositório.

<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>shop-app</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>

  <properties>
    <maven.compiler.release>21</maven.compiler.release>
  </properties>

  <dependencies>
    <dependency>
      <groupId>org.springframework</groupId>
      <artifactId>spring-web</artifactId>
      <version>6.1.0</version>
    </dependency>
  </dependencies>
</project>

O elemento <packaging> informa ao Maven o que produzir (jar, war, pom). O bloco <properties> contém valores reutilizáveis — aqui, a versão Java que o compilador tem como alvo. O POM cresce para cobrir plugins, perfis e herança; o capítulo Maven POM detalha essas partes.

Dependências e o classpath transitivo

Você lista apenas suas dependências diretas. O Maven lê o próprio POM de cada dependência e inclui tudo o que elas precisam — as dependências transitivas — construindo o classpath completo automaticamente. Declarar spring-web também traz spring-core sem que você precise nomeá-lo.

<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.17.0</version>
</dependency>

Cada dependência tem um escopo que controla quando ela está no classpath. O padrão, compile, a disponibiliza em todo lugar; test a limita ao código de teste; provided significa que o runtime a fornece. Para conflitos de versão, exclusões e dependencyManagement, consulte dependências do Maven.

Escopo	No classpath de compilação	No classpath de teste	Empacotado	Uso típico
`compile` (padrão)	Sim	Sim	Sim	Bibliotecas comuns
`provided`	Sim	Sim	Não	API Servlet, fornecida em runtime
`runtime`	Não	Sim	Sim	Drivers JDBC
`test`	Não	Sim	Não	JUnit, Mockito

O ciclo de vida do build

Os builds do Maven percorrem uma sequência fixa de fases. As principais fases do ciclo de vida padrão são validate, compile, test, package, verify, install e deploy. Executar uma fase executa todas as fases anteriores — mvn package primeiro valida, compila e testa, depois empacota. Você nunca chama fases fora de ordem.

mvn compile          # compile main sources
mvn test             # compile + run unit tests
mvn package          # compile + test + build the JAR/WAR
mvn install          # package + copy artifact into your local repository
mvn clean package    # delete target/ first, then build fresh

Cada fase está vinculada a um ou mais objetivos fornecidos por plugins (por exemplo, compiler:compile está vinculado à fase compile). Os plugins são onde o trabalho real acontece; o ciclo de vida apenas ordena esse trabalho. O capítulo ciclo de vida do build Maven percorre todos os três ciclos de vida integrados e como os objetivos se vinculam às fases.

Repositórios

O Maven busca artefatos em repositórios. Ao fazer o build, ele procura primeiro no seu repositório local (~/.m2/repository), um cache na sua máquina. Se não encontrar, ele baixa de um repositório remoto — por padrão o Maven Central — e armazena uma cópia localmente para que o próximo build seja rápido mesmo offline. As equipes frequentemente adicionam um repositório privado para bibliotecas internas.

project pom.xml  →  local repo (~/.m2)  →  remote repo (Maven Central)
                     (cache hit?)            (download + cache)

Um exemplo executável

O executor de código não tem Maven em seu classpath, portanto o programa abaixo modela a mecânica central do Maven com código puro do JDK: ele armazena um POM simples como um mapa, resolve o fechamento de dependências transitivas (eliminando duplicatas de artefatos compartilhados) e percorre o ciclo de vida do build, parando na fase solicitada. As formas aqui — coordenadas GAV, resolução transitiva, fases ordenadas — são exatamente o que o Maven real faz.

java— editable, runs on the server

import java.util.*;

public class Main {
    // A coordinate triple, exactly like Maven's groupId:artifactId:version.
    record Gav(String groupId, String artifactId, String version) {
        @Override public String toString() {
            return groupId + ":" + artifactId + ":" + version;
        }
        String jar() { return artifactId + "-" + version + ".jar"; }
    }

// The project model: each artifact mapped to the dependencies it declares.
    static final Map<String, List<Gav>> pom = new LinkedHashMap<>();

static void declare(Gav a, Gav... deps) { pom.put(a.toString(), List.of(deps)); }

// Build the transitive closure the way Maven resolves a classpath.
    static void resolve(Gav a, Set<String> seen, List<Gav> out) {
        for (Gav d : pom.getOrDefault(a.toString(), List.of())) {
            if (seen.add(d.toString())) {   // de-dupe: each JAR appears once
                out.add(d);
                resolve(d, seen, out);      // then pull in its own dependencies
            }
        }
    }

public static void main(String[] args) {
        Gav app     = new Gav("com.example", "shop-app", "1.0.0");
        Gav web     = new Gav("org.springframework", "spring-web", "6.1.0");
        Gav core    = new Gav("org.springframework", "spring-core", "6.1.0");
        Gav jackson = new Gav("com.fasterxml.jackson.core", "jackson-databind", "2.17.0");
        Gav annot   = new Gav("com.fasterxml.jackson.core", "jackson-annotations", "2.17.0");

declare(app, web, jackson);   // our project's direct dependencies
        declare(web, core);           // spring-web transitively needs spring-core
        declare(jackson, annot);      // jackson-databind needs jackson-annotations
        declare(core);
        declare(annot);

System.out.println("Project coordinates: " + app);
        System.out.println("Direct dependencies:");
        for (Gav d : pom.get(app.toString())) System.out.println("  - " + d);

List<Gav> classpath = new ArrayList<>();
        resolve(app, new HashSet<>(), classpath);
        System.out.println("Resolved classpath has " + classpath.size() + " JARs:");
        for (Gav g : classpath) System.out.println("  - " + g.jar());

List<String> phases = List.of("validate", "compile", "test", "package", "install");
        String goal = "package";
        System.out.println("Executing: mvn " + goal);
        for (String p : phases) {
            System.out.println("  phase " + p + " -> OK");
            if (p.equals(goal)) break;   // stop once the requested phase is reached
        }
        System.out.println("BUILD SUCCESS");
    }
}

O que observar na execução:

O projeto e cada dependência são nomeados pela mesma tripla GAV, razão pela qual Project coordinates: com.example:shop-app:1.0.0 se parece com uma linha de dependência.
Apenas duas dependências são declaradas, mas o classpath resolvido tem quatro JARs — spring-core e jackson-annotations foram incluídos transitivamente, exatamente como o Maven faz.
O conjunto seen garante que cada artefato apareça apenas uma vez; esta é a deduplicação do Maven que impede que uma biblioteca compartilhada apareça no classpath duas vezes.
Executing: mvn package executa validate, compile e test antes de package e então para — executar uma fase sempre executa todas as fases anteriores em ordem.
O build para em package e nunca chega a install, refletindo como o objetivo solicitado limita até onde o ciclo de vida avança.

Quando usar o Maven

O Maven se destaca em projetos Java e JVM convencionais: seus padrões de "convenção sobre configuração" (código-fonte em src/main/java, testes em src/test/java, saída em target/) significam que um novo colaborador pode compilar qualquer projeto Maven da mesma forma. Seu XML declarativo é fácil de ler e fazer diff, e o suporte a IDEs é maduro. A contrapartida é a verbosidade e a flexibilidade limitada para builds incomuns. Quando você precisa de builds com scripts e altamente personalizados, o Gradle é a alternativa comum — ele usa um script de build programável em vez de XML declarativo, mas cobre o mesmo terreno: coordenadas GAV, dependências transitivas e um grafo de tarefas (em vez de fases).

Próximos passos

Maven POM — a estrutura completa do pom.xml, incluindo plugins e herança.
Dependências do Maven — escopos, exclusões e resolução de conflitos de versão em profundidade.
Ciclo de vida do build Maven — cada fase, os três ciclos de vida e como vincular objetivos.
Introdução ao Gradle — a alternativa baseada em scripts ao Maven.

Prática

No Maven, o que acontece quando você executa 'mvn package'?

O Maven executa todas as fases anteriores do ciclo de vida (validate, compile, test) e depois empacota o artefatoO Maven executa apenas a fase package e ignora a compilação e os testesO Maven implanta o artefato em um repositório remotoO Maven baixa o JDK antes de fazer o build