Elegir el CRUD y arrancar el servidor

Proyecto compartido. En el taller de Intermodular que abre esta semana has trabajado del repositorio vacío a una url pública. En Servidor continúas la implementación del mismo producto.

Se explica

25 minutos · explicación y demostración

De un programa Java a una aplicación web

Hasta ahora has escrito programas Java que ejecutan instrucciones desde main. Para que otra persona utilice uno de esos programas desde un navegador, necesitamos que pueda recibir peticiones y responderlas. Esa será la parte servidor, o backend, de nuestro proyecto. La parte que muestra pantallas y recoge las acciones del usuario se llama cliente o frontend.

Por ejemplo, en una aplicación de préstamos, el cliente podría mostrar un formulario para solicitar un proyector. El servidor comprobaría su disponibilidad y registraría el préstamo. Hoy empezamos por algo más pequeño: escribir una dirección en el navegador y recibir un texto producido por nuestro programa Java. Todavía no habrá formulario ni datos guardados.

El navegador y el servidor son dos programas distintos. Durante el desarrollo ambos funcionarán en tu ordenador. Más adelante, en Intermodular, publicaremos este mismo backend para acceder a él por Internet.

Qué son Spring, Spring Boot y Maven, y para qué los necesitamos

Spring es un framework de Java: un conjunto de herramientas y convenciones para construir aplicaciones. Nos proporciona, entre otras cosas, una forma de relacionar una petición web con un método Java. Así podemos centrarnos en lo que hace nuestra aplicación.

Spring Boot facilita preparar y arrancar una aplicación que utiliza Spring. Con la opción web incluye un servidor llamado Tomcat, que escucha las peticiones del navegador. «Incluido» significa que se pone en marcha junto con nuestro programa; no tenemos que instalar Tomcat por separado. Spring Boot no sustituye a Java: seguiremos escribiendo clases y métodos Java.

Para utilizar ese código de otras bibliotecas, nuestro proyecto necesita dependencias. Una dependencia es código externo que nuestra aplicación utiliza. Maven es la herramienta que descarga esas bibliotecas, compila nuestro código, ejecuta pruebas y prepara la aplicación para distribuirla. Lee lo que necesita el proyecto en un archivo llamado pom.xml. No escribimos código de la aplicación en Maven.

El proyecto incluirá Maven Wrapper: los archivos mvnw y mvnw.cmd. Permiten utilizar la versión de Maven configurada en el proyecto sin instalar Maven por separado. La primera ejecución necesita Internet para descargarla y obtener las dependencias. El JDK sí debe estar instalado.

Qué significa la dirección que vamos a abrir

Usaremos http://localhost:8080/hola. Cada parte tiene una función:

Al escribir esa dirección, el navegador envía una petición de consulta, llamada GET. En Java crearemos un método que devuelva un texto y lo asociaremos a esa ruta. A la combinación de método HTTP y ruta, como GET /hola, la llamaremos endpoint.

La respuesta contiene un estado que indica el resultado, unas cabeceras con información sobre la respuesta y un cuerpo con su contenido. Hoy reconoceremos 200 OK cuando nuestra ruta responde y 404 Not Found cuando pedimos una ruta que no hemos creado. Si el servidor está apagado, no llega ninguno de esos estados: el navegador no consigue conectarse.

En la demostración el profesor arrancará el programa, abrirá /hola y señalará el método que produce su texto. Después cambiará el texto, reiniciará y repetirá la petición. Ese es el recorrido que vas a construir, observar y explicar.

Se trabaja

140 minutos · implementación guiada sobre el proyecto propio

Al terminar tendrás el tema de tu CRUD, una aplicación que responde a tres rutas y su primera versión en GitHub. CRUD significa crear, consultar, modificar y borrar información: lo construiremos progresivamente en este mismo proyecto. Los tiempos de los pasos orientan el taller; si una comprobación falla, utiliza la ayuda de ese paso antes de continuar.

Paso 1 · Elegir un problema que tu aplicación resolverá · 15 min

1. Abre una nota y completa: «Mi aplicación la utilizará ___ para ___». Por ejemplo: «Una asociación la utilizará para organizar los préstamos de su material».
2. Enumera cuatro tipos de información que necesitarás. Los llamaremos entidades. En el ejemplo serían socios, ejemplares de material, préstamos y categorías. Escribe dos datos de cada tipo, como nombre y número de socio. Cuatro socios distintos son cuatro registros, no cuatro entidades.
3. Elige la entidad principal y describe sus cuatro operaciones CRUD con tus palabras: registrar un préstamo, consultarlo, corregirlo y eliminar un registro equivocado.
4. Anota tres reglas reales: un ejemplar no se presta dos veces a la vez, una devolución no puede preceder a la salida y un socio bloqueado no puede pedir material.
5. Describe una acción que afecte a varias cosas: prestar varios ejemplares juntos y cancelar toda la operación si alguno no está disponible. Más adelante aprenderemos cómo garantizarlo.
6. Acuerda la propuesta con el profesor. Guarda la nota para copiarla después al README, el archivo que presenta el proyecto.

Comprueba: puedes explicar quién lo usará, qué guardará y qué debe impedir. La matriz de la introducción marca la meta del trimestre; hoy no tienes que saber diseñar sus tablas ni interpretar términos como JPA o transacción.

Paso 2 · Comprobar las herramientas y preparar el editor · 15 min

1. Abre el IDE preparado para Java en clase. La terminal es su panel para escribir comandos; no es la consola del navegador. Abre ese panel desde el menú de terminal del IDE.
2. Escribe los siguientes comandos, uno cada vez, y pulsa Intro después de cada uno:

java -version
javac -version
git --version

3. Comprueba que java y javac muestran Java 21 o una versión compatible posterior. javac es el compilador: si solo funciona java, la preparación del JDK está incompleta. Si un comando «no se reconoce», resuelve la instalación o configuración con el profesor antes de generar el proyecto.
4. Crea una carpeta de trabajo, por ejemplo Documentos/DAW. Abre GitHub en el navegador e inicia sesión con tu cuenta; todavía no crees otro repositorio si ya tienes uno para este proyecto en Intermodular.

Comprueba: funcionan los tres comandos y sabes dónde guardarás el proyecto. No necesitas ejecutar mvn: utilizaremos el wrapper que se descargará con él.

Si trabajas con Visual Studio Code

Visual Studio Code recién instalado no sabe nada de Java. Abre los archivos y los colorea, pero no compila, no te avisa de errores y no tiene ningún botón para arrancar la aplicación. Todo eso lo aportan dos extensiones, y sin ellas los pasos siguientes no te van a funcionar. Puede que en el equipo del aula ya estén puestas; míralo igualmente, que cuesta un minuto.

1. Pulsa Ctrl+Shift+X (en macOS, Cmd+Shift+X) o el icono de las piezas de puzle en la barra lateral.
2. Busca Extension Pack for Java, de Microsoft, y pulsa Install. No es una extensión sino seis: el lenguaje, el depurador, las pruebas, Maven, el explorador de proyectos y las sugerencias de código.
3. Busca Spring Boot Extension Pack y pulsa Install. Añade el autocompletado de application.properties y el panel desde el que se arrancan las aplicaciones Spring.
4. Si aparece un aviso pidiendo recargar la ventana, recárgala.

Comprueba: buscando cada uno de los dos en el panel de extensiones, el botón ya no dice Install sino que aparecen como instalados. Todavía no vas a ver ningún proyecto Java por ninguna parte, y es normal: aún no has abierto ninguno. Eso llega en el paso 3.

Si trabajas con IntelliJ

Sáltate este apartado entero: IntelliJ trae de serie el soporte de Java y de Maven. Lo único que tendrás que hacer es confirmar el JDK 21 cuando abras el proyecto en el paso 3.

Paso 3 · Generar la estructura inicial y abrirla · 20 min

Spring Initializr es una web que genera los archivos iniciales de un proyecto Spring Boot. No aloja tu aplicación ni escribe las reglas de tu CRUD.

1. Abre Spring Initializr y localiza los campos Project, Language, Dependencies y los datos del proyecto. Esas elecciones determinan los archivos que contendrá el ZIP.
2. Para realizar el taller, descarga la plantilla inicial del curso: gestor con Spring Boot 3.5.16. Contiene la estructura generada y ajustada a la serie 3.5 que utiliza el módulo, todavía sin controladores. La descarga fija las versiones para que los cambios de Initializr no cambien las bibliotecas a mitad del curso. Estos son sus valores; no tienes que volver a seleccionarlos en la web:

Usamos gestor como nombre técnico para que las rutas de archivos de estos primeros pasos coincidan en clase. El nombre público y el tema de tu aplicación quedan en el README. La configuración puede contrastarse con la guía oficial de Spring Boot 3.5.

3. Extrae el ZIP del curso en la carpeta de trabajo. No abras el código dentro del ZIP.
4. En el IDE elige Abrir carpeta/proyecto y selecciona la carpeta que contiene pom.xml, no la carpeta src. Si pregunta cómo importarlo, elige Maven. Espera a que termine la descarga de dependencias.

En Visual Studio Code es Archivo → Abrir carpeta, y después pasan tres cosas que conviene no despachar a golpe de Intro:

• Sale un aviso preguntando si confías en los autores de los archivos de esa carpeta. Responde que sí. Si dices que no, el editor entra en modo restringido, Java se queda apagado y nada de lo que viene después va a funcionar.
• Abajo a la derecha aparece un aviso de que está importando el proyecto Maven, con una barra de progreso. La primera vez tarda un rato largo: está descargando Spring entero. Déjalo terminar antes de tocar nada.
• En el explorador de archivos, abajo del todo, aparece una sección nueva, JAVA PROJECTS, con gestor dentro. Ésa es la señal de que la importación ha ido bien.

Ahora que el proyecto está abierto, mira qué Java está usando el editor: Ctrl+Shift+P, escribe Java: Configure Java Runtime y ábrelo. Se abre una pestaña con las versiones detectadas y tiene que aparecer 21. Que java -version funcionara en la terminal del paso 2 no significa que el editor use esa misma; son dos cosas que se configuran por separado, y es el fallo que más tiempo hace perder en esta sesión.

Comprueba: ves pom.xml, src, mvnw y mvnw.cmd. Si el IDE muestra otra carpeta gestor dentro, entra en ella: la raíz del proyecto es donde está pom.xml.

Lo que te puedes encontrar en Visual Studio Code, y qué significa

No aparece la sección JAVA PROJECTS, o está vacía. O has abierto una carpeta que no contiene pom.xml, o dijiste que no confiabas en los autores. Cierra la carpeta, vuelve a abrirla y esta vez confía.

Abajo a la derecha pone «Java: Lightweight Mode», o ves un rayo. Es un modo reducido en el que Visual Studio Code lee el código pero no lo compila. Pulsa encima y elige Switch to Standard. Hasta que no esté en modo estándar no vas a tener ni errores marcados ni botón para arrancar.

Los import org.springframework... salen subrayados en rojo. Casi siempre es que todavía está descargando las bibliotecas; abajo verás la barra de progreso. Espera a que acabe. Si termina y siguen en rojo, Ctrl+Shift+P → Java: Clean Java Language Server Workspace y acepta reiniciar.

Dice «The JAVA_HOME environment variable is not defined correctly». El editor no encuentra el JDK. Abre Java: Configure Java Runtime y mira qué versiones detecta; si no sale ninguna, avisa antes de seguir.

Paso 4 · Localizar el código y entender el primer arranque · 15 min

Antes de editar, comprueba que el IDE utiliza el JDK 21 también para este proyecto: que java -version funcione en la terminal no configura automáticamente el compilador del IDE. Abre los archivos de la tabla y señala cuál contiene Java, cuál configura Maven y cuál configura la aplicación. No copies el bloque de GestorApplication si ese archivo ya coincide con la plantilla: se muestra para leerlo y entenderlo.

La clase de arranque tendrá esta forma:

package com.ejemplo.gestor;

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

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

main sigue siendo el punto de entrada que conoces. Su llamada a SpringApplication.run pone en marcha Spring Boot. Una anotación es una marca que empieza por @ y aporta información sobre el código: aquí @SpringBootApplication identifica la configuración de arranque. Conserva este archivo; el controlador irá en otro.

Comprueba: puedes señalar dónde se inicia el programa y dónde se declaran sus dependencias. Todavía no hay ninguna ruta /hola: la crearemos en el paso 6.

Paso 5 · Arrancar y reconocer una aplicación que escucha · 15 min

1. Abre la terminal del IDE en la carpeta de pom.xml. Comprueba su ubicación con pwd y lista los archivos con ls; ambos comandos funcionan también en PowerShell. Si no ves pom.xml, cambia a la carpeta correcta antes de seguir.
2. En Windows con PowerShell, ejecuta:

.\mvnw.cmd spring-boot:run

En Linux o macOS, el mismo paso se escribe:

./mvnw spring-boot:run

El primer fragmento llama al wrapper de Maven de esta carpeta. spring-boot:run le pide ejecutar la aplicación. Si Linux o macOS dice que no tienes permiso para ejecutar el archivo, aplica chmod +x mvnw y repite el comando.

Con las extensiones instaladas aparecen controles para esta operación: encima del método main aparecen las palabras Run | Debug, y el panel de Spring Boot arranca la aplicación con un play. Hacen lo mismo. En esta sesión se lanza desde la terminal para que la salida sea idéntica para todo el grupo y pueda aprenderse a interpretarla; a partir de la sesión 2 usa el botón si prefieres.

3. Espera a que aparezcan mensajes que contengan Tomcat started on port 8080 y Started GestorApplication. El texto alrededor puede variar. La terminal queda ocupada porque el servidor sigue funcionando: no es un bloqueo.
4. Abre http://localhost:8080/ en el navegador. Aparecerá una respuesta de error, normalmente una página Whitelabel Error Page con estado 404. Has llegado al servidor, pero todavía no has programado qué debe devolver la ruta /.

Si otro servicio necesita el puerto 8080, escribe server.port=8081 en application.properties, reinicia y usa 8081 en las direcciones de la práctica. Regístralo en el README.

Comprueba: distingues «el programa ha arrancado» de «existe la ruta que he pedido».

Paso 6 · Crear una ruta que devuelva un texto · 20 min

Un controlador es una clase que agrupa métodos para atender peticiones. Vamos a crear uno dentro del paquete base que Spring Boot revisa al arrancar.

1. En src/main/java/com/ejemplo/gestor, crea la carpeta o paquete controller desde el IDE. Dentro crea la clase HolaController. Su archivo debe quedar en src/main/java/com/ejemplo/gestor/controller/HolaController.java.
2. Escribe la clase completa:

package com.ejemplo.gestor.controller;

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

@RestController
public class HolaController {
    @GetMapping("/hola")
    public String hola() {
        return "Hola, mundo. Te responde mi servidor.";
    }
}

3. Relaciona cada parte con su función: package coincide con la ubicación; los import permiten usar las anotaciones; @RestController indica que los resultados de los métodos se envían como respuesta; @GetMapping("/hola") asocia un GET a esa ruta; return proporciona el cuerpo de la respuesta. El nombre del método Java no determina la URL.
4. Guarda el archivo. En la terminal donde corre el servidor pulsa Ctrl+C, espera a que vuelva el indicador para escribir y ejecuta otra vez el comando de arranque. No hemos añadido recarga automática: editar y refrescar el navegador no basta para ejecutar el código nuevo.
5. Abre http://localhost:8080/hola. Debes leer exactamente la frase de return.
6. Cambia la frase por una que presente tu aplicación, guarda, reinicia y recarga. Comprueba que cambia la respuesta.

Si obtienes 404, revisa la ruta letra a letra, el reinicio y que HolaController esté bajo com.ejemplo.gestor. Si el IDE marca un error de Java, corrígelo antes de arrancar; no hace falta cambiar el navegador.

Comprueba: puedes recorrer navegador → ruta → método Java → texto de respuesta y señalar tu archivo en ese recorrido.

Paso 7 · Ver tu propia petición en el navegador · 15 min

Las herramientas de desarrollo del navegador permiten observar las peticiones. Vamos a inspeccionar solo la que acabas de crear, cuyo resultado ya conoces.

1. Con /hola abierto, pulsa F12 o abre el menú del navegador → Herramientas de desarrollo. Elige la pestaña Red o Network.
2. Deja seleccionado Todo/All y recarga con Ctrl+R. El panel registra lo que se solicita mientras está abierto; por eso hay que recargar después de abrirlo.
3. Pulsa la fila cuya dirección acaba en /hola. Puede aparecer además favicon.ico, el icono de la pestaña: no es nuestra petición y puedes ignorarlo.
4. En Cabeceras/Headers, busca URL, método GET y estado 200. Localiza Content-Type entre las cabeceras de respuesta: describe el tipo de contenido. En Respuesta/Response, lee el texto de tu método.
5. Abre /ruta-que-no-existe, selecciona su fila y observa el 404. Después detén tu servidor y recarga: ahora verás un fallo de conexión, sin respuesta HTTP. Arranca de nuevo y vuelve a /hola para dejarlo funcionando.

Guarda estas observaciones en una tabla provisional; la incorporarás al repositorio en el paso 9:

Comprueba: sabes localizar método, dirección, estado, cabeceras y cuerpo sin confundirlos con el código Java.

Paso 8 · Aplicar el patrón a tu proyecto · 10 min

1. En HolaController, debajo del método hola y antes de la última llave de la clase, añade:

@GetMapping("/estado")
public String estado() {
    return "Servidor en funcionamiento";
}

@GetMapping("/prestamos/resumen")
public String resumen() {
    return "Esta aplicación gestionará los préstamos de material";
}

2. Cambia prestamos y el texto del segundo método por el recurso principal de tu tema, por ejemplo /reservas/resumen. La respuesta describe el proyecto: todavía no cuenta datos ni consulta una base de datos.
3. Guarda, reinicia y abre las dos direcciones completas en el navegador. Anota en tu tabla sus estados y textos.

Comprueba: responden tres rutas diferentes y sabes qué método atiende cada una. No copies otra clase completa dentro de HolaController: aquí estás añadiendo dos métodos a la clase existente.

Paso 9 · Guardar la primera versión en GitHub · 25 min

Un repositorio guarda los archivos y su historial. Un commit registra una versión local; push envía los commits a GitHub. Es el mismo repositorio que utilizaremos en Intermodular para practicar el flujo de trabajo y el despliegue.

Si ya has hecho la primera sesión de Intermodular, estos comandos los has visto con el portfolio. Lo único distinto es que aquí el proyecto ya existe en tu ordenador antes que en GitHub, y por eso se empieza con git init en lugar de con git clone.

1. En la carpeta de pom.xml, abre el README.md de la plantilla. Completa la propuesta del paso 1, revisa el comando de arranque y añade tus tres rutas.
2. Revisa la tabla de comprobaciones de los pasos 7 y 8. Debe indicar la petición, la respuesta observada y cualquier dificultad pendiente. Explica qué parte de la aplicación produce cada respuesta.
3. Abre .gitignore, el archivo que indica a Git qué no debe subir. Comprueba que excluye target/ (archivos generados al compilar), la configuración local del IDE y .env si lo utilizas más adelante. Conserva los archivos del wrapper, incluidos .mvn/, mvnw y mvnw.cmd.

Si aún no hay repositorio del proyecto, crea uno vacío en GitHub con el botón New repository. No añadas allí README ni .gitignore: ya existen en tu ordenador. Copia su dirección HTTPS. En la terminal del proyecto, ejecuta cada comando por separado:

git init -b main
git status
git add .gitignore README.md pom.xml mvnw mvnw.cmd .mvn src
git diff --cached --stat

init crea el repositorio local, status muestra los cambios, add prepara los archivos para la versión y diff --cached --stat resume lo preparado. Revisa que aparezcan el código y la documentación, sin target/ ni credenciales. Después crea el commit:

git commit -m "Completar sesión 01: primera aplicación servidor"

Si Git pide identidad, configura tu nombre y correo de autor con git config user.name "Tu nombre" y git config user.email "Tu correo de autor", sustituyendo ambos textos por tus datos, y repite el commit.

Conecta el repositorio y sube la versión. Sustituye la dirección siguiente por la que copiaste de GitHub:

git remote add origin https://github.com/TU_USUARIO/TU_REPOSITORIO.git
git push -u origin main

Completa el inicio de sesión que solicite Git. La guía de GitHub para subir código local desarrolla este procedimiento.

Si ya hay repositorio en Intermodular, utiliza su carpeta clonada. Sitúa allí el proyecto sin copiar otra carpeta .git; conserva el README existente y complétalo. No repitas git init ni git remote add: guarda y publica los cambios mediante las ramas y revisiones establecidas en ese módulo.

Comprueba en GitHub: abre el README y el controlador. Contrasta su contenido con tu copia local y localiza en el historial el cambio que acabas de guardar. Debes poder recuperar esa versión del proyecto.

Cierre

15 minutos · resultado comprobable y explicación individual

Al terminar la sesión:

Con tu proyecto abierto, explica para qué utilizas Spring Boot y Maven, señala el método que atiende una de tus rutas y reproduce una respuesta correcta y un 404. Explica qué cambia si detienes el programa. Comprueba también que tu propuesta tiene las entidades y reglas necesarias para seguir ampliándola durante el trimestre.