Skip to main content

Creando un Proyecto Básico con Maven

⏱ Dedicación recomendada: 0 minutos
Esto considera el contenido visible y relevante, e ignora texto colapsado o marcado como opcional.

r8vnhill/echo-app-maven

Antes de que un proyecto crezca, antes incluso de que escribamos una sola línea de código útil, hay algo igual de importante: cómo lo estructuramos.
Esta lección te guiará paso a paso en la creación de un proyecto Java básico utilizando Apache Maven, una de las herramientas más utilizadas en el ecosistema Java para gestionar compilaciones, dependencias y estructura de proyectos.

A través de un enfoque práctico, aprenderás cómo:

  • Instalar Maven correctamente en tu sistema.
  • Crear un proyecto base utilizando un arquetipo estándar.
  • Definir los metadatos esenciales del proyecto (groupId, artifactId, version y package).
  • Entender la estructura típica de un proyecto Maven.
  • Ejecutar una aplicación Java simple que simula el inicio de una aventura Pokémon.

El objetivo no es solo que tu programa funcione, sino que tengas una base sólida para escalar, probar y mantener tu código en el tiempo.

🧱 Paso 0: Instalar Maven​

Para instalar Maven, puedes usar un gestor de paquetes según tu sistema operativo:

scoop install maven

✅ Verificar instalación​

Para comprobar que Maven se instaló correctamente, ejecuta el siguiente comando en tu terminal:

mvn --version

Si la instalación fue exitosa, deberías ver una salida similar a esta:

Apache Maven 3.9.9 (8e8579a9e76f7d015ee5ec7bfcdc97d260186937)
Maven home: /path/to/maven
Java version: 23, vendor: Azul Systems, Inc., runtime: /path/to/java
Default locale: en_US, platform encoding: UTF-8
OS name: "Windows 10", version: "10.0", arch: "amd64", family: "windows"

🛠️ Paso 1: Crear el proyecto base​

Ejecuta el siguiente comando para generar un nuevo proyecto Maven usando una plantilla básica:

mvn archetype:generate "-DarchetypeArtifactId=maven-archetype-quickstart"
¿Qué acabamos de hacer?
  • archetype:generate: Ejecuta el plugin de arquetipos de Maven, que permite generar proyectos a partir de plantillas.
  • -DarchetypeArtifactId=maven-archetype-quickstart: Indica que queremos usar el arquetipo quickstart, una plantilla básica para proyectos Java con estructura estándar (src/main/java y src/test/java).
  • Al ejecutar este comando, Maven te guiará con preguntas interactivas como el groupId, artifactId y version, para personalizar el nuevo proyecto.

✏️ Paso 2: Definir el identificador del grupo (groupId)​

Durante la creación del proyecto, Maven te pedirá que ingreses un valor para la propiedad groupId. Verás algo como:

Define value for property 'groupId': com.github.username
¿Qué acabamos de hacer?

El groupId representa el nombre del grupo o la organización que desarrolla el proyecto. Suele seguir una convención similar al nombre de un paquete Java (por ejemplo, com.miempresa.proyecto). Este identificador se utilizará para distinguir tus artefactos en el repositorio Maven.

🏷️ Paso 3: Definir el identificador del artefacto (artifactId)​

Maven solicitará ahora el valor de artifactId. Verás una línea como esta en la terminal:

Define value for property 'artifactId': echo-app-maven
¿Qué acabamos de hacer?

El artifactId define el nombre del módulo o proyecto. Este será el nombre del directorio que se creará y también el identificador del artefacto generado (por ejemplo, echo-app-maven.jar).
Debe ser único dentro del grupo (groupId) y suele describir la función o propósito del proyecto.

🧭 Paso 4: Definir la versión del proyecto (version)​

Durante el proceso de creación, Maven pedirá que definas la versión del proyecto:

Define value for property 'version' 1.0-SNAPSHOT: 1.0.0
¿Qué acabamos de hacer?

La propiedad version especifica la versión del artefacto que estás generando.

  • Por defecto, Maven sugiere 1.0-SNAPSHOT, que indica una versión en desarrollo.
  • En este caso, optamos por una versión estable (1.0.0), lo cual es útil cuando no necesitas trabajar con snapshots y quieres una numeración semántica clara para tus módulos.

🧾 Paso 5: Definir el nombre del paquete base (package)​

Durante la configuración, Maven solicitará el nombre del paquete donde se generará el código fuente:

Define value for property 'package' com.github.username:
¿Qué acabamos de hacer?

La propiedad package define el espacio de nombres donde se ubicará tu código Java o Kotlin.

  • Maven sugiere usar el mismo valor que groupId, lo cual es una buena práctica para mantener consistencia.
  • Puedes aceptar el valor por defecto (com.github.username) o personalizarlo si prefieres una estructura distinta.

Este valor se reflejará en la carpeta generada (src/main/java/com/github/username) y en los package del código fuente.

✔️ Paso 6: Confirmar la configuración del proyecto​

Una vez que hayas completado todos los campos, Maven mostrará un resumen con los valores que proporcionaste:

groupId: com.github.username  
artifactId: echo-app-maven  
version: 1.0.0  
package: com.github.username  
 Y:
¿Qué acabamos de hacer?

Este paso es una confirmación final antes de que Maven genere el proyecto.

  • Si estás de acuerdo con los valores, simplemente presiona Enter o escribe Y y presiona Enter.
  • Si deseas corregir alguno, escribe N para volver atrás y modificar los campos.

Una vez confirmado, Maven creará la estructura del proyecto en una nueva carpeta llamada echo-app-maven.

🌳 Estructura de un Proyecto Maven​

Explicación de la estructura

Esta es la estructura típica de un proyecto Maven generado con el arquetipo maven-archetype-quickstart. Cada carpeta cumple un rol específico:

  • 📂 echo-app-maven: Es la carpeta raíz del proyecto. Contiene el archivo pom.xml, que define la configuración del proyecto, sus dependencias, plugins y estructura.
    • 📄 pom.xml: Archivo clave de Maven. Define el proyecto, sus metadatos y cómo debe compilarse. En proyectos multi-módulo, también coordina los módulos hijos.
    • 📂 src: Carpeta raíz del código fuente del proyecto.
      • 📂 main/java: Contiene el código fuente principal del proyecto. Aquí es donde se escriben las clases y funciones que conforman la lógica de la aplicación.
        • El subpaquete com/github/username sigue la convención de nombres de paquetes Java, basada en el dominio invertido del desarrollador.
      • 📂 test/java: Contiene el código de pruebas. Se usa para implementar pruebas unitarias o de integración usando frameworks como JUnit.
    • 📄 App.java y AppTest.java: Archivos de ejemplo generados por el arquetipo. Representan la clase principal del proyecto y su prueba asociada.

Esta organización permite separar claramente el código de producción del código de pruebas, y sigue las buenas prácticas de desarrollo en Java y Maven.

🎮 Paso 7: Ejecutar un "Hello, World!"​

Una vez que Maven haya creado el proyecto, entra en el directorio generado:

cd echo-app-maven

Luego, crea un archivo llamado App.java en la carpeta src/main/java/com/github/username y copia el siguiente código:

src/main/java/com/github/username/App.java
package com.github.username;

public class App {
    public static void main(String[] args) {
        System.out.println("Your journey as a Pokémon Trainer begins now.");
        System.out.println("Choose wisely: Bulbasaur, Charmander, or Squirtle?");
    }
}
¿Qué acabamos de hacer?

Esta clase define el punto de entrada del programa.
La función main imprime tres líneas que simulan el inicio de un juego al estilo Pokémon.

  • System.out.println(...) es la forma estándar de imprimir mensajes en Java.

Asegúrate de que el nombre del paquete (package com.github.username;) coincida con el que especificaste durante la creación del proyecto.

▶️ Ejecutar la aplicación​

Una vez generado el proyecto, puedes compilar y ejecutar el módulo app directamente desde la raíz del proyecto:

mvn -pl app exec:java "-Dexec.mainClass=com.github.username.App"
¿Qué acabamos de hacer?

Este comando realiza dos cosas:

  • -pl app: le dice a Maven que ejecute solo el módulo app (y sus dependencias, como lib).
  • exec:java -Dexec.mainClass=com.github.username.App: usa el plugin exec-maven-plugin para ejecutar la clase principal del proyecto.

El valor com.github.username.App debe coincidir exactamente con el nombre completo de tu clase principal, incluyendo el paquete.

Si todo está bien configurado, deberías ver una salida como esta:

Your journey as a Pokémon Trainer begins now.
Choose wisely: Bulbasaur, Charmander, or Squirtle?

🎯 Conclusiones​

Crear un proyecto Java con Maven puede parecer tedioso al principio, pero dominar esta herramienta te prepara para trabajar en entornos profesionales donde la estructura, la automatización y la gestión de dependencias son fundamentales.

En esta lección aprendimos a utilizar mvn archetype:generate para construir un proyecto base, exploramos cómo Maven organiza el código y cómo ejecutar nuestra aplicación desde la línea de comandos.
Además, dimos nuestros primeros pasos hacia un diseño modular que separa el código principal de sus pruebas, con vistas a escalar el proyecto en el futuro.

Más allá de los comandos y configuraciones, lo importante fue comprender por qué estructurar bien un proyecto importa: favorece la claridad, la mantenibilidad y la colaboración.

🔑 Puntos clave​

  • mvn archetype:generate te permite crear rápidamente un proyecto base con una estructura estándar.
  • Maven organiza el código en carpetas bien definidas para producción (main) y pruebas (test).
  • El archivo pom.xml es el corazón del proyecto: define su identidad, dependencias y plugins.
  • Ejecutar tu aplicación requiere indicar el módulo (-pl) y la clase principal (-Dexec.mainClass=...).
  • Usar paquetes con nombres consistentes mejora la claridad y evita conflictos en proyectos grandes.

🧰 ¿Qué nos llevamos?​

Esta lección no solo nos enseñó a usar Maven: nos mostró cómo empezar un proyecto con el pie derecho.

Cuando usamos herramientas como Maven desde el comienzo, ganamos más que automatización: ganamos una forma de pensar que separa responsabilidades, documenta nuestras decisiones en archivos de configuración y deja una base clara para el trabajo en equipo.

Lo que comenzamos como un simple "Hello, World!" terminó siendo un proyecto real, con estructura, propósito y potencial para crecer.

Y así como en Pokémon elegimos un compañero para iniciar nuestra aventura, aquí elegimos herramientas y estructuras que nos acompañarán en el desarrollo de software profesional.

📖 Referencias​

🔥 Recomendadas​