Debug Java con Spring Boot en Visual Studio Code

Para configurar el debug de una aplicación Spring Boot en Visual Studio Code (VS Code), vamos a preparar el entorno para que puedas ejecutar la aplicación en modo depuración, establecer puntos de interrupción (breakpoints), inspeccionar variables y avanzar línea por línea en el código Java.

Te exlicaré el proceso paso a paso, suponiendo que trabajas en Ubuntu y que tu proyecto utiliza Maven.

Instalar las extensiones necesarias

Abre Visual Studio Code y accede al apartado de extensiones pulsando Ctrl + Shift + X.

Busca e instala las siguientes extensiones:

Extensión	Función
Extension Pack for Java	Incluye herramientas para desarrollar, ejecutar y depurar aplicaciones Java.
Spring Boot Extension Pack	Incorpora herramientas para trabajar con proyectos Spring Boot.

La extensión más importante para depurar Java es Debugger for Java, que forma parte de Extension Pack for Java.

Puedes instalarlas desde VS Code o desde una terminal de Ubuntu.

code --install-extension vscjava.vscode-java-pack
code --install-extension vmware.vscode-boot-dev-pack

Si el segundo comando no encuentra la extensión, puedes buscar Spring Boot Extension Pack directamente en el marketplace de VS Code.

Abrir el proyecto Spring Boot

Abre VS Code y selecciona:

File → Open Folder

Selecciona la carpeta raíz de tu proyecto Spring Boot.

Por ejemplo:

mi-proyecto/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── ejemplo/
│   │   │           ├── Application.java
│   │   │           ├── controller/
│   │   │           ├── service/
│   │   │           └── repository/
│   │   └── resources/
│   │       └── application.properties
│   └── test/
└── target/

La estructura puede variar según tu proyecto.

Importante: abre la carpeta que contiene el archivo pom.xml o build.gradle, no solamente la carpeta src.

Comprobar la instalación de Java

Abre la terminal integrada de VS Code desde:

Terminal → New Terminal

Ejecuta:

java -version

Después:

javac -version

Si utilizas Maven, comprueba también:

mvn -version

Por ejemplo, podrías obtener:

openjdk version "11.0.x"
Apache Maven 3.x.x
Java version: 11.0.x

La versión de Java debe ser compatible con la versión de Spring Boot y la configuración de compilación de tu proyecto.

Si tu aplicación utiliza Java 11, por ejemplo, asegúrate de que VS Code utiliza un JDK compatible con Java 11.

Puedes comprobar la configuración de Java en:

Ctrl + Shift + P

Busca el comando:

Java: Configure Java Runtime

Este comando permite revisar los JDK detectados por VS Code.

Configurar el archivo launch.json

Este archivo permite definir cómo se inicia la aplicación durante la depuración.

En VS Code:

Abre el panel Run and Debug desde la barra lateral.
Selecciona create a launch.json file, si aparece.
Selecciona Java.
VS Code generará una configuración inicial.

También puedes crear manualmente la carpeta .vscode en la raíz del proyecto y, dentro de ella, el archivo launch.json.

La estructura quedaría así:

mi-proyecto/
├── .vscode/
│   └── launch.json
├── pom.xml
└── src/

Para una aplicación Spring Boot con Maven, utiliza esta configuración:

Archivo .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Debug Spring Boot",
            "request": "launch",
            "mainClass": "com.ejemplo.Application",
            "projectName": "mi-proyecto"
        }
    ]
}

Debes adaptar dos valores:

mainClass: nombre completo de la clase que contiene el método main.
projectName: nombre del proyecto Java reconocido por VS Code. Si no estás seguro de cuál es, puedes omitir esta propiedad.

Por ejemplo, si tu clase principal es:

package com.igeo.pdi;

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

@SpringBootApplication
public class IgeoPDIRabbitMSApplication {

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

Tu configuración sería:

{
    "version": "0.2.0",
    "configurations": [
        {
            "type": "java",
            "name": "Debug Spring Boot",
            "request": "launch",
            "mainClass": "com.igeo.pdi.IgeoPDIRabbitMSApplication"
        }
    ]
}

No copies el nombre del ejemplo sin comprobarlo: utiliza el nombre real de tu clase principal y su paquete Java.

Ejecutar Spring Boot en modo debug

Una vez configurado launch.json:

Abre el panel Run and Debug.
En el selector de configuraciones, elige Debug Spring Boot.
Pulsa el botón verde de inicio o presiona F5.

VS Code iniciará tu aplicación con el depurador conectado.

En la terminal o en la consola de depuración podrás ver los mensajes de inicio de Spring Boot.

Por ejemplo:

Tomcat started on port 8080
Started IgeoPDIRabbitMSApplication

Si tu aplicación utiliza otro puerto, aparecerá el correspondiente.

¿Qué ocurre cuando ejecutas F5?

VS Code inicia la aplicación Java y conecta el depurador mediante el protocolo de depuración de Java.

Esto permite detener la ejecución en determinados puntos del código e inspeccionar el estado de la aplicación.

Colocar breakpoints

Los breakpoints son puntos donde el depurador detiene temporalmente la ejecución.

Supongamos que tienes un controlador:

@RestController
@RequestMapping("/api")
public class UsuarioController {

    @GetMapping("/usuarios/{id}")
    public String obtenerUsuario(@PathVariable Long id) {

        String mensaje = "Usuario solicitado: " + id;

        return mensaje;
    }
}

Para depurar este método:

Abre UsuarioController.java.
Haz clic a la izquierda del número de línea donde aparece:
String mensaje = "Usuario solicitado: " + id;
Aparecerá un punto rojo: ese es el breakpoint.
Ejecuta la aplicación con F5.
Realiza una petición al endpoint.

Por ejemplo, si la aplicación utiliza el puerto 8080:

curl http://localhost:8080/api/usuarios/25

Cuando la ejecución llegue al breakpoint, VS Code detendrá el programa.

Podrás comprobar el valor de id, que debería ser 25.

Un breakpoint solo se activará si el código correspondiente se ejecuta. Si la petición no llega al controlador, la ejecución no se detendrá allí.

Aprender a utilizar los controles del depurador

Cuando la ejecución se detenga, aparecerán varios controles.

Acción	Tecla	Función
Continue	`F5`	Reanuda la ejecución hasta el siguiente breakpoint.
Step Over	`F10`	Ejecuta la línea actual sin entrar en los métodos invocados.
Step Into	`F11`	Entra en el método invocado cuando es posible.
Step Out	`Shift + F11`	Continúa hasta salir del método actual.
Restart	`Ctrl + Shift + F5`	Reinicia la sesión de depuración.
Stop	`Shift + F5`	Detiene la sesión de depuración.

Las combinaciones pueden variar si has personalizado los atajos de teclado.

Inspeccionar variables

Cuando el programa esté detenido, podrás consultar:

Variables: valores de las variables locales y otros datos disponibles en el contexto actual.
Watch: expresiones cuyo valor quieres supervisar.
Call Stack: cadena de métodos que condujo hasta el punto actual.
Debug Console: consola para evaluar expresiones durante la depuración.

Por ejemplo, si tienes:

BigDecimal subtotal = new BigDecimal("100.00");
BigDecimal impuesto = new BigDecimal("19.00");

BigDecimal total = subtotal.add(impuesto);

Puedes detener la ejecución y comprobar los valores de subtotal, impuesto y total.

Esto resulta especialmente útil para investigar errores en servicios, controladores, repositorios y procesos de facturación.

¿Qué ocurre si quiero depurar un método de un servicio?

Supongamos que tu aplicación tiene un controlador que llama a un servicio:

@RestController
@RequestMapping("/api")
public class FacturaController {

    private final FacturaService facturaService;

    public FacturaController(FacturaService facturaService) {
        this.facturaService = facturaService;
    }

    @GetMapping("/facturas/{id}")
    public String consultar(@PathVariable Long id) {
        return facturaService.consultarFactura(id);
    }
}

Y el servicio:

@Service
public class FacturaService {

    public String consultarFactura(Long id) {

        String resultado = "Factura: " + id;

        return resultado;
    }
}

Coloca un breakpoint en el controlador y otro en el servicio.

Al ejecutar una petición:

curl http://localhost:8080/api/facturas/100

Podrás seguir la ejecución en este orden:

La petición llega a FacturaController.
Se detiene en el breakpoint del controlador.
Presionas F11 para entrar en consultarFactura().
Inspeccionas la variable id.
Avanzas línea por línea con F10.
Compruebas el valor de resultado.
Presionas F5 para finalizar la ejecución.

Esta técnica te permite identificar exactamente dónde se produce un error.

¿Y si Spring Boot ya está ejecutándose?

Hay dos formas de depurar una aplicación Spring Boot:

Opción A. Iniciar desde VS Code

Utiliza F5 con la configuración anterior. Es la alternativa más sencilla para empezar.

Opción B. Conectarte a una aplicación ya iniciada

Si la aplicación ya se está ejecutando desde una terminal, Docker o un servidor, puedes iniciar la JVM con un puerto de depuración habilitado y configurar VS Code para conectarse a ella.

Por ejemplo, en un entorno local de desarrollo:

java \
  -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=127.0.0.1:5005 \
  -jar target/mi-aplicacion.jar

Esta configuración habilita el puerto de depuración 5005, limitado a la interfaz local.

Después, añade esta configuración a .vscode/launch.json:

{
    "type": "java",
    "name": "Attach Spring Boot",
    "request": "attach",
    "hostName": "localhost",
    "port": 5005
}

Selecciona Attach Spring Boot y pulsa F5.

Precaución: no expongas el puerto de depuración JDWP a Internet ni a redes no confiables. El acceso a este puerto puede permitir controlar la ejecución de la JVM. Para depuración remota, utiliza una conexión restringida, por ejemplo mediante SSH.

Para adaptar la configuración a tu proyecto

Quiero comprobar cómo ejecutas actualmente tu aplicación para darte una configuración que funcione directamente en tu entorno.

Una pregunta: ¿cómo ejecutas actualmente tu aplicación Spring Boot?

Desde la terminal con mvn spring-boot:run.
Desde la terminal con java -jar.
Pulsando el botón Run de VS Code.
Dentro de Docker o Kubernetes.
Todavía no consigo ejecutarla desde VS Code.

Indícame la letra correspondiente y, si puedes, la versión de Java que utiliza el proyecto. Con esos datos te indicaré la configuración específica para tu caso.