Guía paso a paso con Spring Initializr para arrancar tu primer proyecto Spring Boot

¿Querés empezar un nuevo proyecto Spring Boot sin perder tiempo en configuraciones? Spring Initializr (el servicio web oficial start.spring.io) es la herramienta perfecta para crear un esqueleto de proyecto listo para usar. En este artículo, vas a recorrer todo el proceso, desde lo más básico hasta un ejemplo completo de API REST, con código real, explicaciones detalladas y una descripción de lo que verás al ejecutar el proyecto.

Para quién es esta guía

Si acabas de descubrir Spring Boot y te sentís un poco perdido con las dependencias, los archivos pom.xml o build.gradle, esta guía te llevará de la mano. Vas a aprender cómo usar Spring Initializr, elegir las dependencias correctas y luego ejecutar un proyecto minimalista que responde a peticiones HTTP. Al terminar, vas a tener un proyecto que podés usar como punto de partida para cualquier aplicación Spring.

Qué vas a aprender

• Cómo planificar un proyecto Spring Boot (groupId, artifactId, package, empaquetado, Java/Kotlin, dependencias).
• Tres formas de generar un proyecto: el sitio web, la CLI (spring init) y los plugins de los IDEs.
• Cómo navegar la estructura del proyecto generado.
• Cómo crear un simple controlador REST con un modelo básico, un servicio y un test.
• Cómo construir y ejecutar el proyecto con Maven o Gradle.
• Buenas prácticas y errores comunes a la hora de empezar un proyecto.

1. Instalación de lo esencial

Antes que nada, necesitas Java (o Kotlin) y una herramienta de construcción (Maven o Gradle) instalada.

1.1 Verificar Java

Abre una terminal (o VS Code Shell, Git Bash, PowerShell) y ejecuta:

gjava -version

Deberías ver una versión como 21.0.2. Si no la tenés, descargá Java desde el sitio oficial (JDK 21 es una buena opción para proyectos nuevos).

1.2 Elegir Maven o Gradle

Ambas herramientas funcionan bien con Spring Boot, pero Maven es más común en proyectos corporativos, mientras que Gradle puede ser más rápido para builds grandes. Esta guía usa Maven, pero casi todos los pasos aplican para Gradle.

Verifica la versión de Maven:

mvn -v

Si no tienes Maven, instalalo desde https://maven.apache.org/download.cgi o a través de tu gestor de paquetes (por ejemplo, apt-get install maven).

2. Spring Initializr web – la interfaz gráfica

El método más visual es visitar https://start.spring.io/. Es un generador de proyectos con una interfaz limpia que te permite seleccionar dependencias, lenguajes y empaquetado sin tocar una línea de código.

2.1 Llenar los campos básicos

2.2 Seleccionar dependencias

Las dependencias más comunes para proyectos nuevos:

• Web (spring-boot-starter-web): Controller, DispatcherServlet, Jackson JSON.
• JPA (spring-boot-starter-data-jpa): Soporte de persistencia con Hibernate.
• H2 (com.h2database:h2): Base de datos incrustada para prototipos rápidos.
• Actuator (spring-boot-starter-actuator): /health, /info, /metrics.
• Test (spring-boot-starter-test): JUnit5, Mockito, AssertJ.

Puedes escribir manualmente el nombre de una dependencia en la caja “Search dependencies” (ej. validation) para filtrar resultados.

2.3 Generar y descargar

Presiona Generate. Spring Initializr compila el proyecto, empaqueta el código fuente, los archivos pom.xml (o build.gradle) y un archivo ZIP que podés descargar. Luego, extraelo en tu workspace.

2.4 ¿Qué obtienes dentro del ZIP?

Un típico proyecto Maven con src/main/java, src/main/resources, y src/test/java. Estructura de directorios típica:

myapp
├─ src
│  ├─ main
│  │  ├─ java
│  │  │  └─ com.example
│  │  │     └─ myapp
│  │  │        ├─ MyappApplication.java
│  │  │        └─ config
│  │  ├─ resources
│  │  │  ├─ application.properties
│  │  │  └─ static
│  │  └─ test
│  │     ├─ java
│  │     │  └─ com.example
│  │     │     └─ myapp
│  │     │        ├─ MyappApplicationTests.java
│  │     │        └─ service
│  └─ pom.xml

pom.xml (Maven) contiene el plugin de arranque de Spring Boot, el padre de Spring Boot y todas las dependencias que seleccionaste.

3. Spring Boot CLI – una forma basada en terminal

Si preferís una experiencia más cercana a la línea de comandos, podés usar la CLI de Spring (spring). Por defecto, incluye un comando spring init que funciona igual que la interfaz web, pero sin necesidad de un navegador.

3.1 Instalar la CLI

Puedes instalarla con SDKMAN (si ya la usas):

sdk install springboot

O con un instalador directo desde https://spring.io/projects/spring-boot#learn. Una vez instalado, ejecuta spring --version para verificar.

3.2 Comando rápido para un proyecto básico

Este es un comando autocontenido que imprime una lista de archivos y config, y después podés compilarlo.

spring init -d=web,actuator,validation my-app

Lo que verás: El comando crea un directorio my-app, descarga la última versión estable de Spring Boot, elige las dependencias web, actuator y validation, y genera un esqueleto de proyecto. Puedes inspeccionar la estructura:

cd my-app
ls -R

El output mostrará pom.xml, un src/main/java/com/example/myapp en el package, etc.

3.3 Construir el proyecto desde la CLI

Ahora podés compilar con Maven:

mvn clean package

Si el build es exitoso, el JAR estará en target/my-app-0.0.1-SNAPSHOT.jar.

Puedes ejecutarlo al instante:

java -jar target/my-app-0.0.1-SNAPSHOT.jar

Spring Boot arranca en http://localhost:8080. Puedes verificarlo con curl:

curl http://localhost:8080/actuator/health

El output esperado (en JSON) sería:

{
  "status": "UP",
  "components": {
    "db": {
      "status": "UP",
      "details": {
        "database": "H2",
        "hello": "true"
      }
    },
    "diskSpace": {
      "status": "UP",
      "details": {
        "total": 500106556928,
        "free": 406956122112,
        "threshold": 10485760
      }
    }
  }
}

(El JSON puede variar levemente según las dependencias, pero el estado principal UP aparece siempre).

4. Plugins de IDEs – configuración con un clic

Los desarrolladores usan a menudo IntelliJ IDEA, Eclipse o VS Code (con Spring Boot Tools). Los plugins generan automáticamente el mismo esqueleto que puedes obtener con la interfaz web.

4.1 IntelliJ IDEA

1. File → New → Project.
2. Elige Spring Initializr desde el panel izquierdo (o busca Spring Initializr).
3. Rellena los mismos campos que en la página web: GroupId, ArtifactId, Package, etc.
4. Selecciona las dependencias.
5. Haz clic en Finish.

IntelliJ creará el proyecto y configura automáticamente src/main/java, src/main/resources, y también agrega los archivos pom.xml o `build.gradle.

4.2 Eclipse (e(f)clipse)

Puedes instalar el plugin Spring Boot Setup desde el marketplace de Eclipse. Después de instalarlo, File → New → Spring Boot Project inicia el asistente, que te permite seleccionar las mismas opciones.

4.3 VS Code con Spring Boot Tools

Instala la extensión Spring Boot Tools desde la Marketplace. Luego, abre el comando Spring Boot: Generate Project. Sigue los prompts en la interfaz.

5. Ejemplo completo – crear un REST API que dice hola

Ahora, aplicamos todo lo anterior: vamos a construir un servicio REST simple: /greeting que acepta un parámetro name opcional y devuelve un saludo.

5.1 Proyecto generado (usando start.spring.io)

# Genera el proyecto usando la CLI (mismo efecto que start.spring.io)
spring init -d=web,validation -packageName=com.example.demo -n=greetingDemo -j=17 greeting-demo

El comando crea un proyecto Maven con las siguientes características:

• Lenguaje: Java (JDK 17)
• Packagings: Jar
• Dependencias: web (Controller + Jackson), validation (para JSR‑303 annotations)

5.2 Estructura del código generado

greeting-demo
├─ src
│  ├─ main
│  │  ├─ java
│  │  │  └─ com
│  │  │     └─ example
│  │  │        └─ demo
│  │  │           ├─ GreetingController.java
│  │  │           ├─ Greeting.java
│  │  │           └─ DemoApplication.java
│  │  └─ resources
│  │     └─ application.properties
│  └─ test
│     └─ java
│        └─ com
│           └─ example
│              └─ demo
│                 └─ DemoApplicationTests.java
└─ pom.xml

5.3 Mostrar los archivos

5.3.1 src/main/java/com/example/demo/Greeting.java

package com.example.demo;

import jakarta.validation.constraints.NotBlank;

public class Greeting {

    private final long id;
    private final String content;

    public Greeting(long id, String content) {
        this.id = id;
        this.content = content;
    }

    public long getId() {
        return id;
    }

    public String getContent() {
        return content;
    }
}

5.3.2 src/main/java/com/example/demo/GreetingController.java

package com.example.demo;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class GreetingController {

    private static final String template = "Hello, %s!";
    private final AtomicLong counter = new AtomicLong();

    @GetMapping("/greeting")
    public Greeting greeting(@RequestParam(value = "name", defaultValue = "World") String name) {
        return new Greeting(counter.incrementAndGet(), String.format(template, name));
    }
}

Nota – AtomicLong se importa desde java.util.concurrent.atomic. Spring Boot ya incluye las dependencias necesarias.

5.3.3 src/main/java/com/example/demo/DemoApplication.java

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {

    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

5.3.4 src/main/resources/application.properties

# Configuración del servidor (puerto predeterminado 8080)
server.port=8080

# Configuración de logging
logging.level.com.example.demo=INFO

5.3.5 src/test/java/com/example/demo/DemoApplicationTests.java

package com.example.demo;

import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class DemoApplicationTests {

    @Test
    void contextLoads() {
        // Spring Boot carga el contexto sin errores
    }
}

5.4 Compilar y ejecutar el proyecto

cd greeting-demo
mvn clean package

Cuando el build finalice, ejecuta el JAR:

java -jar target/greeting-demo-0.0.1-SNAPSHOT.jar

Deberías ver algo como:

2024-10-30 12:34:56.789  INFO 1 --- [main] com.example.demo.DemoApplication      : Started DemoApplication in 1.234 seconds (JVM running for 2.345)
2024-10-30 12:34:57.001  INFO 1 --- [main] com.example.demo.GreetingController : /greeting request received

5.5 Probar el endpoint con curl

Desde otra terminal (o con Postman), haz una petición GET:

curl "http://localhost:8080/greeting"

Salida esperada

{"id":1,"content":"Hello, World!"}

Con un nombre personalizado:

curl "http://localhost:8080/greeting?name=Spring"

Salida esperada

{"id":2,"content":"Hello, Spring!"}

También podés probar con un framework de pruebas como curl -X GET http://localhost:8080/greeting -H "Accept: application/json".

5.6 ¿Qué hicimos hasta aquí?

• Usamos Spring Initializr (vía CLI) para generar un proyecto con las dependencias correctas.
• Creamos un modelo simple (Greeting) que se serializa a JSON (gracias al HttpMessageConverter de Jackson).
• Implementamos un controlador (GreetingController) que responde en /greeting.
• Agregamos un test básico que solo verifica que el contexto de Spring Boot carga sin errores.

Tienes ahora un punto de partida sólido: un controlador REST mínimo, un POJO, un modelo estándar DemoApplication, y una configuración limpia.

6. Mejores prácticas al empezar un proyecto nuevo

1. Escoge las dependencias con cuidado: Siempre comienza con el conjunto core (Web, JPA, Test), luego añade solo lo que necesitas.
2. Mantén el groupId significativo: Evita com.example; usa tu dominio inverso (com.tuempresa.app).
3. Empaquetado adecuado: Por defecto, jar. Cambia a war solo si implementas en un servidor de aplicaciones que espera empaquetado WAR.
4. Versionado con Spring Boot: La versión de Boot está definida en pom.xml (spring-boot-version). Sigue la versión que tu equipo adoptó, o usa la última estable.
5. Propiedades comunes: Coloca propiedades estándar en application.properties (server.port, spring.application.name). Esto ayuda a la consistencia entre entornos.
6. Separación de concerns: Cada controlador debe tener su propio paquete. Ejemplo: com.tuempresa.app.controller. El modelo va en model o domain. Servicios en service.
7. Tests exhaustivos: Empieza con un contextLoads y luego escribe tests de controlador (@WebMvcTest) para tus endpoints.
8. Hazlo reproducible: Usa maven-surefire-plugin con una versión Java estable. Para Gradle, configura java { toolchain { languageVersion = JavaVersion.VERSION_21 } }.
9. Evita código de arranque personalizado cuando puedas: Spring Boot ya provee una configuración extensa (@SpringBootApplication). Solo añade @EnableXxx o @Configuration si necesitas behavior personalizada.
10. Documenta con /actuator: Añade actuator lo antes posible; /health, /info te dan visibilidad sin esfuerzo.

7. Errores comunes y cómo evitarlos

8. Conclusión

Spring Initializr es la puerta de entrada perfecta para empezar proyectos Spring Boot. Ya sea que uses la interfaz web de start.spring.io, el comando spring init de la CLI, o los asistentes de los IDEs, puedes generar un esqueleto limpio y listo para usar en segundos.

A partir de ese esqueleto, puedes construir APIs REST, servicios de datos o microservicios. El ejemplo que cubrimos (/greeting) demuestra una arquitectura mínima pero completa: un controlador, un modelo simple, un servicio opcional (si lo necesitas), y un test básico.

Recuerda seleccionar las dependencias correctas, mantener un groupId significativo, empaquetar como JAR a menos que necesites WAR, y nunca olvides agregar el actuator para facilitar el monitoreo.

Con esta guía, ya tienes lo esencial para arrancar cualquier proyecto Spring Boot. Ahora puedes concentrarte en escribir código útil, probarlo, y desplegarlo, en vez de perder tiempo en configuraciones repetitivas.

Próximos pasos: Explora el Spring Initializr más allá de lo básico: usa plantillas personalizadas (spring init -t), configura un servidor de repositorio remoto, o prueba la CLI con perfiles avanzados (-e, --dependency-overrides).

¡Feliz coding! 🚀

Puntos clave:

• Usa Spring Initializr para generar proyectos Spring Boot rápidamente.
• Elige las dependencias mínimas que realmente necesites.
• Genera un controlador REST simple, un modelo y un test para verificar el flujo.
• Ejecuta mvn clean package y luego java -jar target/<artifact>-<version>.jar.
• Sigue buenas prácticas (groupId significativo, empaquetado adecuado, actuator, tests) para evitar dolores de cabeza futuros.