Skip to content

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:

Image

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:

Image

Los proyectos de este capítulo son proyectos Maven, agrupados en la carpeta [13-web-services]:

13-web-services/
  pom.xml                   aggregation project of the six Maven projects
  WsHello/                  "Hello" web service
    pom.xml
    src/main/java/wshello/WsHelloApplication.java
    src/main/java/wshello/HelloController.java
    src/main/resources/application.properties
  ClientWsHello/            its console client
    pom.xml
    src/main/java/clientwshello/Main.java
  WsOperations/             web service of the four operations
    pom.xml
    src/main/java/wsoperations/WsOperationsApplication.java
    src/main/java/wsoperations/OperationsController.java
    src/main/resources/application.properties
  ClientWsOperations/       its console client
    pom.xml
    src/main/java/clientwsoperations/Main.java
  WsTax/                    tax calculation web service (version 9)
    pom.xml
    TaxData.json
    src/main/java/tax/ws/...
    src/main/resources/application.properties
    src/main/resources/static/index.html    the web client
  ClientWsTax/              its console client (version 9)
    pom.xml
    src/main/java/tax/client/TaxBusinessHttp.java
    src/main/java/tax/client/Main.java
  ClientNode/               a JavaScript client
    client-tax.mjs

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

Image

El archivo [pom.xml] del proyecto [WsHello] es el siguiente:

<?xml version="1.0" encoding="UTF-8"?>
<!-- el servicio web WsHello: una aplicación Spring Boot -->
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- el proyecto padre de Spring Boot: versiones de las bibliotecas y configuración de los plugins -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>4.1.1</version>
        <relativePath/>
    </parent>

    <groupId>examples.webservices</groupId>
    <artifactId>ws-hello</artifactId>
    <version>1.0</version>

    <properties>
        <java.version>25</java.version>
        <maven.compiler.release>25</maven.compiler.release>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <!-- Spring MVC, el servidor Tomcat integrado y Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.15.0</version>
                <configuration>
                    <parameters>true</parameters>
                    <compilerArgs>
                        <arg>-Xlint:all</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
            <!-- mvn spring-boot:run inicia la aplicación; mvn package genera un jar ejecutable de ella -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

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:

package wshello;

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

// la aplicación Spring Boot WsHello
@SpringBootApplication
public class WsHelloApplication {

    public static void main(String[] args) {
        // inicia Spring, y luego el servidor Tomcat que espera las peticiones
        SpringApplication.run(WsHelloApplication.class, args);
    }
}
  • 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]:

1
2
3
4
5
6
7
8
# el nombre de la aplicación
spring.application.name=WsHello
# el puerto de escucha del servidor Tomcat
server.port=5100
# sin banner al inicio
spring.main.banner-mode=off
# mensajes de registro más cortos: hora, nivel, hilo, clase, mensaje
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n
  • 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:

package wshello;

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

// el servicio web WsHello: cada método público anotado procesa una URL
@RestController
public class HelloController {

    // la raíz del sitio: un texto de bienvenida
    @GetMapping("/")
    public String home() {
        return "WsHello web service: try /hello/{name} or /greeting/{name}";
    }

    // un "método web" convertido en URL: saluda a la señora
    // el segmento {name} de la URL se pasa al parámetro [name] del método
    // una cadena se devuelve tal cual (text/plain)
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return "Hello Mrs " + name;
    }

    // lo mismo con una respuesta JSON: un objeto se serializa a JSON (application/json)
    @GetMapping("/greeting/{name}")
    public Greeting greeting(@PathVariable String name) {
        return new Greeting(name, "Hello Mrs " + name);
    }

    // el resultado del método /greeting
    public record Greeting(String name, String message) {
    }
}

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 [...]):

> mvn spring-boot:run
18:57:19.455 INFO  [main] WsHelloApplication : Starting WsHelloApplication using Java 25.0.4.1 with PID 6430 (... in .../13-web-services/WsHello)
18:57:19.911 INFO  [main] WsHelloApplication : No active profile set, falling back to 1 default profile: "default"
18:57:24.871 INFO  [main] TomcatWebServer : Tomcat initialized with port 5100 (http)
18:57:24.915 INFO  [main] StandardService : Starting service [Tomcat]
18:57:24.915 INFO  [main] StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.24]
18:57:25.041 INFO  [main] WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 4582 ms
18:57:27.317 INFO  [main] TomcatWebServer : Tomcat started on port 5100 (http) with context path '/'
18:57:27.394 INFO  [main] WsHelloApplication : Started WsHelloApplication in 10.545 seconds (process running for 11.704)
18:57:30.107 INFO  [http-nio-5100-exec-1] [/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
18:57:30.108 INFO  [http-nio-5100-exec-1] DispatcherServlet : Initializing Servlet 'dispatcherServlet'
18:57:30.113 INFO  [http-nio-5100-exec-1] DispatcherServlet : Completed initialization in 5 ms
18:58:33.536 INFO  [SpringApplicationShutdownHook] GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
18:58:33.585 INFO  [tomcat-shutdown] GracefulShutdown : Graceful shutdown complete
  • 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:

1
2
3
4
5
6
7
> curl -s -i http://localhost:5100/hello/Carla%20Bruni
HTTP/1.1 200 
Content-Type: text/plain;charset=UTF-8
Content-Length: 21
Date: Sat, 03 Oct 2026 16:57:30 GMT

Hello Mrs Carla Bruni
  • 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:

1
2
3
4
5
6
7
> curl -s -i http://localhost:5100/greeting/Carla%20Bruni
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 56
Date: Sat, 03 Oct 2026 16:57:30 GMT

{"name":"Carla Bruni","message":"Hello Mrs Carla Bruni"}
  • 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:

1
2
3
4
5
6
7
> curl -s -i http://localhost:5100/hello
HTTP/1.1 404 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:57:31 GMT

{"timestamp":"2026-10-03T16:57:31.003Z","status":404,"error":"Not Found","path":"/hello"}
  • 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

Image

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:

    <dependencies>
        <!-- Jackson para leer las respuestas JSON -->
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>3.1.5</version>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.15.0</version>
                <configuration>
                    <parameters>true</parameters>
                    <compilerArgs>
                        <arg>-Xlint:all</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
            <!-- mvn exec:java ejecuta la clase principal -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <mainClass>clientwshello.Main</mainClass>
                </configuration>
            </plugin>

Su código es el siguiente:

package clientwshello;

import java.io.IOException;
import java.net.ConnectException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import tools.jackson.databind.json.JsonMapper;

// cliente de consola del servicio web WsHello
public class Main {

    // la respuesta JSON del servicio: mismos nombres de componentes que en el lado del servidor
    record Greeting(String name, String message) {
    }

    public static void main(String[] args) throws InterruptedException {
        // la URL del servicio se puede pasar como argumento
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5100/");
        // el conversor Jackson JSON <-> objetos
        JsonMapper mapper = JsonMapper.builder().build();

        // un único cliente HTTP durante toda la duración del programa
        try (HttpClient client = HttpClient.newHttpClient()) {
            while (true) {
                // el nombre de la señora
                String input = IO.readln("Name of the lady (nothing to stop): ");
                String name = input == null ? "" : input.strip();
                if (name.isEmpty()) {
                    break;
                }
                try {
                    // el nombre se coloca en la ruta de la URL: debe codificarse en ella
                    String encodedName = URLEncoder.encode(name, StandardCharsets.UTF_8).replace("+", "%20");
                    // 1 - respuesta de texto
                    String text = get(client, serviceUrl.resolve("hello/" + encodedName));
                    IO.println("[text] " + text);
                    // 2 - respuesta JSON, deserializada en un objeto Greeting
                    String json = get(client, serviceUrl.resolve("greeting/" + encodedName));
                    Greeting greeting = mapper.readValue(json, Greeting.class);
                    IO.println("[JSON] " + greeting);
                } catch (ConnectException e) {
                    // ningún servicio escucha en esta dirección (la excepción no tiene mensaje)
                    IO.println("Error: ConnectException: connection refused (" + serviceUrl + ")");
                } catch (IOException e) {
                    // el servicio respondió con un error, o la comunicación falló
                    IO.println("Error: " + e.getClass().getSimpleName() + " : " + e.getMessage());
                }
            }
        }
    }

    // una petición GET cuyo cuerpo de respuesta se devuelve como cadena
    private static String get(HttpClient client, URI url) throws IOException, InterruptedException {
        HttpRequest request = HttpRequest.newBuilder(url).GET().build();
        HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
        // un código de estado distinto de 2xx es un error
        if (response.statusCode() / 100 != 2) {
            throw new IOException("the service responded " + response.statusCode() + " for " + url);
        }
        return response.body();
    }
}

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:

1
2
3
4
5
6
7
8
> mvn -q compile exec:java
Name of the lady (nothing to stop): Carla Bruni
[text] Hello Mrs Carla Bruni
[JSON] Greeting[name=Carla Bruni, message=Hello Mrs Carla Bruni]
Name of the lady (nothing to stop): Marie Curie
[text] Hello Mrs Marie Curie
[JSON] Greeting[name=Marie Curie, message=Hello Mrs Marie Curie]
Name of the lady (nothing to stop): 

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:

1
2
3
4
> mvn -q compile exec:java -Dexec.args="http://localhost:5199/"
Name of the lady (nothing to stop): Carla Bruni
Error: ConnectException: connection refused (http://localhost:5199/)
Name of the lady (nothing to stop): 

Y si la URL del servicio es incorrecta, el servicio devuelve una respuesta 404:

1
2
3
4
> mvn -q compile exec:java -Dexec.args="http://localhost:5100/hello/"
Name of the lady (nothing to stop): Carla Bruni
Error: IOException : the service responded 404 for http://localhost:5100/hello/hello/Carla%20Bruni
Name of the lady (nothing to stop): 

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:

# el nombre de la aplicación
spring.application.name=WsOperations
# el puerto de escucha del servidor Tomcat
server.port=5110
# los errores detectados por Spring MVC se informan en el formato "Problem Details" (RFC 9457)
spring.mvc.problemdetails.enabled=true
# sin banner al inicio
spring.main.banner-mode=off
# mensajes de registro más cortos: hora, nivel, hilo, clase, mensaje
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n
  • 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:

package wsoperations;

import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import java.util.function.DoubleBinaryOperator;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

// el servicio web WsOperations: las cuatro operaciones aritméticas
@RestController
public class OperationsController {

    // GET /add?a=1.5&b=2 (igual para subtract, multiply, divide)
    // [operation] proviene de la ruta de la URL, [a] y [b] de su cadena de consulta
    @GetMapping("/{operation}")
    public ResponseEntity<?> calculateGet(@PathVariable String operation,
            @RequestParam(required = false) String a, @RequestParam(required = false) String b) {
        return calculate(operation, readNumber(a), readNumber(b));
    }

    // POST /calculation con un cuerpo JSON: {"operation":"add","a":1.5,"b":2}
    // el cuerpo JSON se deserializa en el parámetro [request]
    @PostMapping("/calculation")
    public ResponseEntity<?> calculatePost(@RequestBody CalculationRequest request) {
        return calculate(request.operation(), request.a(), request.b());
    }

    // un número escrito con punto decimal, null si falta o es incorrecto
    private static Double readNumber(String text) {
        if (text == null) {
            return null;
        }
        try {
            double number = Double.parseDouble(text);
            // NaN y los infinitos se rechazan
            return Double.isFinite(number) ? number : null;
        } catch (NumberFormatException e) {
            return null;
        }
    }

    // el cálculo común a los dos métodos HTTP
    private static ResponseEntity<?> calculate(String operation, Double a, Double b) {
        // la operación solicitada, null si se desconoce
        String name = operation == null ? "" : operation.toLowerCase(Locale.ROOT);
        DoubleBinaryOperator calculation = switch (name) {
            case "add" -> (x, y) -> x + y;
            case "subtract" -> (x, y) -> x - y;
            case "multiply" -> (x, y) -> x * y;
            case "divide" -> (x, y) -> x / y;
            default -> null;
        };
        // comprobación de los parámetros: los errores se acumulan
        Map<String, List<String>> errors = new LinkedHashMap<>();
        if (calculation == null) {
            errors.put("operation", List.of("Unknown operation [" + name
                    + "]: use add, subtract, multiply or divide"));
        }
        if (a == null) {
            errors.put("a", List.of("The number a is missing or incorrect"));
        }
        if (b == null) {
            errors.put("b", List.of("The number b is missing or incorrect"));
        }
        if (!errors.isEmpty()) {
            // respuesta 400 con la lista de errores
            ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
            problem.setTitle("Incorrect parameters");
            problem.setProperty("errors", errors);
            return ResponseEntity.badRequest().body(problem);
        }
        // la división por cero se rechaza: respuesta 400
        if (name.equals("divide") && b == 0) {
            ProblemDetail problem = ProblemDetail.forStatusAndDetail(HttpStatus.BAD_REQUEST,
                    "The number b must be non-zero for a division");
            problem.setTitle("Division by zero");
            return ResponseEntity.badRequest().body(problem);
        }
        // respuesta 200 con el resultado en JSON
        return ResponseEntity.ok(new CalculationResult(name, a, b, calculation.applyAsDouble(a, b)));
    }

    // la solicitud de cálculo (cuerpo de la petición POST): los números ausentes del JSON son null
    public record CalculationRequest(String operation, Double a, Double b) {
    }

    // el resultado de un cálculo (cuerpo de la respuesta)
    public record CalculationResult(String operation, double a, double b, double result) {
    }
}

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:

1
2
3
4
5
6
7
> curl -s -i "http://localhost:5110/add?a=1.5&b=2"
HTTP/1.1 200 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:40 GMT

{"operation":"add","a":1.5,"b":2.0,"result":3.5}

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:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/divide?a=1&b=0"
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:40 GMT
Connection: close

{"detail":"The number b must be non-zero for a division","instance":"/divide","status":400,"title":"Division by zero"}
  • 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:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5110/power?a=1,5"
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:40 GMT
Connection: close

{"instance":"/power","status":400,"title":"Incorrect parameters","errors":{"operation":["Unknown operation [power]: use add, subtract, multiply or divide"],"a":["The number a is missing or incorrect"],"b":["The number b is missing or incorrect"]}}

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:

1
2
3
4
5
6
7
> curl -s -i -H "Content-Type: application/json" -d '{"operation":"multiply","a":1.5,"b":-4}' http://localhost:5110/calculation
HTTP/1.1 200 
Content-Type: application/json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:41 GMT

{"operation":"multiply","a":1.5,"b":-4.0,"result":-6.0}

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:

1
2
3
4
5
6
7
8
> curl -s -i -H "Content-Type: application/json" -d '{"operation":"multiply","a":1.5,' http://localhost:5110/calculation
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:41 GMT
Connection: close

{"detail":"Failed to read request","instance":"/calculation","status":400,"title":"Bad Request"}

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:

1
2
3
4
5
6
7
8
> curl -s -i -d 'x' http://localhost:5110/calculation
HTTP/1.1 415 
Accept: application/json, application/*+json
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 16:59:41 GMT

{"detail":"Content-Type 'application/x-www-form-urlencoded;charset=UTF-8' is not supported.","instance":"/calculation","status":415,"title":"Unsupported Media Type"}

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

Image

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:

package clientwsoperations;

import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;
import java.nio.charset.StandardCharsets;
import java.text.NumberFormat;
import java.text.ParsePosition;
import java.util.List;
import java.util.Map;
import tools.jackson.databind.json.JsonMapper;

// cliente de consola del servicio web WsOperations
public class Main {

    // los objetos intercambiados con el servicio (los nombres de los componentes son los del JSON)
    record CalculationRequest(String operation, double a, double b) {
    }

    record CalculationResult(String operation, double a, double b, double result) {
    }

    // una respuesta de error en el formato "Problem Details"
    record Problem(String title, String detail, Integer status, Map<String, List<String>> errors) {
    }

    // los números se escriben y se muestran en la cultura actual (fr-FR: coma decimal, en-US: punto decimal)
    private static final NumberFormat FORMAT = NumberFormat.getInstance();

    public static void main(String[] args) throws InterruptedException {
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5110/");
        // el conversor JSON; Jackson 3 ignora las propiedades JSON desconocidas (instance...)
        JsonMapper mapper = JsonMapper.builder().build();

        try (HttpClient client = HttpClient.newHttpClient()) {
            while (true) {
                // ingreso de la operación y de los dos números (separador decimal de la cultura actual)
                String input = IO.readln("Operation a b (e.g.: add 1.5 2), nothing to stop: ");
                String[] fields = input == null ? new String[0] : input.strip().split("\\s+");
                if (fields.length == 0 || fields[0].isEmpty()) {
                    break;
                }
                if (fields.length != 3) {
                    IO.println("Three elements are needed: operation a b");
                    continue;
                }
                // comprobación local de los dos números, antes de cualquier llamada al servicio
                String operation = fields[0];
                Double a = readNumber(fields[1]);
                if (a == null) {
                    IO.println("Incorrect number a...");
                }
                Double b = readNumber(fields[2]);
                if (b == null) {
                    IO.println("Incorrect number b...");
                }
                if (a == null || b == null) {
                    continue;
                }
                String calculation = operation + "(" + FORMAT.format(a) + " ; " + FORMAT.format(b) + ")";

                // 1 - petición GET: en la URL, los números se escriben con punto decimal
                String url = URLEncoder.encode(operation, StandardCharsets.UTF_8) + "?a=" + a + "&b=" + b;
                try {
                    HttpRequest request = HttpRequest.newBuilder(serviceUrl.resolve(url)).GET().build();
                    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
                    if (response.statusCode() == 200) {
                        CalculationResult result = mapper.readValue(response.body(), CalculationResult.class);
                        IO.println("[GET " + url + "] " + calculation
                                + " = " + FORMAT.format(result.result()));
                    } else {
                        // fallo: se muestran el código de estado y el documento recibido, tal cual
                        IO.println("[GET " + url + "] error " + response.statusCode()
                                + " : " + response.body());
                    }
                } catch (IOException e) {
                    // el servicio es inalcanzable
                    IO.println("[GET " + url + "] error: " + e);
                }

                // 2 - petición POST: la solicitud se envía en JSON en el cuerpo de la petición
                try {
                    String json = mapper.writeValueAsString(new CalculationRequest(operation, a, b));
                    HttpRequest request = HttpRequest.newBuilder(serviceUrl.resolve("calculation"))
                            .header("Content-Type", "application/json")
                            .POST(HttpRequest.BodyPublishers.ofString(json))
                            .build();
                    HttpResponse<String> response = client.send(request, BodyHandlers.ofString());
                    if (response.statusCode() == 200) {
                        // éxito: el cuerpo contiene el resultado
                        CalculationResult result = mapper.readValue(response.body(), CalculationResult.class);
                        IO.println("[POST calculation] " + calculation + " = " + FORMAT.format(result.result()));
                    } else {
                        // fallo: el cuerpo contiene la descripción del problema
                        Problem problem = mapper.readValue(response.body(), Problem.class);
                        IO.println("[POST calculation] error " + response.statusCode() + " : " + problem.title());
                        if (problem.detail() != null) {
                            IO.println("  " + problem.detail());
                        }
                        if (problem.errors() != null) {
                            problem.errors().forEach((parameter, messages) ->
                                    IO.println("  " + parameter + " : " + String.join(" ; ", messages)));
                        }
                    }
                } catch (IOException e) {
                    // el servicio es inalcanzable
                    IO.println("[POST calculation] error: " + e);
                }
            }
        }
    }

    // un número escrito en la cultura actual, null si la entrada no es un número
    private static Double readNumber(String text) {
        ParsePosition position = new ParsePosition(0);
        Number number = FORMAT.parse(text, position);
        // la entrada debe haberse leído por completo: "2.5x" se rechaza
        return number == null || position.getIndex() != text.length() ? null : number.doubleValue();
    }
}

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:

> mvn -q compile exec:java
Operation a b (e.g.: add 1.5 2), nothing to stop: add 1.5 2
[GET add?a=1.5&b=2.0] add(1.5 ; 2) = 3.5
[POST calculation] add(1.5 ; 2) = 3.5
Operation a b (e.g.: add 1.5 2), nothing to stop: divide 1 0
[GET divide?a=1.0&b=0.0] error 400 : {"detail":"The number b must be non-zero for a division","instance":"/divide","status":400,"title":"Division by zero"}
[POST calculation] error 400 : Division by zero
  The number b must be non-zero for a division
Operation a b (e.g.: add 1.5 2), nothing to stop: power 2 3
[GET power?a=2.0&b=3.0] error 400 : {"instance":"/power","status":400,"title":"Incorrect parameters","errors":{"operation":["Unknown operation [power]: use add, subtract, multiply or divide"]}}
[POST calculation] error 400 : Incorrect parameters
  operation : Unknown operation [power]: use add, subtract, multiply or divide
Operation a b (e.g.: add 1.5 2), nothing to stop: multiply 2.5 x
Incorrect number b...
Operation a b (e.g.: add 1.5 2), nothing to stop: 
  • 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:

Image

  • 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]):

    <dependencies>
        <!-- Spring MVC, el servidor Tomcat integrado y Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
        <!-- las capas [dao] y [business] de la versión 5, reutilizadas tal cual -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-dao</artifactId>
            <version>5.0</version>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
            <version>5.0</version>
        </dependency>
    </dependencies>
  • 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:

# el nombre de la aplicación
spring.application.name=WsTax
# el puerto de escucha del servidor Tomcat
server.port=5120
# los errores detectados por Spring MVC se informan en el formato "Problem Details" (RFC 9457)
spring.mvc.problemdetails.enabled=true
# sin banner al inicio
spring.main.banner-mode=off
# mensajes de registro más cortos: hora, nivel, hilo, clase, mensaje
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n

# la capa [dao]: su implementación y su archivo de datos
dao.implementation=JsonTax
dao.file=TaxData.json
  • 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:

package tax.ws;

import tax.dao.FileTax;
import tax.dao.HardwiredTax;
import tax.dao.ITaxDao;
import tax.dao.JsonTax;
import tax.entities.TaxException;
import tax.business.ITaxBusiness;
import tax.business.TaxBusiness;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

// la integración de las capas [dao] y [business] de la versión 5 en el contenedor de Spring
@Configuration
public class TaxConfig {

    // la capa [dao]: su implementación y su archivo provienen de la configuración
    @Bean
    public ITaxDao dao(@Value("${dao.implementation:HardwiredTax}") String implementation,
            @Value("${dao.file:}") String file) {
        return switch (implementation) {
            case "HardwiredTax" -> new HardwiredTax();
            case "FileTax" -> new FileTax(file);
            case "JsonTax" -> new JsonTax(file);
            default -> throw new TaxException(
                    "Unknown implementation [" + implementation + "] of the [dao] layer");
        };
    }

    // la capa [business]: Spring le pasa la capa [dao]
    @Bean
    public ITaxBusiness business(ITaxDao dao) {
        return new TaxBusiness(dao);
    }
}

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]:

package tax.ws;

import tax.business.ITaxBusiness;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Locale;
import java.util.Map;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.http.HttpStatus;
import org.springframework.http.ProblemDetail;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

// el servicio web de cálculo del impuesto (versión 9)
@RestController
public class TaxController {

    // el registro de la clase
    private static final Logger log = LoggerFactory.getLogger(TaxController.class);

    // la capa [business], inyectada por Spring
    private final ITaxBusiness business;

    public TaxController(ITaxBusiness business) {
        this.business = business;
    }

    // GET /tax?married=y&children=2&salary=60000
    @GetMapping("/tax")
    public TaxResponse calculateGet(@RequestParam(required = false) String married,
            @RequestParam(required = false) String children, @RequestParam(required = false) String salary) {
        Boolean isMarried = switch (married == null ? "" : married.toLowerCase(Locale.ROOT)) {
            case "y" -> true;
            case "n" -> false;
            default -> null;
        };
        return calculate(isMarried, readInteger(children), readInteger(salary));
    }

    // POST /tax con el cuerpo JSON {"married":true,"children":2,"salary":60000}
    @PostMapping("/tax")
    public TaxResponse calculatePost(@RequestBody TaxRequest request) {
        return calculate(request.married(), request.children(), request.salary());
    }

    // el procesamiento común a los dos métodos HTTP: el impuesto, o una excepción si la solicitud es incorrecta
    private TaxResponse calculate(Boolean married, Integer children, Integer salary) {
        // parámetros correctos: el cálculo se solicita a la capa [business]
        if (married != null && children != null && children >= 0 && salary != null && salary >= 0) {
            int tax = business.calculateTax(married, children, salary);
            log.info("Tax(married={}, children={}, salary={}) = {}", married, children, salary, tax);
            return new TaxResponse(tax);
        }
        // parámetros incorrectos: la lista de errores
        Map<String, List<String>> errors = new LinkedHashMap<>();
        if (married == null) {
            errors.put("married",
                    List.of("Indicate whether the taxpayer is married: y/n (GET) or true/false (POST)"));
        }
        if (children == null || children < 0) {
            errors.put("children", List.of("The number of children must be a positive or zero integer"));
        }
        if (salary == null || salary < 0) {
            errors.put("salary", List.of("The salary must be a positive or zero integer"));
        }
        log.warn("Incorrect request: {}", String.join(", ", errors.keySet()));
        throw new BadRequestException(errors);
    }

    // un entero, null si falta o es incorrecto
    private static Integer readInteger(String text) {
        try {
            return text == null ? null : Integer.valueOf(text);
        } catch (NumberFormatException e) {
            return null;
        }
    }

    // una solicitud incorrecta da una respuesta 400 en el formato "Problem Details"
    @ExceptionHandler
    public ProblemDetail badRequest(BadRequestException e) {
        ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
        problem.setTitle("Incorrect parameters");
        problem.setProperty("errors", e.getErrors());
        return problem;
    }

    // la solicitud de cálculo (cuerpo de la petición POST): las propiedades ausentes del JSON son null
    public record TaxRequest(Boolean married, Integer children, Integer salary) {
    }

    // la respuesta: el monto del impuesto
    public record TaxResponse(int tax) {
    }
}

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:

package tax.ws;

import java.io.Serial;
import java.util.List;
import java.util.Map;

// la excepción lanzada por el controlador cuando los parámetros del cálculo son incorrectos
public class BadRequestException extends RuntimeException {

    @Serial
    private static final long serialVersionUID = 1L;

    // los mensajes de error, parámetro por parámetro
    // (transient: un Map no es necesariamente serializable)
    private final transient Map<String, List<String>> errors;

    public BadRequestException(Map<String, List<String>> errors) {
        super("Incorrect parameters: " + String.join(", ", errors.keySet()));
        this.errors = errors;
    }

    public Map<String, List<String>> getErrors() {
        return errors;
    }
}
  • 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 [...]):

> mvn spring-boot:run -Dspring-boot.run.arguments=--dao.file=missing.json
19:01:41.197 INFO  [main] WsTaxApplication : Starting WsTaxApplication using Java 25.0.4.1 with PID 22677 (...)
...
19:01:49.390 INFO  [main] TomcatWebServer : Tomcat initialized with port 5120 (http)
...
19:01:50.956 WARN  [main] AnnotationConfigServletWebServerApplicationContext : Exception encountered during context initialization - cancelling refresh attempt: org.springframework.beans.factory.UnsatisfiedDependencyException: Error creating bean with name 'taxController' ... Error creating bean with name 'business' ... Error creating bean with name 'dao' ... Factory method 'dao' threw exception with message: Error while reading the file missing.json
19:01:50.991 INFO  [main] StandardService : Stopping service [Tomcat]
...
19:01:51.454 ERROR [main] LoggingFailureAnalysisReporter : 

***************************
APPLICATION FAILED TO START
***************************

Description:

The service cannot start: Error while reading the file missing.json (missing.json: The file [missing.json] does not exist)

Action:

Check the dao.implementation and dao.file properties of the configuration.
  • 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:

package tax.ws;

import tax.entities.TaxException;
import org.springframework.boot.diagnostics.AbstractFailureAnalyzer;
import org.springframework.boot.diagnostics.FailureAnalysis;

// Spring Boot llama a este analizador si el inicio falla a causa de una TaxException
// (archivo de datos ausente o incorrecto, implementación desconocida)
public class TaxFailureAnalyzer extends AbstractFailureAnalyzer<TaxException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, TaxException cause) {
        // la descripción del error: el mensaje de la excepción y el de su causa
        String description = "The service cannot start: " + cause.getMessage()
                + (cause.getCause() == null ? "" : " (" + cause.getCause().getMessage() + ")");
        // lo que debe hacer el usuario
        String action = "Check the dao.implementation and dao.file properties of the configuration.";
        return new FailureAnalysis(description, action, cause);
    }
}
  • 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]:

# el analizador de los fallos de inicio causados por una TaxException
org.springframework.boot.diagnostics.FailureAnalyzer=tax.ws.TaxFailureAnalyzer
  • 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]:

1
2
3
4
5
6
7
> curl -s -i "http://localhost:5120/tax?married=y&children=2&salary=60000"
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 12
Date: Sat, 03 Oct 2026 17:04:03 GMT

{"tax":4282}

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:

1
2
3
4
5
6
7
8
> curl -s -i "http://localhost:5120/tax?married=x&children=-2"
HTTP/1.1 400 
Content-Type: application/problem+json
Transfer-Encoding: chunked
Date: Sat, 03 Oct 2026 17:04:03 GMT
Connection: close

{"instance":"/tax","status":400,"title":"Incorrect parameters","errors":{"married":["Indicate whether the taxpayer is married: y/n (GET) or true/false (POST)"],"children":["The number of children must be a positive or zero integer"],"salary":["The salary must be a positive or zero integer"]}}

Luego con POST, con un documento JSON:

1
2
3
4
5
6
7
> curl -s -i -H "Content-Type: application/json" -d '{"married":true,"children":2,"salary":60000}' http://localhost:5120/tax
HTTP/1.1 200 
Content-Type: application/json
Content-Length: 12
Date: Sat, 03 Oct 2026 17:04:04 GMT

{"tax":4282}

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]):

    <dependencies>
        <!-- la interfaz de la capa [business] y la capa [ui] de la versión 5 -->
        <!-- (tax-ui también incorpora tax-dao y el contenedor de Spring) -->
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-business</artifactId>
            <version>5.0</version>
        </dependency>
        <dependency>
            <groupId>examples.tax</groupId>
            <artifactId>tax-ui</artifactId>
            <version>5.0</version>
        </dependency>
        <!-- Jackson para los documentos JSON intercambiados con el servicio -->
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>3.1.5</version>
        </dependency>
    </dependencies>
  • 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]:

package tax.client;

import tax.entities.TaxException;
import tax.business.ITaxBusiness;
import java.io.IOException;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import tools.jackson.databind.json.JsonMapper;

// la capa [business] del lado del cliente: un proxy del servicio web de cálculo del impuesto
// implementa la misma interfaz que la capa [business] local de la versión 5
public class TaxBusinessHttp implements ITaxBusiness {

    // los objetos intercambiados con el servicio web
    private record TaxRequest(boolean married, int children, int salary) {
    }

    private record TaxResponse(int tax) {
    }

    // el cliente HTTP, la URL del método POST /tax, el conversor JSON
    private final HttpClient client;
    private final URI taxUrl;
    private final JsonMapper mapper = JsonMapper.builder().build();

    public TaxBusinessHttp(HttpClient client, URI serviceUrl) {
        this.client = client;
        this.taxUrl = serviceUrl.resolve("tax");
    }

    @Override
    public int calculateTax(boolean married, int nbChildren, int salary) {
        // la petición POST /tax, con la solicitud en JSON en su cuerpo
        String json = mapper.writeValueAsString(new TaxRequest(married, nbChildren, salary));
        HttpRequest request = HttpRequest.newBuilder(taxUrl)
                .header("Content-Type", "application/json")
                .POST(HttpRequest.BodyPublishers.ofString(json))
                .build();
        HttpResponse<String> response;
        try {
            // envío síncrono: el método espera la respuesta
            response = client.send(request, HttpResponse.BodyHandlers.ofString());
        } catch (IOException e) {
            // el servicio es inalcanzable
            throw new TaxException("The web service " + taxUrl + " is unreachable", e);
        } catch (InterruptedException e) {
            // el hilo fue interrumpido durante la espera: se vuelve a señalar
            Thread.currentThread().interrupt();
            throw new TaxException("The tax calculation was interrupted", e);
        }
        // ¿aceptó el servicio la solicitud?
        if (response.statusCode() != 200) {
            throw new TaxException("The web service responded " + response.statusCode()
                    + " : " + response.body(), response.statusCode());
        }
        // la respuesta JSON {"tax":4282}
        return mapper.readValue(response.body(), TaxResponse.class).tax();
    }
}

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 HTTP y la URL del servicio, a partir de la cual calcula la URL del 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:

package tax.client;

import tax.business.ITaxBusiness;
import tax.ui.Dialog;
import java.net.URI;
import java.net.http.HttpClient;
import org.springframework.context.support.GenericApplicationContext;

public class Main {

    public static void main(String[] args) {
        // la URL del servicio web: la que se pasa como argumento, o la predeterminada
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5120/");

        // el código de salida del programa
        int code = 0;
        // integración de las capas: la capa [business] es ahora un cliente del servicio web
        try (GenericApplicationContext context = new GenericApplicationContext()) {
            // la URL del servicio y el cliente HTTP, que Spring pasará al constructor de TaxBusinessHttp
            context.registerBean(URI.class, () -> serviceUrl);
            context.registerBean(HttpClient.class, HttpClient::newHttpClient);
            context.registerBean(TaxBusinessHttp.class);
            context.refresh();
            ITaxBusiness business = context.getBean(ITaxBusiness.class);

            // el diálogo de la versión 5, sin ninguna modificación
            try {
                Dialog.run(business);
            } catch (RuntimeException e) {
                // el servicio es inalcanzable o rechazó la solicitud
                Dialog.displayError(e);
                code = 1;
            }
        }
        if (code != 0) {
            System.exit(code);
        }
    }
}

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:

> mvn -q compile exec:java
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Tax=4282 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 3 60000
Tax=2959 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: n 0 60000
Tax=11519 euros
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y -2 60000
syntax: Married NbChildren Salary
Married: y for married, n for not married
NbChildren: number of children
Salary: annual salary in euros
Incorrect NbChildren argument: type a positive or zero integer
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: 

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:

> mvn -q compile exec:java
Tax calculation parameters in the format: Married (y/n) NbChildren Salary, or nothing to stop: y 2 60000
Exception chain:
----------------------------------------
tax.entities.TaxException: The web service http://localhost:5120/tax is unreachable
----------------------------------------
java.net.ConnectException: null
----------------------------------------
java.net.ConnectException: null
----------------------------------------
java.nio.channels.ClosedChannelException: null
----------------------------------------

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:

Image

  • 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:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Calculate your tax</title>
  <style>
    body { font-family: sans-serif; background: #ffffe0; margin: 2em; }
    td { padding: 4px 8px; white-space: nowrap; }
    .error { color: #cc2200; }
    #tax:not(:empty) { background: #99ccff; padding: 2px 8px; font-weight: bold; }
  </style>
</head>
<body>
  <h2>Calculate your tax</h2>
  <form id="form">
    <table>
      <tr>
        <td>Are you married</td>
        <td>
          <label><input type="radio" name="married" value="yes"> Yes</label>
          <label><input type="radio" name="married" value="no" checked> No</label>
        </td>
      </tr>
      <tr>
        <td>Number of children</td>
        <td><input type="text" id="children" size="3"></td>
        <td class="error" id="childrenError"></td>
      </tr>
      <tr>
        <td>Annual salary</td>
        <td><input type="text" id="salary" size="8"></td>
        <td class="error" id="salaryError"></td>
      </tr>
      <tr>
        <td>Tax to pay</td>
        <td><span id="tax"></span></td>
      </tr>
    </table>
    <p class="error" id="message"></p>
    <p>
      <button type="submit">Calculate</button>
      <button type="button" id="clear">Clear</button>
    </p>
  </form>

  <script>
    // los elementos de la página
    const form = document.getElementById("form");
    const children = document.getElementById("children");
    const salary = document.getElementById("salary");
    const tax = document.getElementById("tax");
    const childrenError = document.getElementById("childrenError");
    const salaryError = document.getElementById("salaryError");
    const message = document.getElementById("message");

    // un entero ingresado, o null si la entrada no es un entero
    function readInteger(text) {
      return /^\s*-?\d+\s*$/.test(text) ? parseInt(text, 10) : null;
    }

    // borra el resultado y los mensajes de error
    function clearMessages() {
      tax.textContent = "";
      childrenError.textContent = "";
      salaryError.textContent = "";
      message.textContent = "";
    }

    // botón [Calculate]: se consulta el servicio web, sin recargar la página
    form.addEventListener("submit", async (event) => {
      event.preventDefault();
      clearMessages();
      // la solicitud, en el formato esperado por POST /tax
      const request = {
        married: form.married.value === "yes",
        children: readInteger(children.value),
        salary: readInteger(salary.value)
      };
      try {
        const response = await fetch("tax", {
          method: "POST",
          headers: { "Content-Type": "application/json" },
          body: JSON.stringify(request)
        });
        const body = await response.json();
        if (response.ok) {
          // 200: {"tax": 4282}
          tax.textContent = `${body.tax} euros`;
        } else {
          // 400: un documento "Problem Details" con los errores por parámetro
          const errors = body.errors ?? {};
          childrenError.textContent = errors.children?.join(" ") ?? "";
          salaryError.textContent = errors.salary?.join(" ") ?? "";
          message.textContent = body.title;
        }
      } catch (e) {
        // el servicio es inalcanzable
        message.textContent = `Error communicating with the service: ${e.message}`;
      }
    });

    // botón [Clear]: reinicio del formulario
    document.getElementById("clear").addEventListener("click", () => {
      children.value = "";
      salary.value = "";
      clearMessages();
    });
  </script>
</body>
</html>

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:

Image

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

Image

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

Image

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:

// un cliente JavaScript (Node.js) del servicio web de cálculo del impuesto
// llamada: node client-tax.mjs [service url]
const serviceUrl = process.argv[2] ?? "http://localhost:5120/";

// las solicitudes que se enviarán: la última es incorrecta
const requests = [
  { married: true, children: 2, salary: 60000 },
  { married: false, children: 0, salary: 60000 },
  { married: true, children: -1, salary: 60000 },
];

for (const request of requests) {
  // POST /tax con la solicitud en JSON
  const response = await fetch(new URL("tax", serviceUrl), {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(request),
  });
  const body = await response.json();
  if (response.ok) {
    console.log(`${JSON.stringify(request)} -> tax = ${body.tax} euros`);
  } else {
    console.log(`${JSON.stringify(request)} -> error ${response.status}: ${JSON.stringify(body.errors)}`);
  }
}
  • 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:

1
2
3
4
> node client-tax.mjs
{"married":true,"children":2,"salary":60000} -> tax = 4282 euros
{"married":false,"children":0,"salary":60000} -> tax = 11519 euros
{"married":true,"children":-1,"salary":60000} -> error 400: {"children":["The number of children must be a positive or zero integer"]}

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 [...]):

> mvn spring-boot:run
19:03:44.598 INFO  [main] WsTaxApplication : Starting WsTaxApplication using Java 25.0.4.1 with PID 25879 (... in .../13-web-services/WsTax)
19:03:44.621 INFO  [main] WsTaxApplication : No active profile set, falling back to 1 default profile: "default"
19:03:50.050 INFO  [main] TomcatWebServer : Tomcat initialized with port 5120 (http)
19:03:50.140 INFO  [main] StandardService : Starting service [Tomcat]
19:03:50.166 INFO  [main] StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.24]
19:03:50.314 INFO  [main] WebApplicationContextInitializer : Root WebApplicationContext: initialization completed in 4921 ms
19:03:51.065 INFO  [main] WelcomePageHandlerMapping : Adding welcome page: class path resource [static/index.html]
19:03:53.070 INFO  [main] TomcatWebServer : Tomcat started on port 5120 (http) with context path '/'
19:03:53.142 INFO  [main] WsTaxApplication : Started WsTaxApplication in 10.178 seconds (process running for 11.043)
19:04:03.287 INFO  [http-nio-5120-exec-1] [/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
19:04:03.287 INFO  [http-nio-5120-exec-1] DispatcherServlet : Initializing Servlet 'dispatcherServlet'
19:04:03.336 INFO  [http-nio-5120-exec-1] DispatcherServlet : Completed initialization in 49 ms
19:04:03.533 INFO  [http-nio-5120-exec-1] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:03.813 WARN  [http-nio-5120-exec-3] TaxController : Incorrect request: married, children, salary
19:04:04.116 INFO  [http-nio-5120-exec-4] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:09.345 INFO  [http-nio-5120-exec-6] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:09.875 INFO  [http-nio-5120-exec-8] TaxController : Tax(married=true, children=3, salary=60000) = 2959
19:04:09.890 INFO  [http-nio-5120-exec-10] TaxController : Tax(married=false, children=0, salary=60000) = 11519
19:04:13.159 INFO  [http-nio-5120-exec-2] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:13.319 WARN  [http-nio-5120-exec-3] TaxController : Incorrect request: children, salary
19:04:13.811 INFO  [http-nio-5120-exec-4] TaxController : Tax(married=true, children=2, salary=60000) = 4282
19:04:13.828 INFO  [http-nio-5120-exec-5] TaxController : Tax(married=false, children=0, salary=60000) = 11519
19:04:13.838 WARN  [http-nio-5120-exec-6] TaxController : Incorrect request: children
19:04:16.301 INFO  [SpringApplicationShutdownHook] GracefulShutdown : Commencing graceful shutdown. Waiting for active requests to complete
19:04:16.314 INFO  [tomcat-shutdown] GracefulShutdown : Graceful shutdown complete
  • 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).