13. Servicios web
Requisitos previos: la versión 9 de la aplicación [Tax], presentada al final de este capítulo, reutiliza los módulos [tax-dao], [tax-business], and [tax-ui] de la versión 5 (capítulo 6). Antes de compilar o abrir sus proyectos, debe haber instalado la versión 5 en el repositorio Maven local con el comando [mvn install] ingresado en la carpeta [06-architectures/TaxV5] (consulte el capítulo 6, sección sobre [mvn install]).
13.1. Introducción
En el capítulo anterior presentamos varias aplicaciones cliente/servidor TCP/IP. Como los clientes y el servidor intercambian líneas de texto, pueden escribirse en cualquier lenguaje. El cliente solo necesita conocer el protocolo de comunicación que espera el servidor.
Los servicios web también son aplicaciones de servidor (TCP/IP). Tienen las siguientes características:
- están alojados en servidores web, y el protocolo de intercambio cliente/servidor es HTTP (HyperText Transfer Protocol), un protocolo construido sobre TCP/IP, que exploramos en el capítulo anterior;
- el servicio web tiene un protocolo de comunicación estándar, independientemente del servicio prestado. Un servicio web ofrece diversos servicios: S1, S2…, Sn. Cada uno de ellos espera parámetros proporcionados por el cliente y devuelve un resultado al cliente. Para cada servicio, el cliente necesita saber:
- cómo especificar el servicio Si;
- la lista de parámetros que debe proporcionar y sus tipos;
- el tipo de resultado que devuelve el servicio. Una vez conocidos estos elementos, el diálogo cliente/servidor sigue el mismo formato, sin importar qué servicio web se consulte. El código del cliente queda así estandarizado;
- para protegerse de los ataques provenientes de Internet, muchas organizaciones abren hacia el exterior solo ciertos puertos de sus servidores: principalmente los puertos 80 (HTTP) y 443 (HTTPS) para el servicio web. Todos los demás puertos están bloqueados. En consecuencia, las aplicaciones cliente/servidor como las descritas en el capítulo anterior suelen quedar limitadas a la red privada de la organización (intranet). Alojar un servicio en un servidor web lo hace accesible a toda la comunidad de Internet;
- el servicio web puede verse como un objeto remoto: los servicios que ofrece se convierten entonces en métodos de ese objeto. Un cliente puede usar este objeto remoto como si fuera local, a través de un objeto intermediario llamado proxy, que oculta toda la comunicación de red. Esto permite construir un cliente independiente de esta capa: si la capa cambia, no es necesario modificar el resto del cliente;
- al igual que en las aplicaciones cliente/servidor TCP/IP del capítulo anterior, el cliente y el servidor pueden escribirse en cualquier lenguaje de programación. Intercambian líneas de texto formadas por dos partes: los encabezados requeridos por el protocolo HTTP y el cuerpo del mensaje, cuyo formato se acuerda entre el cliente y el servidor.
La arquitectura de una aplicación cliente/servidor basada en servicios web es la siguiente:

Es una extensión de la arquitectura en capas del capítulo 6, a la que se agregan capas especializadas de comunicación de red: el cliente del servicio web del lado del cliente y el propio servicio web del lado del servidor. Ya nos encontramos con una arquitectura similar en el servidor TCP de cálculo del impuesto (versión 8) del capítulo anterior.
13.1.1. Ayer: SOAP y WSDL
En la década de 2000, los servicios web seguían con mayor frecuencia el estándar SOAP (Simple Object Access Protocol). El cliente enviaba una solicitud HTTP POST, cuyo cuerpo era un documento XML: un “sobre” que contenía el nombre del método invocado y sus parámetros. El servidor respondía con otro sobre XML que contenía el resultado. Cada servicio se describía mediante un documento XML en formato WSDL (Web Services Description Language), disponible en la URL del servicio seguida de [?wsdl]: enumeraba los métodos, sus parámetros y sus tipos. A partir de este documento, ciertas herramientas generaban automáticamente el proxy del servicio.
En Java, estos servicios se escribían con la API JAX-WS: una clase anotada con [@WebService], cuyos métodos públicos (que podían anotarse con [@WebMethod]) se convertían en los métodos del servicio; la herramienta [wsimport] generaba el proxy del cliente a partir del WSDL. JAX-WS formó parte del JDK desde Java 6 hasta Java 10; se eliminó en Java 11 (JEP 320) y ahora existe fuera del JDK, con el nombre Jakarta XML Web Services. Todavía se encuentra en aplicaciones heredadas, pero los servicios nuevos rara vez lo usan. Entre las razones de este abandono están lo engorroso de los sobres XML y SOAP, la complejidad de los estándares asociados (WS-Security, WS-Addressing, etc.) y la dificultad de invocar estos servicios desde un navegador.
13.1.2. Hoy: REST y JSON
La mayoría de los servicios web actuales siguen el estilo REST (REpresentational State Transfer) e intercambian documentos JSON (JavaScript Object Notation, presentado en el capítulo 5). El estilo REST se basa en los siguientes principios:
- el servicio expone recursos, cada uno designado por una URL: [/tax], [/clients/12], [/clients/12/orders];
- se accede a estos recursos mediante los métodos (también llamados verbos) del protocolo HTTP, cada uno de los cuales tiene un significado específico;
- el resultado de la acción se indica mediante el código de estado HTTP de la respuesta;
- el cuerpo de las solicitudes y las respuestas es, con mayor frecuencia, un documento JSON, más compacto y simple que XML;
- el servicio es sin estado: cada solicitud contiene toda la información necesaria para su procesamiento; el servidor no almacena ninguna información de una solicitud a la siguiente para un cliente determinado.
Los métodos HTTP más utilizados son los siguientes:
Método | Uso | Ejemplo |
GET | Leer un recurso; los parámetros, si los hay, van en la URL | GET /clients/12 |
POST | Crear un recurso o solicitar un procesamiento; los datos van en el cuerpo de la solicitud | POST /clients |
PUT | Reemplazar un recurso | PUT /clients/12 |
PATCH | Modificar parte de un recurso | PATCH /clients/12 |
DELETE | Eliminar un recurso | DELETE /clients/12 |
Los códigos de estado, que se presentaron en el capítulo anterior, adquieren aquí todo su significado:
Código | Significado |
200 OK | La solicitud tuvo éxito; el cuerpo de la respuesta contiene el resultado |
201 Created | El recurso fue creado; el encabezado [Location] proporciona su URL |
204 No Content | La solicitud tuvo éxito; la respuesta no tiene cuerpo |
400 Bad Request | La solicitud no es válida (parámetro ausente o no válido, etc.) |
404 Not Found | El recurso solicitado no existe |
415 Unsupported Media Type | No se acepta el tipo del documento enviado (encabezado [Content-Type]) |
500 Internal Server Error | Ocurrió un error inesperado en el servidor |
Un servicio REST no tiene un equivalente obligatorio de WSDL. Sin embargo, es una práctica habitual describirlo mediante un documento OpenAPI (antes Swagger), en formato JSON o YAML, a partir del cual las herramientas pueden generar documentación, páginas de prueba y clientes. Volveremos sobre esto más adelante.
Por último, cabe mencionar gRPC, diseñado por Google: los métodos del servicio y sus mensajes se describen en un archivo [.proto], a partir del cual las herramientas generan el servidor y el cliente, tal como se hacía en la época de WSDL; los mensajes se codifican en un formato binario compacto (Protocol Buffers) y se transmiten mediante HTTP/2. gRPC es muy eficiente y popular para la comunicación entre servicios dentro de una misma organización, pero no es adecuado para los navegadores. Está disponible en Java con la biblioteca [grpc-java], que no utilizaremos.
13.1.3. Spring Boot y Spring MVC
Para escribir nuestros servicios web, usaremos Spring Boot. En el capítulo 6 usamos el contenedor de inyección de dependencias de Spring Framework. Este framework también incluye un módulo web, Spring MVC, que asocia una URL y un método HTTP con un método Java mediante anotaciones: [@RestController] en la clase, [@GetMapping], [@PostMapping]… en sus métodos. Spring Boot (versión 1.0 en 2014, versión 4 en noviembre de 2025, con Spring Framework 7) simplifica la puesta en marcha de Spring:
- se configura automáticamente la aplicación según las bibliotecas disponibles: si están presentes Spring MVC y Jackson, prepara todo lo necesario para un servicio web JSON, sin una sola línea de configuración;
- se integra el servidor web en la aplicación: el servidor Tomcat (versión 11) es simplemente una biblioteca, lanzada por el programa principal. Por lo tanto, no es necesario instalar un servidor web o un servidor de aplicaciones aparte (Tomcat, GlassFish, WildFly…), en el cual antes se desplegaba la aplicación como un archivo [.war];
- ofrece starters: dependencias Maven que agrupan todo lo necesario para un caso de uso específico. El starter [spring-boot-starter-webmvc] incluye Spring MVC, Tomcat, Jackson 3 (capítulo 5) y el registro de eventos (SLF4J y Logback);
- proporciona un proyecto padre Maven, [spring-boot-starter-parent], que especifica las versiones de todas estas bibliotecas (compatibles entre sí) y un plugin de Maven, [spring-boot-maven-plugin], que lanza la aplicación ([mvn spring-boot:run]) y la empaqueta como un único archivo ejecutable, [.jar].
Spring Boot no es la única solución: Jakarta EE (anteriormente Java EE) define el estándar de API JAX-RS (Jakarta RESTful Web Services), y frameworks como Quarkus, Micronaut y Helidon también se usan ampliamente. Spring Boot es, sin embargo, el más extendido, y se apoya de forma natural en lo que vimos en el capítulo 6.
13.2. Un primer servicio web
Vamos a construir nuestra primera aplicación cliente/servidor con la siguiente arquitectura simplificada:

Los proyectos de este capítulo son proyectos Maven, agrupados en la carpeta [13-web-services]:
Los proyectos ya están configurados en los materiales del curso: el lector solo debe abrir la carpeta [13-web-services] en su IDE (IntelliJ, IDEA o VS Code), o ir a la carpeta de un proyecto e ingresar el comando Maven indicado. Los servicios se lanzan con [mvn spring-boot:run], y los clientes de consola con [mvn compile exec:java]. El archivo [pom.xml] ubicado en la raíz de la carpeta no es un proyecto padre: simplemente enumera los seis proyectos dentro de una etiqueta [<modules>], lo que permite compilarlos todos a la vez (escribiendo [mvn compile] en la carpeta [13-web-services]).
Para crear usted mismo un proyecto Spring Boot, la forma más sencilla es usar el sitio web Spring Initializr: allí se selecciona Maven, Java, la versión de Spring Boot, el nombre del proyecto y sus dependencias (en este caso, “Spring Web”), y luego se descarga un archivo ZIP que contiene un proyecto listo para usar: el archivo [pom.xml], la clase principal y el archivo [application.properties]. IntelliJ, IDEA y VS Code (con la extensión “Spring Boot Extension Pack”) ofrecen el mismo asistente.
13.2.1. El lado del servidor

El archivo [pom.xml] del proyecto [WsHello] es el siguiente:
Comentarios:
- líneas 9–14: el proyecto hereda del proyecto padre de Spring Boot, [spring-boot-starter-parent], descargado como dependencia desde Maven Central (la etiqueta vacía [<relativePath/>] indica que no debe buscarse en la carpeta padre). Este proyecto padre especifica las versiones de varios cientos de bibliotecas y configura los plugins de Maven. Por eso las dependencias y el plugin de las líneas 28–31 y 48–51 no tienen la etiqueta [<version>]: su versión es la elegida por Spring Boot 4.1.1;
- línea 21: la propiedad [java.version] es la que usa el proyecto padre para configurar el compilador; la línea 22 la duplica, en consonancia con los demás proyectos del curso;
- líneas 28–31: la única dependencia del proyecto es el starter web. Proporciona Spring MVC (Spring Framework 7.0), el servidor Tomcat 11 integrado, Jackson 3 y el registro de eventos;
- línea 41: la opción del compilador [-parameters], que conserva los nombres de los parámetros de los métodos en los archivos [.class]. Spring la necesita para asociar un parámetro de método ([name]) con el parámetro del mismo nombre en una URL. El proyecto padre ya habilita esta opción; la incluimos aquí para que sea visible;
- líneas 48–51: el plugin de Spring Boot. [mvn spring-boot:run] compila y ejecuta la aplicación; [mvn package] crea un archivo [target/ws-hello-1.0.jar] que contiene la aplicación y todas sus dependencias, el cual se ejecuta luego con [java -jar target/ws-hello-1.0.jar].
La clase principal es la siguiente:
- línea 7: la anotación [@SpringBootApplication] combina tres anotaciones: [@Configuration] (la clase puede definir beans, como en el capítulo 6), [@EnableAutoConfiguration] (configuración automática según las bibliotecas disponibles) y [@ComponentScan] (Spring busca clases anotadas, como controladores, configuraciones, etc., en el paquete de esta clase y en sus subpaquetes);
- línea 10: aquí conservamos la forma estándar de los métodos [main] y [public static] , con la cual las herramientas de Spring Boot buscan la clase principal;
- línea 12: [SpringApplication.run] lee la configuración (archivo [application.properties], variables de entorno, argumentos de línea de comandos), crea el contenedor Spring y sus beans, inicia el servidor Tomcat y luego devuelve el control. Sin embargo, el programa no se detiene ahí: los hilos de Tomcat esperan solicitudes hasta que se termina la aplicación (Ctrl-C).
La configuración de la aplicación se almacena en el archivo [src/main/resources/application.properties]:
- línea 2: el nombre de la aplicación;
- línea 4: el servidor escucha en el puerto 5100 (8080 de forma predeterminada). Este valor también puede pasarse como argumento: [mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=5100], o mediante la variable de entorno [SERVER_PORT];
- línea 6: de forma predeterminada, Spring Boot muestra al iniciar un gran banner con texto ASCII; lo eliminamos;
- línea 8: el formato de los mensajes de registro. El formato predeterminado es muy completo (fecha, nivel, ID del proceso, nombre de la aplicación, hilo, nombre completo de la clase, mensaje), pero produce líneas muy largas. Lo reducimos a la hora, el nivel del mensaje, el nombre del hilo, el nombre corto de la clase emisora ([%logger{0}]) y el mensaje.
El servicio web propiamente dicho es la clase [HelloController]. Proporciona un método que devuelve la cadena [Hello Mrs xx], donde xx es el nombre recibido:
Comentarios:
- línea 8: la anotación [@RestController] designa la clase como un controlador: Spring crea una única instancia (un singleton) al iniciarse y le asigna las solicitudes HTTP cuya URL corresponde a uno de sus métodos. El resultado de cada método se envía tal cual al cliente, en el cuerpo de la respuesta;
- líneas 12–15: la anotación [@GetMapping("/")] asocia los métodos HTTP y GET con la URL and [/] (la raíz del sitio) y con el método [home], que devuelve un texto que explica cómo usar el servicio;
- Líneas 20–23: la URL de la plantilla (conocida como ruta) [/hello/{name}] contiene una variable [{name}]: corresponde a cualquier segmento de la URL que viene después de [/hello/]. Así, la URL [/hello/Carla%20Bruni] asigna el valor [Carla Bruni] a [{name}] (el código [%20] representa un espacio en una URL). La anotación [@PathVariable] (línea 21) indica a Spring que pase este valor al parámetro del método con el mismo nombre: esto es el enlace de datos (data binding). El método devuelve una cadena: se envía tal cual al cliente como un documento de texto (tipo [text/plain]);
- líneas 26–29: el mismo proceso, pero el método devuelve un objeto de tipo [Greeting]. Spring lo serializa a JSON mediante Jackson (capítulo 5) y lo envía al cliente como un documento de tipo [application/json]. Este es el formato estándar de la respuesta de un servicio web REST;
- líneas 32–33: el tipo del resultado, un record (capítulo 4), declarado dentro del controlador. Jackson sabe serializar records: cada componente se convierte en una propiedad JSON con el mismo nombre.
El servicio se inicia con el comando [mvn spring-boot:run], ejecutado en la carpeta del proyecto. Muestra su registro (en el curso se abrevian las rutas de la línea 2 con [...]):
- línea 2: el inicio de la aplicación, la versión de Java y el directorio de ejecución, que es el directorio del proyecto;
- línea 3: Spring permite definir perfiles (desarrollo, pruebas, producción, etc.) que activan configuraciones diferentes (archivos [application-dev.properties], etc.). Aquí no hay ningún perfil activo;
- líneas 4–6: se crea el servidor Tomcat embebido; escuchará en el puerto 5100;
- línea 7: el contenedor de Spring está listo: ha creado sus beans, entre ellos nuestro controlador;
- líneas 8–9: Tomcat ya acepta conexiones; la aplicación está lista. El inicio tardó unos diez segundos en nuestra máquina de pruebas, lo cual es bastante lento; normalmente tarda dos o tres segundos;
- líneas 10–12: estos mensajes aparecieron durante la primera solicitud: el servlet de Spring [DispatcherServlet], que recibe todas las solicitudes y las distribuye entre los métodos de los controladores, solo se inicializa en este momento. Un servlet es un componente Java que procesa solicitudes en un servidor web como Tomcat (Jakarta Servlet); Spring está construido sobre él. El nombre del hilo, [http-nio-5100-exec-1], indica que la solicitud es procesada por uno de los hilos del servidor Tomcat;
- líneas 13–14: estos mensajes aparecieron cuando se detuvo el servidor con Ctrl-C, después de las pruebas descritas en los párrafos siguientes; el apagado fue “ordenado” (graceful): Tomcat termina las solicitudes pendientes antes de cerrarse.
Cada mensaje del registro indica su hora, su nivel ([TRACE], [DEBUG], [INFO], [WARN], [ERROR]), el hilo que lo emitió y la clase emisora. Los mensajes de nivel [INFO] y superiores se muestran de forma predeterminada; la propiedad [logging.level.<package>=DEBUG] también muestra los mensajes de nivel inferior de un paquete determinado.
13.2.2. Consulta del servicio con curl
Mientras el servicio está en ejecución, lo consultamos desde una segunda ventana de comandos con la herramienta [curl] presentada en el capítulo anterior. La opción [-i] muestra los encabezados de la respuesta antes del cuerpo, y la opción [-s] (silencioso) suprime la barra de progreso:
- Línea 2: la solicitud tuvo éxito. Tomcat no envía el texto que suele seguir al código de estado ([OK]): es opcional desde HTTP/1.1 (y ya no existe en HTTP/2); solo importa el código;
- Línea 3: el documento es texto (UTF-8);
- línea 4: el tamaño del documento, en bytes;
- línea 5: la hora de la respuesta, siempre expresada en Tiempo Universal Coordinado (GMT) en los encabezados HTTP, mientras que el registro del servidor usa la hora local;
- línea 7: el resultado del método [hello].
Ahora solicitemos la versión JSON:
- línea 3: el documento ahora es de tipo [application/json]. No es necesario especificar el juego de caracteres: un documento JSON intercambiado por la red siempre está codificado en UTF-8 (RFC 8259);
- Línea 7: el objeto [Greeting] serializado. Las propiedades JSON [name] y [message] corresponden a los nombres de los componentes del record. Como los nombres en Java ya están en formato “camelCase”, y el uso es en JavaScript y JSON, no hay nada que convertir.
Una URL que no corresponde a ninguna ruta devuelve una respuesta 404:
- Línea 4: el documento se envía en fragmentos (chunks), cada uno precedido por su tamaño; el servidor no tuvo que calcular el tamaño total del documento antes de empezar a enviarlo;
- línea 7: el documento de error generado por Spring Boot: la fecha, el código de estado, su texto y la ruta solicitada. Por razones de seguridad, no contiene ni el mensaje de una eventual excepción ni la pila de llamadas (propiedades [server.error.include-message] y [server.error.include-stacktrace], deshabilitadas de forma predeterminada). Veremos en el siguiente servicio cómo obtener un documento de error estandarizado.
También puede escribir la URL [http://localhost:5100/hello/Carla Bruni] en la barra de direcciones de un navegador, que mostrará el texto recibido: un servicio web consultado mediante GET se puede probar muy fácilmente.
13.2.3. Un cliente de consola

Es posible escribir el cliente del servicio con un simple cliente TCP, como en el capítulo anterior: basta con enviar la solicitud HTTP y leer la respuesta. Sin embargo, usamos la clase [java.net.http.HttpClient] (Java 11), también presentada en el capítulo anterior, que gestiona el protocolo HTTP por nosotros y usa Jackson para los documentos JSON. El proyecto [ClientWsHello] es un proyecto Maven estándar, cuyo archivo [pom.xml] declara la dependencia de Jackson y la clase principal:
Su código es el siguiente:
Comentarios:
- Líneas 16–18: la respuesta del servicio, en JSON, se deserializará en un objeto [Greeting]. El cliente no tiene acceso al tipo [Greeting] del servidor; declara el suyo propio, con los mismos nombres de componentes. Un cliente no comparte el código del servidor, solo el formato de los documentos intercambiados;
- línea 22: la URL del servicio se pasa como argumento o, en su defecto, toma el valor predeterminado [http://localhost:5100/]: si cambia la dirección del servicio, no es necesario recompilar el cliente;
- línea 24: el convertidor JSON de Jackson 3 (capítulo 5);
- línea 27: un único [HttpClient] para todo el programa. Gestiona un conjunto de conexiones reutilizables y debe compartirse, no recrearse para cada solicitud. A partir de Java 21, [HttpClient] implementa [AutoCloseable]: la instrucción [try] con recurso lo cierra al final del programa;
- línea 37: el nombre ingresado pasa a ser un segmento de la URL: los caracteres no permitidos en ella deben codificarse. [URLEncoder.encode] codifica la “é” como [%C3%A9], pero está pensado para parámetros de formulario, donde el espacio se codifica como [+]. En la ruta de una URL, el espacio debe codificarse como [%20]: por eso reemplazamos el [+] (un [+] válido ingresado se codifica como [%2B] y no se ve afectado);
- línea 39: el método [resolve] de la clase [URI] construye una URL a partir de la URL base y una URL relativa. Nota: la URL base debe terminar en [/] para que [hello/...] se le agregue;
- líneas 42–43: la respuesta JSON se deserializa en un objeto [Greeting] mediante el método [readValue] de Jackson;
- líneas 45–47: la excepción [ConnectException] se lanza cuando es imposible conectarse al servicio, por ejemplo, cuando ningún servicio escucha en la dirección especificada. No tiene mensaje; construimos uno. Este [catch] debe preceder al de la línea 48, porque [ConnectException] deriva de [IOException];
- líneas 48–50: otros errores de comunicación y respuestas de error del servicio (véase la línea 62);
- líneas 57–65: una solicitud GET, cuyo cuerpo de respuesta se obtiene como una cadena;
- línea 58: la solicitud se construye mediante un constructor (builder): la URL, el método HTTP y luego [build];
- Línea 59: el método [send] envía la solicitud y espera la respuesta. Su segundo parámetro, un [BodyHandler], especifica qué hacer con el cuerpo de la respuesta: [ofString] lee todo el cuerpo en una cadena, decodificada según el juego de caracteres especificado por el encabezado [Content-Type] (UTF-8 de forma predeterminada). [send] lanza una [IOException] en caso de error de comunicación y una [InterruptedException] si el hilo es interrumpido durante la espera; el programa principal deja que esta última se propague hacia arriba (línea 20);
- líneas 61–63: a diferencia de otras bibliotecas, [HttpClient] no trata un código de estado de error (4xx, 5xx) como una excepción: la respuesta se devuelve normalmente y nos corresponde a nosotros examinar su código. Aquí lanzamos una [IOException] para cualquier código distinto de 2xx.
Resultados, con el servicio en ejecución:
La línea 4 muestra el objeto [Greeting] recibido, en el formato del método [toString] generado para los records. La opción [-q] (quiet) de Maven suprime sus propios mensajes. Si se especifica una dirección en la que ningún servicio escucha, se rechaza la conexión:
Y si la URL del servicio es incorrecta, el servicio devuelve una respuesta 404:
Con un servicio SOAP, el cliente usaba un proxy generado a partir del WSDL del servicio y llamaba al método remoto como si fuera un método local. Aquí llamamos directamente a la URL del servicio. Escribiremos un proxy propiamente dicho para el servicio de cálculo de impuestos.
13.2.4. Descripción del servicio: OpenAPI
El WSDL describía un servicio SOAP en un formato estandarizado. Su equivalente actual es el documento OpenAPI. Para Spring Boot, la biblioteca [springdoc-openapi] (dependencia [org.springdoc:springdoc-openapi-starter-webmvc-ui]) lo genera sin una sola línea de código: examina los controladores y sus anotaciones al iniciar y publica el documento en la URL [/v3/api-docs], así como una página interactiva de pruebas, Swagger UI, en la URL [/swagger-ui.html]. El documento describe cada ruta: su URL, su método HTTP, sus parámetros y sus tipos, y el esquema JSON de sus respuestas. Generadores como OpenAPI Generator lo aprovechan para generar un cliente tipado en diversos lenguajes, tal como lo hacía [wsimport] con WSDL. Esta biblioteca no forma parte de Spring Boot, y no la usaremos en este capítulo.
13.3. Un servicio web para operaciones aritméticas
El servicio anterior ofrecía un único método. Ahora consideraremos un servicio web que proporciona las cuatro operaciones aritméticas: add(a, b), subtract(a, b), multiply(a, b) y divide(a, b). Aprovecharemos para explorar las dos formas de pasar parámetros a un servicio web y cómo manejar los errores.
13.3.1. El lado del servidor
El servicio [WsOperations] acepta dos tipos de solicitudes:
Solicitud | Parámetros |
GET /add?a=1.5&b=2 | La operación en la ruta de la URL, los números en su cadena de consulta |
POST /calculation | un documento JSON en el cuerpo de la solicitud: [{"operation":"add","a":1.5,"b":2}] |
En ambos casos, la respuesta es un documento JSON: [{"operation":"add","a":1.5,"b":2.0,"result":3.5}]. GET es adecuado para solicitudes simples que no modifican nada en el servidor: la URL se puede escribir en un navegador, guardar como marcador y su respuesta puede almacenarse en caché. POST es adecuado para datos voluminosos o estructurados. El archivo [pom.xml] del proyecto es igual al de [WsHello], salvo por el nombre del proyecto ([ws-operations]), y su clase principal, [WsOperationsApplication], es idéntica a la de [WsHello]. Su archivo [application.properties] es el siguiente:
- línea 4: el servicio escucha en el puerto 5110;
- línea 6: los errores detectados por el propio Spring MVC (URL desconocida, documento JSON no válido, tipo de documento no admitido, etc.) se informarán mediante una respuesta en el formato Problem Details . Este formato, estandarizado por la RFC 9457, es un documento JSON de tipo [application/problem+json] que describe un error: su tipo, un título, el código de estado, un detalle y, eventualmente, información adicional. Es la forma estándar en que un servicio REST indica qué está mal.
El validador es el siguiente:
Comentarios:
- Líneas 24–28: la solicitud GET. El parámetro [operation] del método está vinculado a la variable de ruta [{operation}] ([@PathVariable]). Los parámetros [a] y [b], anotados con [@RequestParam], se enlazan con los parámetros del mismo nombre de la cadena de consulta ([?a=1.5&b=2]). Son opcionales ([required = false]): un parámetro ausente se trata como [null]; de lo contrario, Spring rechazaría con una respuesta 400 cualquier solicitud a la que le falte alguno de ellos;
- Línea 26: [a] y [b] se declaran de tipo [String]. Podríamos haberlos declarado de tipo [double] o [Double]: Spring habría realizado entonces la conversión por sí mismo y habría rechazado un valor incorrecto con una respuesta 400 que contiene un mensaje de error genérico. Al recibirlos como cadenas, conservamos el control sobre los mensajes de error;
- líneas 32–35: la solicitud POST. El parámetro [request], anotado con [@RequestBody], es construido por Jackson a partir del cuerpo JSON de la solicitud. Sus componentes son de tipo [Double] (línea 93), no [double]: una propiedad ausente del documento JSON se evalúa entonces como [null], lo que permite detectarla;
- líneas 38–49: conversión de una cadena en un número; si falla, el resultado es [null]. Tanto en la URL como en JSON, los números se escriben con punto decimal: [Double.parseDouble], que es independiente del idioma del sistema, es por tanto la herramienta correcta (y no [NumberFormat], que esperaría una coma en un servidor francés, capítulo 5). También acepta los textos [NaN] e [Infinity], que rechazamos (línea 45);
- línea 54: el nombre de la operación, en minúsculas. [Locale.ROOT] realiza la conversión sin importar el idioma del sistema;
- líneas 55–61: la operación solicitada se representa mediante una interfaz funcional (capítulo 7), [DoubleBinaryOperator], cuyo método [applyAsDouble(double, double)] devuelve un [double]. Una expresión [switch] selecciona la lambda correspondiente a la operación; para una operación desconocida, selecciona [null];
- líneas 63–73: los tres parámetros se validan acumulando los errores en un diccionario que asocia cada parámetro con su lista de mensajes de error. Un [LinkedHashMap] conserva el orden de inserción;
- líneas 74–80: si se encuentra un error, se devuelve una respuesta 400. La clase [ProblemDetail] de Spring representa un documento “Problem Details”: [forStatus] lo crea con un código de estado, [setTitle] le asigna un título y [setProperty] le agrega una propiedad, en este caso [errors], la lista de errores. La clase [ResponseEntity] representa una respuesta HTTP completa: código de estado, encabezados y cuerpo. [ResponseEntity.badRequest()] prepara una respuesta 400 y [body] proporciona su cuerpo;
- líneas 82–87: la división por cero se rechaza con una respuesta 400, cuyo documento esta vez incluye un detalle ([forStatusAndDetail]). Este rechazo es necesario: en Java, dividir un [double] por cero no lanza una excepción sino que devuelve infinito ([Double.POSITIVE_INFINITY]), que un documento JSON no puede representar (Jackson lo escribiría como una cadena, ["Infinity"]). La prueba [b == 0] compara el valor del objeto [Double] con cero: Java lo “desempaqueta” (unboxing) automáticamente;
- línea 89: la respuesta 200, cuyo cuerpo es el objeto [CalculationResult] serializado a JSON;
- líneas 93–98: los dos tipos intercambiados con los clientes. Estos objetos, que se utilizan únicamente para transportar datos entre dos aplicaciones, se denominan DTO (Data Transfer Object). Los records son ideales para este propósito.
Ambos métodos del controlador devuelven el tipo [ResponseEntity<?>]: una respuesta cuyo cuerpo puede ser de cualquier tipo, en este caso un [CalculationResult] o un [ProblemDetail]. Spring examina el tipo real del cuerpo para serializarlo; asigna al documento el tipo [application/json], o [application/problem+json] para un [ProblemDetail].
13.3.2. Pruebas con curl
El servicio se inicia con [mvn spring-boot:run] en la carpeta [WsOperations]. Una suma:
El número 2 se ha convertido en 2.0: Jackson siempre escribe un [double] con su parte decimal. Para un cliente, en particular JavaScript, es el mismo número. Una división por cero:
- Línea 2: la solicitud es rechazada;
- línea 3: el cuerpo es un documento “Problem Details”;
- línea 6: después de una respuesta 400, Tomcat cierra la conexión por precaución: una solicitud no válida podría haber dejado datos inesperados en la conexión. El cliente abrirá otra para su siguiente solicitud;
- línea 8: el documento contiene las propiedades [title], [status] y [detail], establecidas por nuestro código, e [instance], agregada por Spring: la ruta de la solicitud que causó el error. La propiedad [type], una URL que documenta el tipo de error, está ausente: la RFC 9457 le asigna entonces el valor [about:blank], que significa que el código de estado basta para describir el problema. Observe que las propiedades están ordenadas alfabéticamente: es el comportamiento predeterminado de Jackson 3 para clases ordinarias como [ProblemDetail]; los records, en cambio, conservan el orden de sus componentes.
Una operación desconocida, un número escrito con coma decimal y un número ausente:
La propiedad [errors] del documento contiene los errores de validación, parámetro por parámetro; agregada mediante [setProperty], se ubica después de las propiedades normalizadas. Ahora una consulta POST. La opción [-d] de [curl] envía el texto que la sigue en el cuerpo de una solicitud POST, y la opción [-H] agrega un encabezado a la solicitud, en este caso el tipo del documento enviado:
Si el documento JSON enviado no es válido, Jackson no puede construir el parámetro [request]: Spring responde por sí solo con un error 400, sin ejecutar nuestro método:
El documento “Problem Details” de la línea 8 fue generado por Spring MVC, gracias a la propiedad [spring.mvc.problemdetails.enabled]; sin ella, obtendríamos el documento de error de Spring Boot visto con [WsHello]. Lo mismo ocurre si se omite el encabezado [Content-Type]: [curl] envía entonces el cuerpo como un formulario HTML, y Spring rechaza este tipo de documento:
El código 415 (Unsupported Media Type) significa que el tipo de documento enviado no es aceptado; el encabezado [Accept] de la línea 3 indica al cliente qué tipos se aceptan.
13.3.3. El lado del cliente

Nuestro cliente de consola solicita la operación y los dos números en una sola línea, y luego consulta el servicio dos veces: primero con GET y después con POST, para demostrar ambos métodos. Su archivo [pom.xml] es idéntico al de [ClientWsHello], salvo por el nombre del proyecto y la clase principal. Su programa es el siguiente:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 | |
Comentarios:
- Líneas 20–29: los archivos DTO del cliente. Se declaran aquí de nuevo: un cliente no comparte el código del servidor, solo el formato de los documentos JSON intercambiados. La clase [ProblemDetail] de Spring forma parte del framework web; para el cliente basta con un simple record. Sus componentes son de tipos objeto ([String], [Integer], [Map]): una propiedad ausente del documento, como [detail] o [errors], se establece en [null];
- línea 32: los números se ingresan y se muestran en el formato del idioma del sistema, en este caso inglés: punto decimal;
- Línea 37: a partir de Jackson 3, las propiedades desconocidas en el record (aquí, [instance]) se ignoran de forma predeterminada durante la deserialización;
- líneas 51–63: los números se verifican localmente antes de realizar cualquier llamada al servicio. Un servicio siempre debe verificar sus parámetros (ya que no sabe quién lo llama), pero un cliente puede evitar tráfico de red innecesario;
- línea 64: el texto que describe el cálculo, con los números en el formato del idioma del sistema;
- línea 67: la URL de la solicitud GET. Los números deben escribirse con punto decimal: al concatenar un [Double] con una cadena se usa su método [toString], que es independiente del idioma del sistema. La operación, ingresada por el usuario, se codifica con [URLEncoder];
- líneas 69–70: la solicitud GET;
- líneas 71–74: si tiene éxito (código de estado 200), la respuesta JSON se deserializa en un objeto [CalculationResult];
- líneas 75–79: si la solicitud falla, se muestran tal cual el código de estado y el documento recibido;
- líneas 80–83: la excepción [IOException] indica un error de comunicación, como un servicio inalcanzable;
- líneas 87–92: la solicitud POST. El objeto [CalculationRequest] se serializa a JSON mediante [writeValueAsString]; la solicitud recibe el encabezado [Content-Type], seguido de su cuerpo: [BodyPublishers.ofString] envía una cadena, codificada en UTF-8;
- líneas 97–107: en caso de fallo, el cuerpo es un documento “Problem Details”, deserializado en un objeto [Problem], del que se muestran el título, el detalle y los errores de validación. El método [forEach] de un [Map] recibe una lambda con dos parámetros: la clave y el valor de cada elemento (capítulo 7);
- líneas 118–123: lectura de un número en el formato del idioma del sistema. El método [parse(String, ParsePosition)] de [NumberFormat] lee el comienzo de la cadena e indica en el objeto [ParsePosition] dónde se detuvo: si no se detuvo al final, la entrada contiene caracteres sobrantes ([2.5x]).
Resultados, con el servicio en ejecución:
- línea 3: la URL de la consulta GET: los números 1.5 y 2 ingresados allí se escriben como 1.5 y 2.0;
- Líneas 6–8: el mismo error observado en ambas solicitudes: el documento sin procesar para la solicitud GET y su tratamiento para la solicitud POST;
- Líneas 10–12: el servicio detectó una operación desconocida;
- línea 14: el cliente detectó el número incorrecto, y no consultó el servicio.
13.4. Aplicación de ejemplo, versión 9: un servicio web para calcular impuestos
Retomamos la aplicación de cálculo de impuestos. En el capítulo anterior (versión 8) habíamos creado un servidor TCP que se podía consultar de forma remota, con su propio protocolo de comunicación. Ahora lo convertiremos en un servicio web REST.
13.4.1. La arquitectura
La arquitectura de la versión 9 es la siguiente:

- en el lado del servidor, el servicio web [WsTax] recibe solicitudes HTTP y las hace procesar por las capas [business] y [dao] de la versión 5 (capítulo 6), que se reutilizan tal cual;
- en el lado del cliente, la capa [ui] de la versión 5 también se reutiliza tal cual. Se comunica con un nuevo tipo de capa [business], [TaxBusinessHttp], que implementa la interfaz [ITaxBusiness] consultando el servicio web: actúa como un proxy del servicio. La capa [ui] no sabe que el cálculo se realiza en otra máquina;
- en ambos lados, la integración de las capas está a cargo del contenedor de inyección de dependencias de Spring, igual que en la versión 5.
13.4.2. El servicio web
El contrato del servicio es el siguiente:
Solicitud | Respuesta en caso de éxito | Respuesta en caso de error |
GET /tax?married=y&children=2&salary=60000 | 200: [{"tax":4282}] | 400: documento "Problem Details" |
POST /tax con el cuerpo [{"married":true,"children":2,"salary":60000}] | 200: [{"tax":4282}] | 400: documento "Problem Details" |
El proyecto [WsTax] depende de los módulos [tax-dao] y [tax-business] de la versión 5. Para que Maven los encuentre, primero debe instalarlos en el repositorio Maven local de la máquina (la carpeta [.m2/repository] del directorio personal del usuario) escribiendo [mvn install] en la carpeta [06-architectures/TaxV5] (capítulo 6). Las dependencias del archivo [pom.xml] de [WsTax] son entonces las siguientes (el resto del archivo es igual al de [WsHello], salvo por el nombre del proyecto: [examples.tax:ws-tax:9.0]):
- Líneas 7–17: los dos módulos de la versión 5, identificados por sus coordenadas Maven. El módulo [tax-dao] incluye también las clases [TaxBracket] y [TaxException] de la capa [entities]. Estos módulos dependen de Jackson 3.1.5, que el starter web ya proporciona.
El archivo de configuración [application.properties] es el siguiente:
- línea 4: el servicio escucha en el puerto 5120;
- Líneas 13–14: la configuración de la capa [dao], con el mismo formato que en el archivo [tax.properties] de la versión 5: la implementación que se utilizará y su archivo de datos. No son propiedades de Spring Boot, sino propiedades propias de nuestra aplicación: un archivo [application.properties] puede contener tantas como se desee. Aquí usamos los archivos JSON y [TaxData.json], ubicados en la carpeta del proyecto, que es la carpeta de ejecución del servicio con [mvn spring-boot:run].
Las capas [dao] y [business] se integran en el contenedor de Spring mediante una clase de configuración:
Comentarios:
- línea 15: la anotación [@Configuration] (capítulo 6): la clase define beans. Spring la encuentra porque está ubicada en el mismo paquete que la clase principal ([@ComponentScan]);
- Líneas 19–29: el método anotado con [@Bean] crea la capa [dao]. Sus parámetros los proporciona Spring: la anotación [@Value] le inyecta el valor de una propiedad de configuración. En [${dao.implementation:HardwiredTax}], el texto que sigue al carácter [:] es el valor predeterminado, que se usa si falta la propiedad. Este método y el siguiente son iguales a los de la clase [TaxConfig] de la versión 5 (capítulo 6), sin la anotación [@PropertySource]: Spring Boot lee por sí mismo el archivo [application.properties];
- líneas 32–35: la capa [business]. El parámetro [dao] del método recibe el bean de tipo [ITaxDao]: Spring crea, por tanto, la capa [dao] antes que la capa [business].
Estas líneas reemplazan la integración de las capas que el programa principal realizaba en la versión 5: el contenedor de Spring es el mismo, pero ahora es Spring Boot quien lo crea y localiza por sí solo la clase de configuración. Los beans definidos de esta manera son singletons, creados al iniciar la aplicación, antes de procesar cualquier solicitud: si el archivo de datos falta o es incorrecto, el servicio no se inicia, en lugar de responder a todas las solicitudes con un error 500. Lo verificaremos más adelante.
El servicio web es el controlador [TaxController]:
Comentarios:
- Línea 24: el registro de la clase. Spring Boot utiliza el API de registro (framework Simple Logging Facade for Java), que aquí se implementa con Logback. [LoggerFactory.getLogger] genera una entrada de registro cuya categoría es el nombre completo de la clase;
- Líneas 27–31: el controlador recibe la capa [business] desde su constructor. Spring, que crea el controlador, le pasa el bean de tipo [ITaxBusiness] definido por [TaxConfig]: esto es la inyección por constructor descrita en el capítulo 6. Un campo declarado [final] garantiza que la capa no cambiará;
- líneas 34–43: la solicitud GET. Los tres parámetros de la cadena de consulta se reciben como cadenas y se convierten: [y]/[n] to [married] (líneas 37–41, una expresión [switch] cuyo tipo es [Boolean]), enteros para [children] and [salary] ([readInteger], líneas 76–82), [null] en caso de error;
- líneas 46–49: la consulta POST: el cuerpo JSON se deserializa en un objeto [TaxRequest] (línea 94), cuyos componentes de tipo objeto ([Boolean], [Integer]) sirven para detectar valores ausentes. La misma URL [/tax] se asocia con dos métodos, según el método HTTP de la consulta;
- líneas 52–73: el procesamiento común a ambas solicitudes. Devuelve una respuesta si tiene éxito y lanza una excepción si ocurre un error. El tipo de su resultado, al igual que el de los métodos de las líneas 35 y 47, es por tanto simplemente [TaxResponse]: leer sus firmas muestra lo que devuelve el servicio cuando todo va bien;
- línea 54: ¿son correctos los tres parámetros? Las comparaciones [children >= 0] and [salary >= 0] desempaquetan los objetos [Integer]: solo se evalúan si estos no son [null], gracias a la evaluación perezosa del operador [&&];
- línea 55: el cálculo se delega a la capa [business] de la versión 5;
- línea 56: cada cálculo se registra en el nivel [INFO]. El texto del mensaje es una plantilla: cada aparición de [{}] se reemplaza por el argumento correspondiente, en orden. A diferencia de la concatenación, el mensaje solo se construye si debe mostrarse (según el nivel de registro), y las herramientas de registro pueden guardar cada valor por separado;
- líneas 60–72: en caso de error, se construye la lista de errores, se registra una advertencia ([warn]) y se lanza una excepción [BadRequestException] que transporta esta lista;
- líneas 85–91: un método anotado con [@ExceptionHandler] actúa como un manejador de excepciones: Spring lo llama cuando un método del controlador lanza una excepción del tipo especificado por su parámetro, en este caso [BadRequestException]. Lo que devuelve se convierte en la respuesta HTTP: un [ProblemDetail], cuyo código de estado (400) pasa a ser el código de estado de la respuesta;
- líneas 94–99: las respuestas DTO del servicio.
La excepción [BadRequestException] es la siguiente:
- línea 8: una excepción no verificada, que los métodos que la lanzan no necesitan declarar;
- líneas 10–11: una excepción es serializable (en el sentido de la serialización binaria de Java): con la opción [-Xlint:all], el compilador exige que declare un número de versión;
- línea 15: la lista de errores. La palabra clave [transient] excluye este campo de la serialización binaria, ya que el tipo [Map] no es necesariamente serializable; sin ella, el compilador emitiría una advertencia. Esto no tiene consecuencias aquí: nuestras excepciones nunca se serializan.
La clase principal [WsTaxApplication] es idéntica a la de los otros dos servicios. La carpeta [src/main/resources/static] contiene el cliente web, que se trata en la sección siguiente.
El servicio web es sin estado: los métodos del controlador no conservan ningún estado de una solicitud a la siguiente. El controlador y las capas [business] y [dao] son singletons, creados una sola vez, que existen mientras la aplicación esté en ejecución; son compartidos por todas las solicitudes, que pueden ser procesadas simultáneamente por distintos hilos del servidor Tomcat (capítulo 8). Aquí esto no es un problema porque estos objetos nunca se modifican después de su creación: los tramos del impuesto se leen una sola vez, y el controlador tiene un único campo [final]. Un controlador nunca debe almacenar en sus campos datos específicos de una solicitud. El singleton es el ámbito predeterminado de los beans de Spring; pero hay otros: [prototype] (un objeto por cada solicitud al contenedor), [request] (un objeto por solicitud HTTP), [session] (un objeto por sesión HTTP). Por último, observe que la propiedad [spring.threads.virtual.enabled=true] hace que cada solicitud sea procesada por un hilo virtual (Java 21, capítulo 8) en lugar de un hilo del grupo de Tomcat: el servicio puede entonces manejar un número muy grande de solicitudes simultáneas que esperan operaciones de E/S.
13.4.3. Ejecución del servicio
Comencemos con un error de configuración. Los argumentos de la línea de comandos de la forma [--property=value] forman parte de la configuración de la aplicación y reemplazan los valores de [application.properties]. Con [mvn spring-boot:run], se pasan mediante la propiedad [spring-boot.run.arguments]. Especifiquemos un archivo de datos inexistente (en el curso se abrevian las líneas de este registro, que son muy largas, con [...]):
- línea 4: el servidor Tomcat se creó, pero todavía no ha abierto su puerto;
- línea 6: falló la creación del bean. Para crear el controlador, Spring tuvo que crear la [business] layer, y por tanto la capa [dao], cuyo constructor instanció una [TaxException] (capítulo 6). Los mensajes de nuestras capas, al igual que los de Spring, están en inglés;
- línea 7: el servidor Tomcat se detiene; el servicio no aceptó ninguna solicitud;
- líneas 9–21: el informe del fallo de inicio. Su descripción (línea 17) y la acción recomendada (línea 21) las genera una clase que escribimos para este fin.
En efecto, cuando falla el inicio, Spring Boot normalmente muestra la excepción y toda la pila de llamadas: decenas de líneas, entre las que cuesta encontrar el mensaje relevante. Spring Boot también puede pasar la excepción a analizadores de fallos, que la traducen en un informe legible. Proporciona analizadores para los errores más comunes (puerto ya en uso, bean no encontrado, etc.), y podemos agregar los nuestros:
- Línea 9: la clase [AbstractFailureAnalyzer<T>] de Spring Boot busca una excepción de tipo [T], en este caso [TaxException], en la cadena de causas que llevó a la excepción que provocó el fallo del inicio. Si encuentra una, llama al método [analyze];
- línea 12: el parámetro [rootFailure] es la excepción inicial, y [cause] es la [TaxException] encontrada en la cadena;
- líneas 14–18: el informe es un objeto [FailureAnalysis] formado por una descripción, una acción recomendada y la excepción analizada.
Este analizador no es un bean (debe funcionar incluso si no se pudo crear el contenedor): Spring Boot lo busca en los archivos [META-INF/spring.factories] de las bibliotecas y de la aplicación. El nuestro se encuentra en [src/main/resources/META-INF]:
- línea 2: la clave es el nombre de la interfaz [FailureAnalyzer], y el valor es el nombre de nuestra clase (si hubiera varias clases, se separarían con comas).
Ahora iniciemos el servicio de la forma habitual, con [mvn spring-boot:run], y luego consultémoslo con [curl]:
Este es el resultado esperado de la prueba: un contribuyente casado con dos hijos y un salario anual de 60 000 euros paga 4282 euros de impuestos (observe que la escala de impuestos utilizada, la de 2004, se conserva solo para este ejercicio fiscal). Con parámetros incorrectos:
Luego con POST, con un documento JSON:
El registro del servicio se mostrará al final del capítulo: contiene un historial de todos los cálculos solicitados.
13.4.4. La salida de consola: una nueva capa [business]
El cliente de la versión 9 usa la capa [ui] de la versión 5 sin modificarla: la clase [tax.ui.Dialog], cuyo método estático [run(ITaxBusiness business)] interactúa con el usuario y solicita cálculos a la capa [business] que se le pasa. Basta con pasarle una capa llamada [business] que consulte el servicio web. Las dependencias del proyecto [ClientWsTax] son las siguientes (el resto del archivo [pom.xml] es igual al de [ClientWsHello], salvo por el nombre del proyecto y la clase principal: [examples.tax:client-ws-tax:9.0], [tax.client.Main]):
- Líneas 4–13: módulos de la versión 5: [tax-business] para la interfaz [ITaxBusiness], [tax-ui] para la clase [Dialog]. Un proyecto puede depender de un módulo que contiene un programa principal: en ese caso, usa las clases públicas del módulo sin ejecutar el programa en sí. El módulo [tax-dao] es una dependencia indirecta (o transitiva): el cliente solo usa de él la clase [TaxException]. De manera similar, [tax-ui] proporciona el contenedor de Spring ([spring-context]);
- líneas 15–19: Jackson, para los documentos JSON. También lo proporciona [tax-dao], pero el cliente lo usa directamente: es preferible declararlo.
La nueva capa [business] es la clase [TaxBusinessHttp]:
Comentarios:
- línea 14: la clase implementa la interfaz [ITaxBusiness] de la versión 5;
- líneas 17–21: las variables DTO se declaran dentro de la clase ([private]) porque nadie más las utiliza;
- líneas 28–31: la clase recibe, mediante su constructor, el cliente
HTTPy laURLdel servicio, a partir de la cual calcula laURLdel método[POST /tax]; - líneas 36–40: la solicitud [POST tax], con la solicitud serializada como JSON en su cuerpo;
- línea 44: la solicitud se envía de forma sincrónica: el método [send] espera la respuesta, lo cual es coherente con el método [calculateTax] de la interfaz, que a su vez es sincrónico (devuelve un [int]);
- Líneas 45–47: [send] lanza una [IOException] si el servicio es inalcanzable. Es una excepción verificada, que el método [calculateTax] de la interfaz no declara: se encapsula dentro de una [TaxException], la excepción no verificada de la aplicación [Tax];
- líneas 48–52: lo mismo ocurre con [InterruptedException], que se lanza si el hilo es interrumpido durante la espera. Al capturar la excepción se borra el indicador de interrupción del hilo: la buena práctica (capítulo 8) es restablecerlo mediante [Thread.currentThread().interrupt()] para que el código que llama sepa que el hilo fue interrumpido;
- líneas 54–57: una respuesta de error se convierte en [TaxException], cuyo código es el código de estado HTTP;
- línea 59: la respuesta JSON [{"tax":4282}] se deserializa y se devuelve el monto del impuesto.
Con un servicio SOAP, la herramienta [wsimport] generaba un proxy, y una clase similar a esta implementaba [ITaxBusiness] delegándole el cálculo: hoy escribimos nosotros mismos las pocas decenas de líneas del proxy.
Como el método [calculateTax] de la interfaz [ITaxBusiness] es sincrónico, usamos el método sincrónico [send] de [HttpClient]. Esta interfaz también ofrece un método asincrónico, [sendAsync], que devuelve de inmediato un [CompletableFuture<HttpResponse<T>>] (capítulo 9). Para aprovecharlo, tendríamos que hacer asincrónica la interfaz: [CompletableFuture<Integer> calculateTaxAsync(boolean married, int nbChildren, int salary)], lo que exigiría modificar la interfaz [ITaxBusiness], sus implementaciones y la capa [ui]. No lo hicimos para mantener intactas las capas de la versión 5. Con los hilos virtuales (Java 21), el código sincrónico volvió a ser la forma recomendada de escribir programas que realizan muchas operaciones de E/S: un hilo virtual bloqueado por [send] no bloquea ningún hilo del sistema.
El programa principal del cliente integra las capas:
Comentarios:
- línea 13: la URL del servicio, pasada como argumento o, de forma predeterminada, [http://localhost:5120/];
- línea 18: el contenedor de Spring, como en la versión 5. Se cierra al final del bloque [try];
- Líneas 20–22: se registran tres beans: el bean de la URL del servicio y el bean del cliente HTTP, proporcionados mediante lambdas (de tipo [Supplier]), seguidos de la clase [TaxBusinessHttp]. Para crear esta clase, Spring examina su constructor y le pasa los beans de tipos [HttpClient] y [URI];
- línea 23: el contenedor crea los beans;
- línea 24: se solicita al contenedor un bean de tipo [ITaxBusiness]; este devuelve el objeto [TaxBusinessHttp], que implementa esta interfaz. El resto del programa desconoce la implementación;
- línea 28: el diálogo de la versión 5, sin ninguna modificación;
- líneas 29–33: si no se puede acceder al servicio, la excepción se propaga desde la [business] layer a través de la capa [ui], que no la maneja: se muestra mediante el método [Dialog.displayError] de la versión 5;
- líneas 35–37: en caso de error, el programa termina con el código 1 después de cerrar el contenedor.
Resultados, con el servicio en ejecución:
Se muestran los valores de verificación del cálculo del impuesto: 4282, 2959 y 11 519 euros. La entrada incorrecta de la línea 8 fue detectada por la capa [ui], que no llamó a la capa [business]: el servicio solo recibió solicitudes válidas. Si se detiene el servicio:
La [TaxException] de nuestro proxy encapsula la excepción [ConnectException] lanzada por [send], que a su vez encapsula las excepciones de la capa de red (capítulo 12). Ninguna de ellas tiene mensaje: [getMessage()] devuelve [null].
13.5. Un cliente web para el servicio de cálculo de impuestos
Una aplicación web “tradicional” genera sus páginas (HTML) en el servidor: cada vez que se hace clic en un botón, el formulario se envía al servidor, que devuelve al navegador una página nueva y completa. Hoy en día, lo más frecuente es que el propio navegador consulte un servicio web, en JavaScript, y actualice solo la parte de la página que cambió. Eso es lo que vamos a hacer. La arquitectura es la siguiente:

- 1: el navegador solicita la página [/]; el servidor [WsTax] le envía el archivo estático [index.html];
- 2: cada vez que se hace clic en el botón [Calculate], el código JavaScript de la página envía la solicitud [POST /tax] al servicio web y muestra en la página el monto del impuesto recibido, sin recargarla.
El servicio web no se ha modificado: simplemente sirve un archivo adicional. Spring Boot sirve automáticamente como archivos estáticos los archivos ubicados en la carpeta [static] dentro de los recursos de la aplicación ([src/main/resources/static]): páginas HTML, imágenes, scripts, hojas de estilo, etc. El archivo [static/index.html] también se sirve para la URL [/]: es la página de bienvenida. Un mismo servidor puede así alojar tanto un sitio web como un servicio web. La página [index.html] es la siguiente:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | |
Comentarios:
- Líneas 15–44: el formulario: dos botones de opción para el estado civil, dos campos de entrada para el número de hijos y el salario (cada uno seguido de una celda donde se mostrará un mensaje de error, si lo hay), un campo para el impuesto, un párrafo para un mensaje general y dos botones;
- líneas 46–108: el código de la página, en JavaScript, ejecutado por el navegador. El curso no trata JavaScript; sin embargo, este código se parece lo bastante a Java como para leerse sin dificultad;
- línea 57: una entrada que no es un entero da como resultado [null]; corresponde al servicio informar del error;
- línea 70: el manejador de clic del botón [Calculate] (envío del formulario). Es una función asincrónica ([async]): al igual que [CompletableFuture] (capítulo 9), no bloquea el navegador mientras espera una respuesta;
- línea 71: se impide que el navegador envíe el formulario por sí mismo, lo que provocaría la carga de una página nueva;
- líneas 74–77: la solicitud, un objeto JavaScript que tiene el formato esperado por [POST /tax];
- líneas 80–83: la función [fetch] del navegador envía la solicitud HTTP: el método [POST], el encabezado [Content-Type] y el cuerpo, la solicitud serializada a JSON mediante [JSON.stringify]. La URL [tax] es relativa a la página: la solicitud se envía al servidor que proporcionó la página. [await] espera la respuesta sin bloquear el navegador;
- línea 85: el cuerpo de la respuesta se deserializa en un objeto;
- líneas 86–88: si tiene éxito (código 2xx), se muestra el monto del impuesto;
- líneas 91–94: si ocurre un error, se muestra el título del documento “Problem Details”, junto con los mensajes de error sobre el número de hijos y el salario, cada uno al lado de su campo de entrada correspondiente. El operador [?.] devuelve [undefined] si el objeto a su izquierda no existe, en lugar de provocar un error; el operador [??] reemplaza un valor ausente por el valor que le sigue. Java no tiene un equivalente directo de estos operadores: en Java se usan pruebas con [null] o un [Optional];
- Líneas 103–106: el botón [Clear] restablece el formulario localmente, sin consultar el servicio.
Ahora que el servicio está en ejecución, solicitemos la URL [http://localhost:5120/] con un navegador:

Después de ingresar un cálculo y hacer clic en el botón [Calculate]:

Si la entrada es incorrecta, los mensajes de error son los del servicio web:

Estas capturas de pantalla se tomaron con el navegador Chromium, controlado por un programa mediante la biblioteca Playwright: así se automatizan las pruebas de una interfaz web.
Aquí, la página y el servicio comparten el mismo origen (mismo protocolo, misma máquina, mismo puerto: [http://localhost:5120]). Si la página fuera servida por otro sitio, por ejemplo [http://localhost:5000], el navegador aplicaría la política del mismo origen: solo permitiría que el código JavaScript lea la respuesta del servicio si este lo autoriza mediante el encabezado [Access-Control-Allow-Origin]. Para una solicitud como la nuestra (POST con un cuerpo JSON), el navegador incluso pediría esta autorización antes de enviar la solicitud, mediante una solicitud preliminar con el método OPTIONS (preflight). Este es el mecanismo CORS (Cross-Origin Resource Sharing), que protege al usuario de páginas maliciosas que podrían intentar usar, sin que él lo sepa, servicios en los que ha iniciado sesión. Para permitir otros orígenes, un controlador de Spring puede anotarse con [@CrossOrigin(origins = "http://localhost:5000")]; también es posible una configuración global (el método [addCorsMappings] de la interfaz [WebMvcConfigurer]). Los clientes que no son navegadores ([curl], nuestros clientes de consola) no se ven afectados por CORS.
Para interfaces web más completas generadas por el servidor, Spring MVC también ofrece controladores que devuelven páginas HTML construidas a partir de plantillas (como Thymeleaf), lo cual queda fuera del alcance de este curso.
13.6. Un servicio web es independiente del lenguaje de programación de su cliente
Con un servicio SOAP, el cliente debía contar con una herramienta capaz de leer el WSDL y generar el proxy, y las diferencias en la interpretación de los estándares entre plataformas causaban a menudo problemas de interoperabilidad. Con un servicio REST/JSON, cualquier lenguaje que disponga de un cliente HTTP y una biblioteca JSON, es decir, todos los lenguajes actuales, puede consultar el servicio sin ninguna herramienta especial. Ya lo vimos con [curl], que no está escrito en Java, y con el JavaScript del navegador. Aquí hay un cliente escrito para Node.js, el entorno de ejecución de JavaScript fuera del navegador:
- línea 3: la URL del servicio, pasada como argumento o establecida de forma predeterminada;
- líneas 6–9: tres solicitudes de cálculo, la última de las cuales es incorrecta;
- líneas 14–17: la misma función [fetch] que en el navegador;
- líneas 20–23: visualización del monto del impuesto o de los errores.
Una vez que el servicio está en ejecución:
En Python se usaría de forma similar el módulo [requests] o [httpx] ; en C#, la clase [HttpClient]. Por último, este es el registro del servicio [WsTax] durante todas las pruebas de este capítulo ([curl], cliente de consola, navegador, cliente Node.js), hasta que se terminó con Ctrl-C (en el curso se abrevian las rutas de la línea 2 con [...]):
- línea 8: Spring Boot encontró la página de inicio [static/index.html];
- líneas 14–24: mensajes de nuestro controlador: las líneas [INFO] registran los cálculos, mientras que las líneas [WARN] registran las solicitudes no válidas, junto con los nombres de los parámetros involucrados. Las líneas 14–16 provienen de [curl], las líneas 17–19 del cliente de consola, las líneas 20–21 del navegador y las líneas 22–24 del cliente Node.js;
- los nombres de los hilos ([http-nio-5120-exec-1] hasta [exec-10]) muestran que las solicitudes se distribuyen entre los hilos del grupo de Tomcat; las solicitudes sucesivas de un mismo cliente no son necesariamente atendidas por el mismo hilo.
13.7. Información adicional
13.7.1. Tipos de respuesta y manejo de errores
El servicio [WsOperations] devuelve objetos [ResponseEntity<?>]: solo con las firmas de sus métodos no queda claro qué respuestas pueden producir, y el compilador no realiza ninguna verificación. El servicio [WsTax] devuelve el tipo específico de su respuesta en caso de éxito, [TaxResponse], y señala los errores mediante excepciones, que un manejador [@ExceptionHandler] convierte en respuestas. Este es el enfoque más común con Spring: el código del método solo trata el caso normal, y las herramientas (en particular el generador del documento OpenAPI) conocen el esquema JSON de la respuesta sin que se les indique explícitamente. Una prueba unitaria también puede llamar directamente a un método del controlador y examinar su resultado, sin pasar por HTTP. [ResponseEntity<T>], con un tipo específico, sigue siendo útil cuando se necesita elegir el código de estado o agregar encabezados, por ejemplo, para una respuesta 201 (Created) acompañada de su encabezado [Location]: [ResponseEntity.created(uri).body(client)].
Un manejador [@ExceptionHandler] colocado en un controlador trata únicamente las excepciones de ese controlador. Para tratar las excepciones de todos los controladores de una aplicación, coloque los manejadores en una clase anotada con [@RestControllerAdvice]. Spring también proporciona la clase [ErrorResponseException], una excepción que transporta directamente un [ProblemDetail] y produce la respuesta correspondiente sin un manejador, y la clase [ResponseEntityExceptionHandler], que se puede extender para personalizar las respuestas a los errores detectados por el propio Spring MVC (documento JSON ilegible, tipo de documento no válido, etc.).
13.7.2. Un prefijo común para las rutas
Cuando varias rutas comparten un prefijo, este se especifica una sola vez con la anotación [@RequestMapping] colocada en la clase del controlador. Por ejemplo, con [@RequestMapping("/api/operations")] en la clase [OperationsController], las rutas pasan a ser [GET /api/operations/add?a=1&b=2] y [POST /api/operations/calculation], sin ningún otro cambio. Esta es también una forma sencilla de gestionar las versiones de los servicios ([/api/v1/...], [/api/v2/...]).
13.7.3. Interceptores y validación
Nuestros servicios validan sus propios parámetros. Spring ofrece dos mecanismos para sacar este código de los controladores:
- interceptores: una clase que implementa la interfaz [HandlerInterceptor], registrada mediante el método [addInterceptors] de [WebMvcConfigurer], se ejecuta antes y después de los métodos del controlador; puede examinar la solicitud y responder por sí misma, sin llamar al controlador. Se usan para el registro, la medición de tiempos de respuesta, la autenticación, entre otros. Los filtros de servlet ([jakarta.servlet.Filter]) cumplen la misma función a más bajo nivel;
- validación: con el starter [spring-boot-starter-validation] (que proporciona Hibernate Validator, la implementación de referencia de la API Jakarta Validation), los componentes de un DTO pueden anotarse con restricciones: [record TaxRequest(@NotNull Boolean married, @NotNull @Min(0) Integer children, @NotNull @Min(0) Integer salary)]. Un parámetro [@Valid @RequestBody TaxRequest request] se valida entonces antes de llamar al método, y una solicitud no válida se rechaza con una respuesta 400 “Problem Details”, como las que hemos construido.
13.7.4. Alojamiento
Nuestros servicios se ejecutan con [mvn spring-boot:run], lo cual es adecuado para el desarrollo. En producción:
- primero se empaqueta la aplicación con [mvn package]: el plugin de Spring Boot genera un único archivo [.jar] “ejecutable”, que contiene la aplicación, sus dependencias y el servidor Tomcat. Basta con copiarlo al servidor y ejecutarlo con [java -jar ws-tax-9.0.jar]; la configuración se puede modificar mediante argumentos de la línea de comandos ([--server.port=80]), variables de entorno o un archivo [application.properties] colocado junto al archivo [.jar];
- Tomcat puede exponerse directamente a Internet, pero a menudo se coloca detrás de un proxy inverso (nginx o Apache en Linux, IIS en Windows) que recibe las solicitudes HTTPS, gestiona los certificados y distribuye la carga entre varias instancias de la aplicación;
- La aplicación también puede desplegarse como una imagen de contenedor (Docker), que el plugin de Spring Boot puede generar sin un archivo [Dockerfile]: [mvn spring-boot:build-image]. La imagen se ejecuta entonces en cualquier plataforma de contenedores, ya sea en su propio servidor o con un proveedor de alojamiento;
- HTTPS es esencial: las propiedades [server.ssl.*] de Spring Boot configuran el certificado del servidor Tomcat cuando el servidor se expone directamente.
13.8. Conclusión
Este capítulo presentó los servicios web REST/JSON, sucesores de los servicios web SOAP, escritos con Spring Boot y Spring MVC. Hemos visto:
- que un servicio web asocia URL y métodos HTTP con métodos Java mediante las anotaciones [@RestController], [@GetMapping] y [@PostMapping], y que los parámetros de estos métodos se obtienen de la ruta ([@PathVariable]), la cadena de consulta ([@RequestParam]), el cuerpo (JSON, [@RequestBody]) o el contenedor de Spring (inyección por constructor);
- que los resultados se envían como JSON mediante Jackson, y los errores se informan mediante un código de estado y un documento “Problem Details” ([ProblemDetail], [ResponseEntity], [@ExceptionHandler]);
- que un cliente Java usa [java.net.http.HttpClient] y Jackson, y que un cliente escrito en cualquier otro lenguaje puede hacer lo mismo;
- que la arquitectura en capas cumplió sus promesas: la versión 9 del cálculo de impuestos reutiliza, sin modificarlas, las capas del lado del servidor [dao] y [business] de la versión 5, así como su capa del lado del cliente [ui]; solo hizo falta escribir el servicio web (unas 100 líneas) y una nueva implementación de la interfaz [ITaxBusiness] (unas 60 líneas).