Criando JAR com dependências no Maven: guia passo a passo para iniciantes

«Seu aplicativo só funciona na IDE? Está na hora de mudar isso!»

Se você já programou em Java, com certeza já passou por esta situação: você mostra orgulhoso seu novo projeto para um amigo, executa no IntelliJ IDEA ou Eclipse — tudo funciona perfeitamente. Mas quando você tenta passar o projeto para um colega ou executá-lo pelo terminal, aparece um ClassNotFoundException ou NoClassDefFoundError. Parece familiar?

A maioria dos cursos e tutoriais ensina como criar um arquivo JAR com Maven, mas muitas vezes esquecem um detalhe crucial: para onde vão as dependências?. Um JAR comum contém apenas o seu código, enquanto todas as bibliotecas (como Apache Commons, Jackson, JUnit) ficam de fora. É por isso que surge a pergunta que milhões de desenvolvedores Java fazem no Stack Overflow: «How can I create an executable/runnable JAR with dependencies using Maven?»

Neste artigo, vamos explorar várias formas testadas de criar um JAR executável com dependências usando Maven. Você vai aprender a configurar o maven-assembly-plugin, o maven-shade-plugin e como isso funciona no Spring Boot. Vamos nessa!

Por que um JAR comum não funciona?

Vamos fazer um experimento simples. Imagine que você tem um aplicativo que faz parsing de JSON usando a biblioteca Jackson. Você cria um JAR comum com o comando mvn package e tenta executá-lo:

java -jar my-app.jar

E recebe algo como:

Exception in thread "main" java.lang.NoClassDefFoundError: com/fasterxml/jackson/databind/ObjectMapper

Por que isso acontece? Porque o Maven, por padrão, empacota apenas o seu código compilado (as classes da pasta src/main/java). Todas as dependências que você declarou no pom.xml ficam no repositório local do Maven (~/.m2/repository). Quando você executa o JAR, a JVM não sabe onde encontrar essas bibliotecas e lança um erro.

A solução é criar um fat JAR (JAR gordo) ou uber JAR, que contém não apenas suas classes, mas também todas as dependências necessárias. É para isso que existem plugins específicos do Maven.

Método 1: maven-assembly-plugin (simples e confiável)

A maneira mais popular e simples é usar o maven-assembly-plugin. Ele cria um JAR onde todas as dependências são descompactadas e combinadas com suas classes. Vamos configurá-lo.

Adicione o seguinte código ao seu pom.xml na seção <build><plugins>:

<plugin>\n    <groupId>org.apache.maven.plugins</groupId>\n    <artifactId>maven-assembly-plugin</artifactId>\n    <version>3.6.0</version>\n    <configuration>\n        <descriptorRefs>\n            <descriptorRef>jar-with-dependencies</descriptorRef>\n        </descriptorRefs>\n        <archive>\n            <manifest>\n                <mainClass>com.example.Main</mainClass>\n            </manifest>\n        </archive>\n    </configuration>\n    <executions>\n        <execution>\n            <id>make-assembly</id>\n            <phase>package</phase>\n            <goals>\n                <goal>single</goal>\n            </goals>\n        </execution>\n    </executions>\n</plugin>

Importante: substitua com.example.Main pelo nome completo da sua classe que contém o método main.

Agora, compile o projeto com o comando:

mvn clean package

Na pasta target, você verá dois arquivos:

\n
• my-app.jar — o JAR com