O arquivo pom.xml

O pom.xml (Project Object Model) é o ficheiro central de todo o projeto Maven. É um documento XML que descreve o projeto: a sua identidade, as suas dependências, as suas propriedades e a forma de o construir.

Todo o pom.xml começa por uma raiz <project> com o seu espaço de nomes e declara obrigatoriamente a versão do modelo:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <!-- O resto da configuração aqui -->

</project>

<modelVersion>4.0.0</modelVersion> é obrigatório e vale sempre 4.0.0 hoje: é a versão do formato de ficheiro pom.xml, não a versão do seu projeto.

Um pom.xml lê-se de cima para baixo, por grandes blocos. Eis a organização típica:

O bloco <packaging> determina o tipo de entregável:

Se omitir <packaging>, o Maven escolhe jar por omissão. Mais uma vez: convenção em vez de configuração.

🔧 Mini-exercício — Escreva a etiqueta <packaging> para produzir uma aplicação web implantável no Tomcat.

<packaging>war</packaging>

Todo o projeto Maven é identificado de forma única por três coordenadas, muitas vezes abreviadas GAV: GroupId, ArtifactId, Version.

<groupId>com.exemple</groupId>
<artifactId>mon-app</artifactId>
<version>1.0.0</version>

O sufixo -SNAPSHOT merece atenção especial:

# O nome do artefacto produzido combina artifactId + version
# Ex : mon-app-1.0.0-SNAPSHOT.jar
mvn package

A combinação groupId:artifactId:version é o « endereço postal » do seu projeto no ecossistema Maven. É assim que outros projetos poderão depender dele.

🔧 Mini-exercício — Escreva as três etiquetas GAV para um projeto com.banque chamado gestion-comptes em versão de desenvolvimento 1.0.0.

<groupId>com.banque</groupId>
<artifactId>gestion-comptes</artifactId>
<version>1.0.0-SNAPSHOT</version>

O bloco <properties> define variáveis reutilizáveis em todo o pom.xml. Aí se centralizam as versões e os ajustes para evitar repetições.

<properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <junit.version>5.10.2</junit.version>
</properties>

Reutiliza-se depois uma propriedade com a sintaxe ${nom}:

<dependency>
    <groupId>org.junit.jupiter</groupId>
    <artifactId>junit-jupiter</artifactId>
    <version>${junit.version}</version>   <!-- reutiliza a propriedade -->
    <scope>test</scope>
</dependency>

Propriedades habituais:

Centralizar as versões em <properties> é uma boa prática: para passar o JUnit de 5.10 a 5.11, modifica um só sítio em vez de cada dependência.

🔧 Mini-exercício — Defina uma propriedade gson.version com o valor 2.10.1 e mostre como a reutilizar numa etiqueta <version>.

<properties>
    <gson.version>2.10.1</gson.version>
</properties>
<!-- ... -->
<version>${gson.version}</version>

Um pom.xml pode herdar de outro pom.xml via o bloco <parent>. O filho recupera então as propriedades, dependências e configurações do parent. É o mecanismo que permite fatorizar a configuração comum a vários módulos.

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>3.2.5</version>
    <relativePath/>   <!-- vazio: ir buscar o parent no repositório -->
</parent>

O uso mais conhecido é o parent Spring Boot, que fixa as versões de dezenas de bibliotecas para que sejam compatíveis entre si. Graças a ele, declara dependências sem precisar a versão:

<!-- Sem <version>: é herdada do parent -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

O parent Spring Boot age como uma « lista de compras validada »: garante que todas as suas bibliotecas se entendem, sem que tenha de escolher cada número de versão à mão.

Eis um pom.xml realista que reúne tudo o que precede: coordenadas, propriedades, parent opcional e dependências.

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <!-- Versão do formato de ficheiro -->
    <modelVersion>4.0.0</modelVersion>

    <!-- Coordenadas GAV: identidade do projeto -->
    <groupId>com.exemple</groupId>
    <artifactId>mon-app</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <!-- Variáveis reutilizáveis -->
    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <junit.version>5.10.2</junit.version>
    </properties>

    <!-- Bibliotecas usadas -->
    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>

Pode mostrar-se o pom.xml « efetivo » (com toda a herança resolvida):

# Mostra o pom completo, parent incluído
mvn help:effective-pom

O comando mvn help:effective-pom é precioso para compreender o que o Maven « vê » realmente, incluindo tudo o que vem do parent.

🔧 Mini-exercício — Escreva o comando que mostra o pom.xml efetivo, com toda a herança do parent resolvida.

mvn help:effective-pom

Question 1

O que valem as três coordenadas GAV?

a) Group, Action, Value

b) GroupId, ArtifactId, Version

c) Git, Apache, Version

d) General, Application, Version

Question 2

O que significa o sufixo -SNAPSHOT numa versão?

a) Uma versão publicada e congelada

b) Uma versão em desenvolvimento, instável e atualizada com frequência

c) Uma captura de ecrã do projeto

d) Uma versão obsoleta

Question 3

Para que serve o bloco <properties>?

a) Para declarar as dependências

b) Para definir variáveis reutilizáveis (versões, encoding) com ${...}

c) Para configurar o servidor web

d) Para escrever o código Java

Question 4

Qual é a vantagem de herdar de um <parent> como spring-boot-starter-parent?

a) Elimina a necessidade de código

b) Garante versões de bibliotecas coerentes e reduz a configuração

c) Acelera a rede

d) Cifra o pom.xml

Question 5

Que valor toma sempre <modelVersion> hoje?

a) 1.0.0

b) 3.9.6

c) 4.0.0

d) 17

Instrução

Redija de raiz um pom.xml para um projeto identificado por com.banque:gestion-comptes:1.0.0-SNAPSHOT, empacotado em jar, compilado em Java 17 com encoding UTF-8, e a centralizar a versão do JUnit numa propriedade. Depois verifique-o.

Correção — pom.xml esperado

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             http://maven.apache.org/xsd/maven-4.0.0.xsd">

    <modelVersion>4.0.0</modelVersion>

    <groupId>com.banque</groupId>
    <artifactId>gestion-comptes</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <junit.version>5.10.2</junit.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter</artifactId>
            <version>${junit.version}</version>
            <scope>test</scope>
        </dependency>
    </dependencies>

</project>

Verificação:

# Verifica que o pom é válido e resolúvel
mvn validate

# Mostra o pom efetivo (parent e propriedades resolvidos)
mvn help:effective-pom

Resultado esperado:

[INFO] BUILD SUCCESS

Se mvn validate mostrar BUILD SUCCESS, o seu pom.xml está sintaticamente correto e todas as coordenadas estão bem formadas. Um erro frequente: esquecer <modelVersion> ou fechar mal uma etiqueta XML.

Pontos a reter

1. O pom.xml é um ficheiro XML que descreve identidade, propriedades, dependências e build.
2. As coordenadas GAV (groupId, artifactId, version) identificam o projeto de forma única.
3. -SNAPSHOT = versão em desenvolvimento; sem sufixo = versão publicada congelada.
4. As <properties> centralizam variáveis reutilizáveis via ${nom}.
5. A herança <parent> fatoriza a configuração e garante versões coerentes.

A continuação

Lição 03 — Gestão das dependências: declarar bibliotecas, compreender os âmbitos, os repositórios e a resolução transitiva.