Skip to content

13. Serviços web

Pré-requisitos: a versão 9 da aplicação [Tax], apresentada no fim deste capítulo, reutiliza os módulos [tax-dao], [tax-business] e [tax-ui] da versão 5 (Capítulo 6). Antes de compilar ou abrir seus projetos, é preciso ter instalado a versão 5 no repositório Maven local com o comando [mvn install] digitado na pasta [06-architectures/TaxV5] (veja o Capítulo 6, seção sobre [mvn install]).

13.1. Introdução

No capítulo anterior, apresentamos várias aplicações cliente/servidor TCP/IP. Como os clientes e o servidor trocam linhas de texto, eles podem ser escritos em qualquer linguagem. O cliente só precisa conhecer o protocolo de comunicação esperado pelo servidor.

Os serviços web também são aplicações servidoras (TCP/IP). Eles têm as seguintes características:

  • são hospedados por servidores web, e o protocolo de troca cliente/servidor é o HTTP (HyperText Transfer Protocol), um protocolo construído sobre o TCP/IP, que exploramos no capítulo anterior;
  • o serviço web tem um protocolo de comunicação padrão, qualquer que seja o serviço prestado. Um serviço web oferece diversos serviços: S1, S2…, Sn. Cada um desses serviços espera parâmetros fornecidos pelo cliente e devolve um resultado ao cliente. Para cada serviço, o cliente precisa saber:
    • como designar o serviço Si;
    • a lista de parâmetros a fornecer e seus tipos;
    • o tipo de resultado devolvido pelo serviço. Conhecidos esses elementos, o diálogo cliente/servidor segue o mesmo formato, qualquer que seja o serviço web consultado. O código do cliente fica, assim, padronizado;
  • para se proteger de ataques vindos da Internet, muitas organizações abrem para o exterior apenas algumas portas de seus servidores: principalmente as portas 80 (HTTP) e 443 (HTTPS) para o serviço web. Todas as outras portas são bloqueadas. Consequentemente, as aplicações cliente/servidor como as descritas no capítulo anterior ficam em geral restritas à rede privada (intranet) da organização. Hospedar um serviço em um servidor web o torna acessível a toda a comunidade da Internet;
  • o serviço web pode ser visto como um objeto remoto: os serviços que ele oferece se tornam então métodos desse objeto. Um cliente pode usar esse objeto remoto como se fosse local, por meio de um objeto intermediário chamado proxy, que oculta toda a comunicação de rede. Isso permite construir um cliente independente dessa camada: se a camada mudar, o restante do cliente não precisa ser modificado;
  • como nas aplicações cliente/servidor TCP/IP do capítulo anterior, o cliente e o servidor podem ser escritos em qualquer linguagem de programação. Eles trocam linhas de texto compostas de duas partes: os cabeçalhos exigidos pelo protocolo HTTP e o corpo da mensagem, cujo formato é combinado entre o cliente e o servidor.

A arquitetura de uma aplicação cliente/servidor baseada em serviços web é a seguinte:

Image

Trata-se de uma extensão da arquitetura em camadas do Capítulo 6, à qual se acrescentam camadas especializadas de comunicação de rede: o cliente do serviço web no lado do cliente e o próprio serviço web no lado do servidor. Já encontramos uma arquitetura semelhante com o servidor TCP de cálculo do imposto (versão 8) do capítulo anterior.

13.1.1. Ontem: SOAP e WSDL

Nos anos 2000, os serviços web seguiam mais frequentemente o padrão SOAP (Simple Object Access Protocol). O cliente enviava uma requisição HTTP POST cujo corpo era um documento XML: um “envelope” contendo o nome do método chamado e seus parâmetros. O servidor respondia com outro envelope XML contendo o resultado. Cada serviço era descrito por um documento XML no formato WSDL (Web Services Description Language), disponível na URL do serviço seguida de [?wsdl]: ele listava os métodos, seus parâmetros e seus tipos. A partir desse documento, ferramentas geravam automaticamente o proxy do serviço.

Em Java, esses serviços eram escritos com a API JAX-WS: uma classe anotada com [@WebService], cujos métodos públicos (que podiam ser anotados com [@WebMethod]) se tornavam os métodos do serviço; a ferramenta [wsimport] gerava o proxy do cliente a partir do WSDL. O JAX-WS fez parte do JDK do Java 6 ao Java 10; foi removido no Java 11 (JEP 320) e hoje existe fora do JDK, com o nome Jakarta XML Web Services. Ainda é encontrado em aplicações legadas, mas novos serviços raramente o usam. Entre as razões desse abandono estão o peso do XML e dos envelopes SOAP, a complexidade dos padrões associados (WS-Security, WS-Addressing etc.) e a dificuldade de chamar esses serviços a partir de um navegador.

13.1.2. Hoje: REST e JSON

A maioria dos serviços web atuais segue o estilo REST (REpresentational State Transfer) e troca documentos JSON (JavaScript Object Notation, apresentado no Capítulo 5). O estilo REST se baseia nos seguintes princípios:

  • o serviço expõe recursos, cada um designado por uma URL: [/tax], [/clients/12], [/clients/12/orders];
  • esses recursos são acessados por meio dos métodos (também chamados de verbos) do protocolo HTTP, cada um com um significado específico;
  • o resultado da ação é indicado pelo código de status HTTP da resposta;
  • o corpo das requisições e das respostas é, na maioria das vezes, um documento JSON, mais compacto e mais simples que o XML;
  • o serviço é sem estado (stateless): cada requisição contém todas as informações necessárias ao seu processamento; o servidor não guarda nenhuma informação de uma requisição para a seguinte para um dado cliente.

Os métodos HTTP mais usados são os seguintes:

Método
Uso
Exemplo
GET
Ler um recurso; eventuais parâmetros ficam na URL
GET /clients/12
POST
Criar um recurso ou solicitar um processamento; os dados ficam no corpo da requisição
POST /clients
PUT
Substituir um recurso
PUT /clients/12
PATCH
Modificar parte de um recurso
PATCH /clients/12
DELETE
Excluir um recurso
DELETE /clients/12

Os códigos de status, apresentados no capítulo anterior, assumem aqui todo o seu sentido:

Código
Significado
200 OK
A requisição foi bem-sucedida; o corpo da resposta contém o resultado
201 Created
O recurso foi criado; o cabeçalho [Location] fornece sua URL
204 No Content
A requisição foi bem-sucedida; a resposta não tem corpo
400 Bad Request
A requisição é inválida (parâmetro ausente ou inválido etc.)
404 Not Found
O recurso solicitado não existe
415 Unsupported Media Type
O tipo do documento enviado (cabeçalho [Content-Type]) não é aceito
500 Internal Server Error
Ocorreu um erro inesperado no servidor

Um serviço REST não tem um equivalente obrigatório ao WSDL. No entanto, é prática comum descrevê-lo com um documento OpenAPI (antigo Swagger), no formato JSON ou YAML, a partir do qual ferramentas podem gerar documentação, páginas de teste e clientes. Voltaremos a isso mais adiante.

Por fim, note o gRPC, concebido pelo Google: os métodos do serviço e suas mensagens são descritos em um arquivo [.proto], a partir do qual ferramentas geram o servidor e o cliente, como se fazia na época do WSDL; as mensagens são codificadas em um formato binário compacto (Protocol Buffers) e transmitidas por HTTP/2. O gRPC é muito eficiente e popular para a comunicação entre serviços de uma mesma organização, mas é pouco adequado a navegadores. Ele está disponível em Java com a biblioteca [grpc-java], que não usaremos.

13.1.3. Spring Boot e Spring MVC

Para escrever nossos serviços web, usaremos o Spring Boot. No Capítulo 6, usamos o contêiner de injeção de dependência do Spring Framework. Esse framework também inclui um módulo web, o Spring MVC, que associa uma URL e um método HTTP a um método Java por meio de anotações: [@RestController] na classe, [@GetMapping], [@PostMapping]… em seus métodos. O Spring Boot (versão 1.0 em 2014, versão 4 em novembro de 2025, com o Spring Framework 7) simplifica a implementação do Spring:

  • ele configura automaticamente a aplicação com base nas bibliotecas disponíveis: se o Spring MVC e o Jackson estiverem presentes, ele prepara tudo o que é necessário para um serviço web JSON, sem uma única linha de configuração;
  • ele embute o servidor web na aplicação: o servidor Tomcat (versão 11) é simplesmente uma biblioteca, iniciada pelo programa principal. Portanto, não é necessário instalar um servidor web ou um servidor de aplicações à parte (Tomcat, GlassFish, WildFly…), no qual a aplicação costumava ser implantada como um arquivo [.war];
  • ele fornece os starters, dependências Maven que reúnem tudo o que é necessário para um uso específico. O starter [spring-boot-starter-webmvc] inclui o Spring MVC, o Tomcat, o Jackson 3 (Capítulo 5) e o log (SLF4J e Logback);
  • ele fornece um projeto pai Maven, [spring-boot-starter-parent], que especifica as versões de todas essas bibliotecas, compatíveis entre si, e um plugin Maven, [spring-boot-maven-plugin], que inicia a aplicação ([mvn spring-boot:run]) e a empacota em um único arquivo executável, [.jar].

O Spring Boot não é a única solução: o Jakarta EE (antigo Java EE) define a API padrão JAX-RS (Jakarta RESTful Web Services), e frameworks como Quarkus, Micronaut e Helidon também são muito usados. O Spring Boot é, porém, o mais difundido, e se apoia naturalmente no que vimos no Capítulo 6.

13.2. Um primeiro serviço web

Vamos construir nossa primeira aplicação cliente/servidor com a seguinte arquitetura simplificada:

Image

Os projetos deste capítulo são projetos Maven, agrupados na pasta [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

Os projetos já estão preparados no material do curso: o leitor só precisa abrir a pasta [13-web-services] em sua IDE (IntelliJ, IDEA ou VS Code) ou navegar até a pasta de um projeto e digitar o comando Maven indicado. Os serviços são iniciados com [mvn spring-boot:run] e os clientes de console com [mvn compile exec:java]. O arquivo [pom.xml] localizado na raiz da pasta não é um projeto pai: ele apenas lista os seis projetos em uma tag [<modules>], o que permite compilá-los todos de uma vez (digitando [mvn compile] na pasta [13-web-services]).

Para criar você mesmo um projeto Spring Boot, o modo mais fácil é usar o site Spring Initializr: nele, você seleciona Maven, Java, a versão do Spring Boot, o nome do projeto e suas dependências (neste caso, “Spring Web”) e baixa um arquivo ZIP contendo um projeto pronto para uso: o arquivo [pom.xml], a classe principal e o arquivo [application.properties]. O IntelliJ, IDEA e o VS Code (com a extensão “Spring Boot Extension Pack”) oferecem o mesmo assistente.

13.2.1. O lado servidor

Image

O arquivo [pom.xml] do projeto [WsHello] é o seguinte:

<?xml version="1.0" encoding="UTF-8"?>
<!-- o serviço web WsHello: uma aplicação 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>

    <!-- o projeto pai Spring Boot: versões das bibliotecas e configuração dos 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, o servidor Tomcat embutido e o 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 a aplicação; mvn package gera um jar executável dela -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

Comentários:

  • linhas 9–14: o projeto herda do projeto pai do Spring Boot, [spring-boot-starter-parent], baixado como dependência do Maven Central (a tag vazia [<relativePath/>] indica que ele não deve ser procurado na pasta pai). Esse projeto pai especifica as versões de várias centenas de bibliotecas e configura os plugins Maven. É por isso que as dependências e o plugin das linhas 28–31 e 48–51 não têm a tag [<version>]: sua versão é a escolhida pelo Spring Boot 4.1.1;
  • linha 21: a propriedade [java.version] é a usada pelo projeto pai para configurar o compilador; a linha 22 a duplica, em conformidade com os outros projetos do curso;
  • linhas 28–31: a única dependência do projeto é o starter web. Ele fornece o Spring MVC (Spring Framework 7.0), o servidor Tomcat 11 embutido, o Jackson 3 e o log;
  • linha 41: a opção de compilador [-parameters], que preserva os nomes dos parâmetros dos métodos nos arquivos [.class]. O Spring precisa disso para associar um parâmetro de método ([name]) ao parâmetro de mesmo nome em uma URL. O projeto pai já ativa essa opção; nós a incluímos aqui para torná-la visível;
  • linhas 48–51: o plugin do Spring Boot. [mvn spring-boot:run] compila e executa a aplicação; [mvn package] cria um arquivo [target/ws-hello-1.0.jar] contendo a aplicação e todas as suas dependências, que é então executado por [java -jar target/ws-hello-1.0.jar].

A classe principal é a seguinte:

package wshello;

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

// a aplicação Spring Boot WsHello
@SpringBootApplication
public class WsHelloApplication {

    public static void main(String[] args) {
        // inicia o Spring e depois o servidor Tomcat, que espera as requisições
        SpringApplication.run(WsHelloApplication.class, args);
    }
}
  • linha 7: a anotação [@SpringBootApplication] combina três anotações: [@Configuration] (a classe pode definir beans, como no Capítulo 6), [@EnableAutoConfiguration] (configuração automática com base nas bibliotecas disponíveis) e [@ComponentScan] (o Spring procura classes anotadas, como controllers e configurações, no pacote dessa classe e em seus subpacotes);
  • linha 10: aqui mantemos a forma padrão dos métodos [main] e [public static] , sob a qual as ferramentas do Spring Boot procuram a classe principal;
  • linha 12: [SpringApplication.run] lê a configuração (arquivo [application.properties], variáveis de ambiente, argumentos de linha de comando), cria o contêiner Spring e seus beans, inicia o servidor Tomcat e depois devolve o controle. No entanto, o programa não para por aí: as threads do Tomcat esperam requisições até que a aplicação seja encerrada (Ctrl-C).

A configuração da aplicação fica no arquivo [src/main/resources/application.properties]:

1
2
3
4
5
6
7
8
# o nome da aplicação
spring.application.name=WsHello
# a porta de escuta do servidor Tomcat
server.port=5100
# sem banner na inicialização
spring.main.banner-mode=off
# mensagens de log mais curtas: hora, nível, thread, classe, mensagem
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n
  • linha 2: o nome da aplicação;
  • linha 4: o servidor escuta na porta 5100 (8080 por padrão). Esse valor também pode ser passado como argumento: [mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=5100], ou pela variável de ambiente [SERVER_PORT];
  • linha 6: por padrão, o Spring Boot exibe na inicialização um grande banner com texto ASCII; nós o removemos;
  • linha 8: o formato das mensagens de log. O formato padrão é muito completo (data, nível, ID do processo, nome da aplicação, thread, nome completo da classe, mensagem), mas resulta em linhas muito longas. Nós o reduzimos à hora, ao nível da mensagem, ao nome da thread, ao nome curto da classe emissora ([%logger{0}]) e à mensagem.

O serviço web propriamente dito é a classe [HelloController]. Ela oferece um método que devolve a string [Hello Mrs xx], em que xx é o nome recebido:

package wshello;

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

// o serviço web WsHello: cada método público anotado trata uma URL
@RestController
public class HelloController {

    // a raiz do site: um texto de boas-vindas
    @GetMapping("/")
    public String home() {
        return "WsHello web service: try /hello/{name} or /greeting/{name}";
    }

    // um "método web" que virou URL: ele cumprimenta a senhora
    // o segmento {name} da URL é passado ao parâmetro [name] do método
    // uma string é retornada como está (text/plain)
    @GetMapping("/hello/{name}")
    public String hello(@PathVariable String name) {
        return "Hello Mrs " + name;
    }

    // a mesma coisa com uma resposta JSON: um objeto é serializado em JSON (application/json)
    @GetMapping("/greeting/{name}")
    public Greeting greeting(@PathVariable String name) {
        return new Greeting(name, "Hello Mrs " + name);
    }

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

Comentários:

  • linha 8: a anotação [@RestController] designa a classe como um controller: o Spring cria uma única instância dela (um singleton) na inicialização e lhe atribui as requisições HTTP cuja URL corresponde a um de seus métodos. O resultado de cada método é enviado como está ao cliente, no corpo da resposta;
  • linhas 12–15: a anotação [@GetMapping("/")] associa o método HTTP GET e a URL [/] (a raiz do site) ao método [home], que devolve um texto explicando como usar o serviço;
  • Linhas 20–23: a URL do template (chamada de rota) [/hello/{name}] contém uma variável [{name}]: ela corresponde a qualquer segmento de URL que venha depois de [/hello/]. Assim, a URL [/hello/Carla%20Bruni] atribui o valor [Carla Bruni] a [{name}] (o código [%20] representa um espaço na URL). A anotação [@PathVariable] (linha 21) instrui o Spring a passar esse valor ao parâmetro do método de mesmo nome: isso é o binding de dados. O método retorna uma string, que é enviada tal como está ao cliente, como um documento de texto (tipo [text/plain]);
  • linhas 26–29: o mesmo processo, mas o método retorna um objeto do tipo [Greeting]. O Spring serializa ele para JSON usando o Jackson (Capítulo 5) e o envia ao cliente como um documento do tipo [application/json]. Esse é o formato padrão da resposta de um serviço web REST;
  • linhas 32–33: o tipo do resultado, um record (Capítulo 4), declarado dentro do controller. O Jackson sabe serializar records: cada componente se torna uma propriedade JSON com o mesmo nome.

O serviço é iniciado pelo comando [mvn spring-boot:run], digitado na pasta do projeto. Ele exibe seu log (o curso abreviou os caminhos da linha 2 para [...]):

> 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
  • linha 2: a inicialização da aplicação, a versão do Java e o diretório de execução, que é o diretório do projeto;
  • linha 3: o Spring permite definir perfis (desenvolvimento, teste, produção etc.) que ativam configurações diferentes (arquivos [application-dev.properties] etc.). Nenhum perfil está ativo aqui;
  • linhas 4–6: o servidor Tomcat embutido é criado; ele escutará na porta 5100;
  • linha 7: o contêiner do Spring está pronto: ele criou seus beans, entre eles o nosso controller;
  • linhas 8–9: o Tomcat agora aceita conexões; a aplicação está pronta. A inicialização levou cerca de dez segundos em nossa máquina de teste, o que é bastante lento; normalmente leva dois ou três segundos;
  • linhas 10–12: essas mensagens apareceram durante a primeira requisição: o servlet do Spring [DispatcherServlet], que recebe todas as requisições e as distribui entre os métodos dos controllers, só é inicializado nesse momento. Um servlet é um componente Java que processa requisições em um servidor web como o Tomcat (Jakarta Servlet); o Spring é construído sobre ele. O nome da thread, [http-nio-5100-exec-1], indica que a requisição está sendo processada por uma das threads do servidor Tomcat;
  • linhas 13–14: essas mensagens apareceram quando o servidor foi encerrado com Ctrl-C, após os testes descritos nos parágrafos seguintes; o encerramento foi “gracioso” (graceful): o Tomcat conclui as requisições pendentes antes de encerrar.

Cada mensagem de log indica a hora, o nível ([TRACE], [DEBUG], [INFO], [WARN], [ERROR]), a thread que a emitiu e a classe emissora. As mensagens de nível [INFO] e superiores são exibidas por padrão; a propriedade [logging.level.<package>=DEBUG] também exibe mensagens de nível inferior para um determinado pacote.

13.2.2. Consulta ao serviço com curl

Enquanto o serviço está em execução, vamos consultá-lo em uma segunda janela de comando, usando a ferramenta [curl] apresentada no capítulo anterior. A opção [-i] exibe os cabeçalhos da resposta antes do corpo, e a opção [-s] (silent) suprime a barra de progresso:

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
  • Linha 2: a requisição foi bem-sucedida. O Tomcat não envia o texto que normalmente acompanha o código de status ([OK]): ele é opcional desde o HTTP/1.1 (e deixou de existir no HTTP/2); só o código importa;
  • Linha 3: o documento é um texto (UTF-8);
  • linha 4: o tamanho do documento, em bytes;
  • linha 5: a hora da resposta, sempre expressa em Tempo Universal Coordenado (GMT) nos cabeçalhos HTTP, enquanto o log do servidor usa a hora local;
  • linha 7: o resultado do método [hello].

Agora vamos solicitar a versão 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"}
  • linha 3: o documento agora é do tipo [application/json]. Não é necessário especificar o conjunto de caracteres: um documento JSON trocado pela rede é sempre codificado em UTF-8 (RFC 8259);
  • Linha 7: o objeto [Greeting] serializado. As propriedades JSON [name] e [message] correspondem aos nomes dos componentes do record. Como os nomes em Java já estão no formato “camelCase”, que também é o usado em JavaScript e JSON, não há nada a converter.

Uma URL que não corresponde a nenhuma rota retorna uma resposta 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"}
  • Linha 4: o documento é enviado em partes (chunks), cada uma precedida por seu tamanho; o servidor não precisou calcular o tamanho total do documento antes de começar a enviá-lo;
  • linha 7: o documento de erro gerado pelo Spring Boot: a data, o código de status, seu texto e o caminho solicitado. Por motivos de segurança, ele não contém nem a mensagem de eventual exceção nem a pilha de chamadas (propriedades [server.error.include-message] e [server.error.include-stacktrace], desativadas por padrão). Veremos no próximo serviço como obter um documento de erro padronizado.

Você também pode digitar a URL [http://localhost:5100/hello/Carla Bruni] na barra de endereços de um navegador, que exibirá o texto recebido: um serviço web consultado por GET pode ser testado com muita facilidade.

13.2.3. Um cliente de console

Image

É possível escrever o cliente do serviço usando um simples cliente TCP, como no capítulo anterior: basta enviar a requisição HTTP e ler a resposta. No entanto, usamos a classe [java.net.http.HttpClient] (Java 11), também apresentada no capítulo anterior, que cuida do protocolo HTTP para nós e usa o Jackson para os documentos JSON. O projeto [ClientWsHello] é um projeto Maven padrão, cujo arquivo [pom.xml] declara a dependência do Jackson e a classe principal:

    <dependencies>
        <!-- Jackson para ler as respostas 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 executa a classe principal -->
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>exec-maven-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <mainClass>clientwshello.Main</mainClass>
                </configuration>
            </plugin>

Seu código é o seguinte:

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 console do serviço web WsHello
public class Main {

    // a resposta JSON do serviço: mesmos nomes de componentes que no lado do servidor
    record Greeting(String name, String message) {
    }

    public static void main(String[] args) throws InterruptedException {
        // a URL do serviço pode ser passada como argumento
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5100/");
        // o conversor Jackson JSON <-> objetos
        JsonMapper mapper = JsonMapper.builder().build();

        // um único cliente HTTP durante toda a execução do programa
        try (HttpClient client = HttpClient.newHttpClient()) {
            while (true) {
                // o nome da senhora
                String input = IO.readln("Name of the lady (nothing to stop): ");
                String name = input == null ? "" : input.strip();
                if (name.isEmpty()) {
                    break;
                }
                try {
                    // o nome é colocado no caminho da URL: ele deve ser codificado nela
                    String encodedName = URLEncoder.encode(name, StandardCharsets.UTF_8).replace("+", "%20");
                    // 1 - resposta em texto
                    String text = get(client, serviceUrl.resolve("hello/" + encodedName));
                    IO.println("[text] " + text);
                    // 2 - resposta JSON, desserializada em um objeto Greeting
                    String json = get(client, serviceUrl.resolve("greeting/" + encodedName));
                    Greeting greeting = mapper.readValue(json, Greeting.class);
                    IO.println("[JSON] " + greeting);
                } catch (ConnectException e) {
                    // nenhum serviço escuta neste endereço (a exceção não tem mensagem)
                    IO.println("Error: ConnectException: connection refused (" + serviceUrl + ")");
                } catch (IOException e) {
                    // o serviço respondeu com um erro, ou a comunicação falhou
                    IO.println("Error: " + e.getClass().getSimpleName() + " : " + e.getMessage());
                }
            }
        }
    }

    // uma requisição GET cujo corpo da resposta é retornado como string
    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());
        // um código de status diferente de 2xx é um erro
        if (response.statusCode() / 100 != 2) {
            throw new IOException("the service responded " + response.statusCode() + " for " + url);
        }
        return response.body();
    }
}

Comentários:

  • Linhas 16–18: a resposta do serviço, em JSON, será desserializada em um objeto [Greeting]. O cliente não tem acesso ao tipo [Greeting] do servidor; ele declara o seu próprio, com os mesmos nomes de componentes. Um cliente não compartilha o código do servidor, apenas o formato dos documentos trocados;
  • linha 22: a URL do serviço é passada como argumento ou, na falta dele, assume por padrão [http://localhost:5100/]: se o endereço do serviço mudar, o cliente não precisa ser recompilado;
  • linha 24: o conversor JSON do Jackson 3 (Capítulo 5);
  • linha 27: um único [HttpClient] para todo o programa. Ele gerencia um conjunto de conexões reutilizáveis e deve ser compartilhado, não recriado a cada requisição. A partir do Java 21, [HttpClient] implementa [AutoCloseable]: a instrução [try] com recurso o fecha ao final do programa;
  • linha 37: o nome digitado se torna um segmento de URL: os caracteres nela não permitidos devem ser codificados. [URLEncoder.encode] codifica o “é” como [%C3%A9], mas é destinado a parâmetros de formulário, nos quais o espaço é codificado como [+]. No caminho de uma URL, o espaço deve ser codificado como [%20]: por isso substituímos o [+] (um [+] digitado pelo usuário é codificado como [%2B] e não é afetado);
  • linha 39: o método [resolve] da classe [URI] constrói uma URL a partir da URL base e de uma URL relativa. Atenção: a URL base deve terminar com [/] para que [hello/...] seja acrescentado a ela;
  • linhas 42–43: a resposta JSON é desserializada em um objeto [Greeting] por meio do método [readValue] do Jackson;
  • linhas 45–47: a exceção [ConnectException] é lançada quando é impossível conectar-se ao serviço, por exemplo, quando nenhum serviço escuta no endereço especificado. Ela não tem mensagem; nós construímos uma. Esse [catch] deve preceder o da linha 48, porque [ConnectException] deriva de [IOException];
  • linhas 48–50: outros erros de comunicação e respostas de erro do serviço (veja a linha 62);
  • linhas 57–65: uma requisição GET, cujo corpo da resposta é obtido como uma string;
  • linha 58: a requisição é construída com um builder: a URL, o método HTTP e, por fim, [build];
  • Linha 59: o método [send] envia a requisição e aguarda a resposta. Seu segundo parâmetro, um [BodyHandler], especifica o que fazer com o corpo da resposta: [ofString] lê todo o corpo em uma string, decodificada de acordo com o conjunto de caracteres especificado pelo cabeçalho [Content-Type] (UTF-8 por padrão). [send] lança uma [IOException] em caso de erro de comunicação e uma [InterruptedException] se a thread for interrompida durante a espera; o programa principal deixa esta última se propagar para cima (linha 20);
  • linhas 61–63: ao contrário de outras bibliotecas, [HttpClient] não trata um código de status de erro (4xx, 5xx) como exceção: a resposta é retornada normalmente, e cabe a nós examinar seu código. Aqui, lançamos uma [IOException] para qualquer código diferente de 2xx.

Resultados, com o serviço em execução:

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

A linha 4 exibe o objeto [Greeting] recebido, no formato do método [toString] gerado para os records. A opção [-q] (quiet) do Maven suprime as mensagens do próprio Maven. Se você especificar um endereço no qual nenhum serviço escuta, a conexão é recusada:

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

E se a URL do serviço estiver incorreta, o serviço retorna um 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): 

Com um serviço SOAP, o cliente usava um proxy gerado a partir do WSDL do serviço e chamava o método remoto como se fosse um método local. Aqui, chamamos diretamente a URL do serviço. Escreveremos um proxy de verdade para o serviço de cálculo do imposto.

13.2.4. Descrição do serviço: OpenAPI

O WSDL descrevia um serviço SOAP em um formato padronizado. Seu equivalente atual é o documento OpenAPI. Para o Spring Boot, a biblioteca [springdoc-openapi] (dependência [org.springdoc:springdoc-openapi-starter-webmvc-ui]) o gera sem uma única linha de código: ela examina os controllers e suas anotações na inicialização e publica o documento na URL [/v3/api-docs], bem como uma página interativa de testes, o Swagger UI, na URL [/swagger-ui.html]. O documento descreve cada rota: sua URL, seu método HTTP, seus parâmetros e respectivos tipos, e o esquema JSON de suas respostas. Geradores como o OpenAPI Generator o utilizam para gerar um cliente tipado em diversas linguagens, exatamente como [wsimport] fazia com o WSDL. Essa biblioteca não faz parte do Spring Boot, e não a usaremos neste capítulo.

13.3. Um serviço web para operações aritméticas

O serviço anterior oferecia um único método. Vamos agora considerar um serviço web que fornece as quatro operações aritméticas: add(a, b), subtract(a, b), multiply(a, b) e divide(a, b). Aproveitaremos para explorar as duas maneiras de passar parâmetros a um serviço web e o tratamento de erros.

13.3.1. O lado do servidor

O serviço [WsOperations] aceita dois tipos de requisições:

Requisição
Parâmetros
GET /add?a=1.5&b=2
A operação no caminho da URL, os números em sua query string
POST /calculation
um documento JSON no corpo da requisição: [{"operation":"add","a":1.5,"b":2}]

Em ambos os casos, a resposta é um documento JSON: [{"operation":"add","a":1.5,"b":2.0,"result":3.5}]. O GET é adequado para requisições simples que não modificam nada no servidor: a URL pode ser digitada em um navegador, salva nos favoritos, e sua resposta pode ser armazenada em cache. O POST é adequado para dados volumosos ou estruturados. O arquivo [pom.xml] do projeto é igual ao de [WsHello], exceto pelo nome do projeto ([ws-operations]), e sua classe principal, [WsOperationsApplication], é idêntica à de [WsHello]. Seu arquivo [application.properties] é o seguinte:

# o nome da aplicação
spring.application.name=WsOperations
# a porta de escuta do servidor Tomcat
server.port=5110
# os erros detectados pelo Spring MVC são informados no formato "Problem Details" (RFC 9457)
spring.mvc.problemdetails.enabled=true
# sem banner na inicialização
spring.main.banner-mode=off
# mensagens de log mais curtas: hora, nível, thread, classe, mensagem
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n
  • linha 4: o serviço escuta na porta 5110;
  • linha 6: os erros detectados pelo próprio Spring MVC (URL desconhecida, documento JSON inválido, tipo de documento não suportado etc.) serão informados por meio de uma resposta no formato Problem Details . Esse formato, padronizado pela RFC 9457, é um documento JSON do tipo [application/problem+json] que descreve um erro: seu tipo, um título, o código de status, um detalhe e eventuais informações adicionais. Essa é a maneira padrão de um serviço REST indicar o que está errado.

O validador é o seguinte:

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;

// o serviço web WsOperations: as quatro operações aritméticas
@RestController
public class OperationsController {

    // GET /add?a=1.5&b=2 (idem para subtract, multiply, divide)
    // [operation] vem do caminho da URL, [a] e [b] de sua query string
    @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 com um corpo JSON: {"operation":"add","a":1.5,"b":2}
    // o corpo JSON é desserializado no parâmetro [request]
    @PostMapping("/calculation")
    public ResponseEntity<?> calculatePost(@RequestBody CalculationRequest request) {
        return calculate(request.operation(), request.a(), request.b());
    }

    // um número escrito com ponto decimal, null se estiver ausente ou incorreto
    private static Double readNumber(String text) {
        if (text == null) {
            return null;
        }
        try {
            double number = Double.parseDouble(text);
            // NaN e infinitos são recusados
            return Double.isFinite(number) ? number : null;
        } catch (NumberFormatException e) {
            return null;
        }
    }

    // o cálculo comum aos dois métodos HTTP
    private static ResponseEntity<?> calculate(String operation, Double a, Double b) {
        // a operação solicitada, null se for desconhecida
        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;
        };
        // verificação dos parâmetros: os erros são acumulados
        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()) {
            // resposta 400 com a lista de erros
            ProblemDetail problem = ProblemDetail.forStatus(HttpStatus.BAD_REQUEST);
            problem.setTitle("Incorrect parameters");
            problem.setProperty("errors", errors);
            return ResponseEntity.badRequest().body(problem);
        }
        // a divisão por zero é recusada: resposta 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);
        }
        // resposta 200 com o resultado em JSON
        return ResponseEntity.ok(new CalculationResult(name, a, b, calculation.applyAsDouble(a, b)));
    }

    // a requisição de cálculo (corpo da requisição POST): os números ausentes do JSON são null
    public record CalculationRequest(String operation, Double a, Double b) {
    }

    // o resultado de um cálculo (corpo da resposta)
    public record CalculationResult(String operation, double a, double b, double result) {
    }
}

Comentários:

  • Linhas 24–28: a requisição GET. O parâmetro [operation] do método está vinculado à variável de rota [{operation}] ([@PathVariable]). Os parâmetros [a] e [b], anotados com [@RequestParam], são vinculados aos parâmetros de mesmo nome na query string ([?a=1.5&b=2]). Eles são opcionais ([required = false]): um parâmetro ausente é tratado como [null]; caso contrário, o Spring rejeitaria com uma resposta 400 uma requisição em que faltasse qualquer um deles;
  • Linha 26: [a] e [b] são declarados como do tipo [String]. Poderíamos tê-los declarado como do tipo [double] ou [Double]: o Spring teria então feito a conversão por conta própria e rejeitado um valor incorreto com uma resposta 400 contendo uma mensagem de erro genérica. Ao recebê-los como strings, mantemos o controle sobre as mensagens de erro;
  • linhas 32–35: a requisição POST. O parâmetro [request], anotado com [@RequestBody], é construído pelo Jackson a partir do corpo JSON da requisição. Seus componentes são do tipo [Double] (linha 93), e não [double]: uma propriedade ausente do documento JSON é então avaliada como [null], o que permite detectá-la;
  • linhas 38–49: conversão de uma string em número; se falhar, o resultado é [null]. Tanto na URL quanto no JSON, os números são escritos com ponto decimal: [Double.parseDouble], que é independente do idioma do sistema, é portanto a ferramenta correta (e não [NumberFormat], que esperaria uma vírgula em um servidor francês, Capítulo 5). Ele também aceita os textos [NaN] e [Infinity], que rejeitamos (linha 45);
  • linha 54: o nome da operação, em minúsculas. [Locale.ROOT] realiza a conversão independentemente do idioma do sistema;
  • linhas 55–61: a operação solicitada é representada por uma interface funcional (Capítulo 7), [DoubleBinaryOperator], cujo método [applyAsDouble(double, double)] retorna um [double]. Uma expressão [switch] seleciona a lambda correspondente à operação; para uma operação desconhecida, ela seleciona [null];
  • linhas 63–73: os três parâmetros são validados acumulando os erros em um dicionário que associa cada parâmetro à sua lista de mensagens de erro. Um [LinkedHashMap] preserva a ordem de inserção;
  • linhas 74–80: se um erro for encontrado, uma resposta 400 é retornada. A classe [ProblemDetail] do Spring representa um documento “Problem Details”: [forStatus] o cria com um código de status, [setTitle] define seu título e [setProperty] acrescenta uma propriedade a ele, neste caso [errors], a lista de erros. A classe [ResponseEntity] representa uma resposta HTTP completa: código de status, cabeçalhos e corpo. [ResponseEntity.badRequest()] prepara uma resposta 400, e [body] fornece o corpo dela;
  • linhas 82–87: a divisão por zero é rejeitada com uma resposta 400, cujo documento desta vez inclui um detalhe ([forStatusAndDetail]). Essa rejeição é necessária: em Java, dividir um [double] por zero não lança uma exceção, mas retorna infinito ([Double.POSITIVE_INFINITY]), que um documento JSON não consegue representar (o Jackson o escreveria como uma string, ["Infinity"]). O teste [b == 0] compara o valor do objeto [Double] com zero: o Java faz automaticamente o “unboxing” dele;
  • linha 89: a resposta 200, cujo corpo é o objeto [CalculationResult] serializado em JSON;
  • linhas 93–98: os dois tipos trocados com os clientes. Esses objetos, usados unicamente para transportar dados entre duas aplicações, são chamados de DTO (Data Transfer Object). Os records são ideais para essa finalidade.

Os dois métodos do controller retornam o tipo [ResponseEntity<?>]: uma resposta cujo corpo pode ser de qualquer tipo, neste caso um [CalculationResult] ou um [ProblemDetail]. O Spring examina o tipo real do corpo para serializá-lo; ele atribui ao documento o tipo [application/json], ou [application/problem+json] para um [ProblemDetail].

13.3.2. Testes com curl

O serviço é iniciado por [mvn spring-boot:run] na pasta [WsOperations]. Uma adição:

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}

O número 2 virou 2.0: o Jackson sempre escreve um [double] com sua parte decimal. Para um cliente, em particular JavaScript, é o mesmo número. Uma divisão por zero:

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"}
  • Linha 2: a requisição é negada;
  • linha 3: o corpo é um documento “Problem Details”;
  • linha 6: após uma resposta 400, o Tomcat fecha a conexão por precaução: uma requisição inválida pode ter deixado dados inesperados na conexão. O cliente abrirá outra para sua próxima requisição;
  • linha 8: o documento contém as propriedades [title], [status] e [detail], definidas por nosso código, e [instance], acrescentada pelo Spring: o caminho da requisição que causou o erro. A propriedade [type], uma URL que documenta o tipo de erro, está ausente: a RFC 9457 lhe atribui então o valor [about:blank], o que significa que o código de status basta para descrever o problema. Observe que as propriedades estão em ordem alfabética: esse é o comportamento padrão do Jackson 3 para classes comuns como [ProblemDetail]; os records, por outro lado, mantêm a ordem de seus componentes.

Uma operação desconhecida, um número escrito com vírgula decimal e um 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"]}}

A propriedade [errors] do documento contém os erros de validação, parâmetro por parâmetro; acrescentada por [setProperty], ela é colocada depois das propriedades normalizadas. Agora uma consulta POST. A opção [-d] de [curl] envia o texto que a segue no corpo de uma requisição POST, e a opção [-H] acrescenta um cabeçalho à requisição, neste caso o tipo do 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}

Se o documento JSON enviado for inválido, o Jackson não consegue construir o parâmetro [request]: o Spring responde com um erro 400 por conta própria, sem executar nosso 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"}

O documento “Problem Details” da linha 8 foi gerado pelo Spring MVC, graças à propriedade [spring.mvc.problemdetails.enabled]; sem ela, obteríamos o documento de erro do Spring Boot visto com [WsHello]. O mesmo ocorre se o cabeçalho [Content-Type] for omitido: [curl] passa então a enviar o corpo como um formulário HTML, e o Spring rejeita esse 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"}

O código 415 (Unsupported Media Type) significa que o tipo de documento enviado não é aceito; o cabeçalho [Accept] da linha 3 informa ao cliente quais tipos são aceitos.

13.3.3. O lado do cliente

Image

Nosso cliente de console solicita a operação e os dois números em uma única linha e depois consulta o serviço duas vezes: primeiro com GET, depois com POST, para demonstrar os dois métodos. Seu arquivo [pom.xml] é idêntico ao de [ClientWsHello], exceto pelo nome do projeto e pela classe principal. Seu programa é o seguinte:

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 console do serviço web WsOperations
public class Main {

    // os objetos trocados com o serviço (os nomes dos componentes são os do JSON)
    record CalculationRequest(String operation, double a, double b) {
    }

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

    // uma resposta de erro no formato "Problem Details"
    record Problem(String title, String detail, Integer status, Map<String, List<String>> errors) {
    }

    // os números são digitados e exibidos na cultura atual (fr-FR: vírgula decimal, en-US: ponto 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/");
        // o conversor JSON; o Jackson 3 ignora as propriedades JSON desconhecidas (instance...)
        JsonMapper mapper = JsonMapper.builder().build();

        try (HttpClient client = HttpClient.newHttpClient()) {
            while (true) {
                // entrada da operação e dos dois números (separador decimal da cultura atual)
                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;
                }
                // verificação local dos dois números, antes de qualquer chamada ao serviço
                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 - requisição GET: na URL, os números são escritos com ponto 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 {
                        // falha: o código de status e o documento recebido são exibidos, tal como estão
                        IO.println("[GET " + url + "] error " + response.statusCode()
                                + " : " + response.body());
                    }
                } catch (IOException e) {
                    // o serviço está inacessível
                    IO.println("[GET " + url + "] error: " + e);
                }

                // 2 - requisição POST: a requisição é enviada em JSON no corpo da requisição
                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) {
                        // sucesso: o corpo contém o resultado
                        CalculationResult result = mapper.readValue(response.body(), CalculationResult.class);
                        IO.println("[POST calculation] " + calculation + " = " + FORMAT.format(result.result()));
                    } else {
                        // falha: o corpo contém a descrição do 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) {
                    // o serviço está inacessível
                    IO.println("[POST calculation] error: " + e);
                }
            }
        }
    }

    // um número digitado na cultura atual, null se a entrada não for um
    private static Double readNumber(String text) {
        ParsePosition position = new ParsePosition(0);
        Number number = FORMAT.parse(text, position);
        // a entrada deve ter sido lida por inteiro: "2.5x" é recusado
        return number == null || position.getIndex() != text.length() ? null : number.doubleValue();
    }
}

Comentários:

  • Linhas 20–29: os arquivos DTO do cliente. Eles são declarados novamente aqui: um cliente não compartilha o código do servidor, apenas o formato dos documentos JSON trocados. A classe [ProblemDetail] do Spring faz parte do framework web; um simples record basta para o cliente. Seus componentes são tipos de objeto ([String], [Integer], [Map]): uma propriedade ausente do documento, como [detail] ou [errors], é definida como [null];
  • linha 32: os números são digitados e exibidos no formato do idioma do sistema, neste caso o inglês: ponto decimal;
  • Linha 37: a partir do Jackson 3, as propriedades desconhecidas do record (aqui, [instance]) são ignoradas por padrão durante a desserialização;
  • linhas 51–63: os números são verificados localmente antes de qualquer chamada ao serviço. Um serviço deve sempre verificar seus parâmetros (pois não sabe quem o chama), mas um cliente pode evitar tráfego de rede desnecessário;
  • linha 64: o texto que descreve o cálculo, com os números no formato do idioma do sistema;
  • linha 67: a URL da requisição GET. Os números devem ser escritos com ponto decimal: concatenar um [Double] a uma string usa seu método [toString], que é independente do idioma do sistema. A operação, digitada pelo usuário, é codificada com [URLEncoder];
  • linhas 69–70: a requisição GET;
  • linhas 71–74: em caso de sucesso (código de status 200), a resposta JSON é desserializada em um objeto [CalculationResult];
  • linhas 75–79: se a requisição falhar, o código de status e o documento recebido são exibidos tal como estão;
  • linhas 80–83: a exceção [IOException] indica um erro de comunicação, como um serviço inacessível;
  • linhas 87–92: a requisição POST. O objeto [CalculationRequest] é serializado em JSON por [writeValueAsString]; a requisição recebe o cabeçalho [Content-Type], seguido de seu corpo: [BodyPublishers.ofString] envia uma string, codificada em UTF-8;
  • linhas 97–107: em caso de falha, o corpo é um documento “Problem Details”, desserializado em um objeto [Problem], cujo título, detalhes e erros de validação são exibidos. O método [forEach] de um [Map] recebe uma lambda com dois parâmetros: a chave e o valor de cada elemento (Capítulo 7);
  • linhas 118–123: leitura de um número no formato do idioma do sistema. O método [parse(String, ParsePosition)] de [NumberFormat] lê o início da string e indica no objeto [ParsePosition] onde parou: se não parou no final, a entrada contém caracteres excedentes ([2.5x]).

Resultados, com o serviço em execução:

> 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: 
  • linha 3: a URL da consulta GET: os números 1.5 e 2 digitados ali são escritos como 1.5 e 2.0;
  • Linhas 6–8: o mesmo erro observado nas duas requisições: o documento bruto para a requisição GET e seu tratamento para a requisição POST;
  • Linhas 10–12: o serviço detectou uma operação desconhecida;
  • linha 14: o número incorreto foi detectado pelo cliente, que não consultou o serviço.

13.4. Aplicação de exemplo - Versão 9: um serviço web para cálculo do imposto

Retomaremos a aplicação de cálculo do imposto. No capítulo anterior (versão 8), havíamos criado um servidor TCP que podia ser consultado remotamente, usando um protocolo de comunicação próprio. Vamos agora transformá-lo em um serviço web REST.

13.4.1. A arquitetura

A arquitetura da versão 9 é a seguinte:

Image

  • no lado do servidor, o serviço web [WsTax] recebe requisições HTTP e as faz processar pelas camadas [business] e [dao] da versão 5 (Capítulo 6), que são reutilizadas sem alterações;
  • no lado do cliente, a camada [ui] da versão 5 também é reutilizada sem alterações. Ela se comunica com um novo tipo de camada [business], [TaxBusinessHttp], que implementa a interface [ITaxBusiness] consultando o serviço web: ela atua como um proxy do serviço. A camada [ui] ignora que o cálculo é realizado em outra máquina;
  • em ambos os lados, a integração das camadas é feita pelo contêiner de injeção de dependência do Spring, como na versão 5.

13.4.2. O serviço web

O contrato do serviço é o seguinte:

Requisição
Resposta em caso de sucesso
Resposta em caso de erro
GET /tax?married=y&children=2&salary=60000
200: [{"tax":4282}]
400: documento “Problem Details”
POST /tax com o corpo [{"married":true,"children":2,"salary":60000}]
200: [{"tax":4282}]
400: documento “Problem Details”

O projeto [WsTax] depende dos módulos [tax-dao] e [tax-business] da versão 5. Para que o Maven os encontre, é preciso primeiro instalá-los no repositório Maven local da máquina (a pasta [.m2/repository] no diretório pessoal do usuário), digitando [mvn install] na pasta [06-architectures/TaxV5] (Capítulo 6). As dependências do arquivo [pom.xml] de [WsTax] ficam então como a seguir (o restante do arquivo é igual ao de [WsHello], exceto pelo nome do projeto: [examples.tax:ws-tax:9.0]):

    <dependencies>
        <!-- Spring MVC, o servidor Tomcat embutido e o Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-webmvc</artifactId>
        </dependency>
        <!-- as camadas [dao] e [business] da versão 5, reutilizadas como estão -->
        <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>
  • Linhas 7–17: os dois módulos da versão 5, identificados por suas coordenadas Maven. O módulo [tax-dao] também inclui as classes [TaxBracket] e [TaxException] da camada [entities]. Esses módulos dependem do Jackson 3.1.5, que o starter web já fornece.

O arquivo de configuração [application.properties] é o seguinte:

# o nome da aplicação
spring.application.name=WsTax
# a porta de escuta do servidor Tomcat
server.port=5120
# os erros detectados pelo Spring MVC são informados no formato "Problem Details" (RFC 9457)
spring.mvc.problemdetails.enabled=true
# sem banner na inicialização
spring.main.banner-mode=off
# mensagens de log mais curtas: hora, nível, thread, classe, mensagem
logging.pattern.console=%d{HH:mm:ss.SSS} %-5level [%thread] %logger{0} : %msg%n

# a camada [dao]: sua implementação e seu arquivo de dados
dao.implementation=JsonTax
dao.file=TaxData.json
  • linha 4: o serviço escuta na porta 5120;
  • Linhas 13–14: a configuração da camada [dao], no mesmo formato do arquivo [tax.properties] da versão 5: a implementação a usar e seu arquivo de dados. Não são propriedades do Spring Boot, mas propriedades específicas de nossa aplicação: um arquivo [application.properties] pode conter quantas se desejar. Aqui usamos os arquivos JSON e [TaxData.json], localizados na pasta do projeto, que é a pasta de execução do serviço com [mvn spring-boot:run].

As camadas [dao] e [business] são integradas ao contêiner do Spring por meio de uma classe de configuração:

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;

// a integração das camadas [dao] e [business] da versão 5 no contêiner do Spring
@Configuration
public class TaxConfig {

    // a camada [dao]: sua implementação e seu arquivo vêm da configuração
    @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");
        };
    }

    // a camada [business]: o Spring passa a camada [dao] a ela
    @Bean
    public ITaxBusiness business(ITaxDao dao) {
        return new TaxBusiness(dao);
    }
}

Comentários:

  • linha 15: a anotação [@Configuration] (Capítulo 6): a classe define beans. O Spring a encontra porque ela está no mesmo pacote que a classe principal ([@ComponentScan]);
  • Linhas 19–29: o método anotado com [@Bean] cria a camada [dao]. Seus parâmetros são fornecidos pelo Spring: a anotação [@Value] injeta nele o valor de uma propriedade de configuração. Em [${dao.implementation:HardwiredTax}], o texto que segue o caractere [:] é o valor padrão, usado se a propriedade estiver ausente. Esse método e o seguinte são iguais aos da classe [TaxConfig] da versão 5 (Capítulo 6), sem a anotação [@PropertySource]: o Spring Boot lê o arquivo [application.properties] por conta própria;
  • linhas 32–35: a camada [business]. O parâmetro [dao] do método recebe o bean do tipo [ITaxDao]: o Spring cria, portanto, a camada [dao] antes da camada [business].

Essas linhas substituem a integração das camadas que o programa principal realizava na versão 5: o contêiner Spring é o mesmo, mas agora é o Spring Boot que o cria e localiza a classe de configuração por conta própria. Os beans assim definidos são singletons, criados quando a aplicação é iniciada, antes do processamento de qualquer requisição: se o arquivo de dados estiver ausente ou incorreto, o serviço não inicia, em vez de responder a todas as requisições com um erro 500. Verificaremos isso mais adiante.

O serviço web é o controller [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;

// o serviço web de cálculo do imposto (versão 9)
@RestController
public class TaxController {

    // o log da classe
    private static final Logger log = LoggerFactory.getLogger(TaxController.class);

    // a camada [business], injetada pelo 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 com o corpo JSON {"married":true,"children":2,"salary":60000}
    @PostMapping("/tax")
    public TaxResponse calculatePost(@RequestBody TaxRequest request) {
        return calculate(request.married(), request.children(), request.salary());
    }

    // o processamento comum aos dois métodos HTTP: o imposto, ou uma exceção se a requisição estiver incorreta
    private TaxResponse calculate(Boolean married, Integer children, Integer salary) {
        // parâmetros corretos: o cálculo é solicitado à camada [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 incorretos: a lista de erros
        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);
    }

    // um inteiro, null se estiver ausente ou incorreto
    private static Integer readInteger(String text) {
        try {
            return text == null ? null : Integer.valueOf(text);
        } catch (NumberFormatException e) {
            return null;
        }
    }

    // uma requisição incorreta dá uma resposta 400 no 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;
    }

    // a requisição de cálculo (corpo da requisição POST): as propriedades ausentes do JSON são null
    public record TaxRequest(Boolean married, Integer children, Integer salary) {
    }

    // a resposta: o valor do imposto
    public record TaxResponse(int tax) {
    }
}

Comentários:

  • Linha 24: o log da classe. O Spring Boot usa a API de logging (Simple Logging Facade for Java), que aqui é implementado com o Logback. [LoggerFactory.getLogger] gera uma entrada de log cuja categoria é o nome completo da classe;
  • Linhas 27–31: o controller recebe a camada [business] por seu construtor. O Spring, que cria o controller, passa a ele o bean do tipo [ITaxBusiness] definido por [TaxConfig]: é a injeção por construtor descrita no Capítulo 6. Um campo declarado [final] garante que a camada não mudará;
  • linhas 34–43: a requisição GET. Os três parâmetros da query string são recebidos como strings e convertidos: [y]/[n] em [married] (linhas 37–41, uma expressão [switch] cujo tipo é [Boolean]), inteiros para [children] e [salary] ([readInteger], linhas 76–82), [null] em caso de erro;
  • linhas 46–49: a consulta POST: o corpo JSON é desserializado em um objeto [TaxRequest] (linha 94), cujos componentes de tipo objeto ([Boolean], [Integer]) são usados para detectar valores ausentes. A mesma URL [/tax] é associada a dois métodos, conforme o método HTTP da consulta;
  • linhas 52–73: o processamento comum às duas requisições. Ele retorna uma resposta em caso de sucesso e lança uma exceção em caso de erro. O tipo de seu resultado, assim como o dos métodos das linhas 35 e 47, é portanto simplesmente [TaxResponse]: a leitura de suas assinaturas mostra o que o serviço retorna quando tudo corre bem;
  • linha 54: os três parâmetros estão corretos? As comparações [children >= 0] e [salary >= 0] fazem o unboxing dos objetos [Integer]: elas só são avaliadas se estes não forem [null], graças à avaliação preguiçosa do operador [&&];
  • linha 55: o cálculo é delegado à camada [business] da versão 5;
  • linha 56: cada cálculo é registrado no log no nível [INFO]. O texto da mensagem é um template: cada ocorrência de [{}] é substituída pelo argumento correspondente, em ordem. Ao contrário da concatenação, a mensagem só é construída se precisar ser exibida (conforme o nível de log), e as ferramentas de log podem registrar cada valor separadamente;
  • linhas 60–72: em caso de erro, a lista de erros é construída, um aviso ([warn]) é registrado no log e uma exceção [BadRequestException] que carrega essa lista é lançada;
  • linhas 85–91: um método anotado com [@ExceptionHandler] atua como um tratador de exceções: o Spring o chama quando um método do controller lança uma exceção do tipo especificado por seu parâmetro, neste caso [BadRequestException]. O que ele retorna se torna a resposta HTTP: um [ProblemDetail], cujo código de status (400) se torna o código de status da resposta;
  • linhas 94–99: os DTOs de resposta do serviço.

A exceção [BadRequestException] é a seguinte:

package tax.ws;

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

// a exceção lançada pelo controller quando os parâmetros do cálculo estão incorretos
public class BadRequestException extends RuntimeException {

    @Serial
    private static final long serialVersionUID = 1L;

    // as mensagens de erro, parâmetro por parâmetro
    // (transient: um Map não é necessariamente serializável)
    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;
    }
}
  • linha 8: uma exceção não verificada (unchecked), que não precisa ser declarada pelos métodos que a lançam;
  • linhas 10–11: uma exceção é serializável (no sentido da serialização binária do Java): o compilador exige, com a opção [-Xlint:all], que ela declare um número de versão;
  • linha 15: a lista de erros. A palavra-chave [transient] exclui esse campo da serialização binária, já que o tipo [Map] não é necessariamente serializável; sem ela, o compilador emitiria um aviso. Isso não tem consequência aqui: nossas exceções nunca são serializadas.

A classe principal [WsTaxApplication] é idêntica à dos outros dois serviços. A pasta [src/main/resources/static] contém o cliente web, que é abordado na seção seguinte.

O serviço web é sem estado (stateless): os métodos do controller não retêm nenhum estado de uma requisição para outra. O controller e as camadas [business] e [dao] são singletons, criados de uma vez por todas, que existem enquanto a aplicação estiver em execução; eles são compartilhados por todas as requisições, que podem ser processadas simultaneamente por threads diferentes do servidor Tomcat (Capítulo 8). Isso não é um problema aqui porque esses objetos nunca são modificados depois de criados: as faixas de imposto são lidas uma única vez, e o controller tem apenas um campo [final]. Um controller nunca deve armazenar em seus campos dados específicos de uma requisição. O singleton é o escopo padrão dos beans do Spring, mas existem outros: [prototype] (um objeto a cada solicitação ao contêiner), [request] (um objeto por requisição HTTP), [session] (um objeto por sessão HTTP). Por fim, observe que a propriedade [spring.threads.virtual.enabled=true] faz cada requisição ser processada por uma thread virtual (Java 21, Capítulo 8) em vez de por uma thread do pool do Tomcat: o serviço pode então atender a um número muito grande de requisições simultâneas que ficam aguardando operações de E/S.

13.4.3. Execução do serviço

Comecemos por um erro de configuração. Os argumentos de linha de comando na forma [--property=value] fazem parte da configuração da aplicação e substituem os valores de [application.properties]. Com [mvn spring-boot:run], eles são passados pela propriedade [spring-boot.run.arguments]. Vamos especificar um arquivo de dados inexistente (o curso abreviou as linhas deste log, que são muito longas, para [...]):

> 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.
  • linha 4: o servidor Tomcat foi criado, mas ainda não abriu sua porta;
  • linha 6: a criação do bean falhou. Para criar o controller, o Spring precisou criar a camada [business], e portanto a camada [dao], cujo construtor instanciou uma [TaxException] (Capítulo 6). As mensagens de nossas camadas, como as do Spring, estão em inglês;
  • linha 7: o servidor Tomcat é parado; o serviço não aceitou nenhuma requisição;
  • linhas 9–21: o relatório de falha na inicialização. Sua descrição (linha 17) e a ação recomendada (linha 21) são geradas por uma classe que escrevemos para essa finalidade.

Na verdade, quando a inicialização falha, o Spring Boot normalmente exibe a exceção e toda a pilha de chamadas: dezenas de linhas, nas quais a mensagem relevante é difícil de encontrar. O Spring Boot também pode passar a exceção a analisadores de falha (failure analyzers), que a traduzem em um relatório legível. Ele fornece analisadores para os erros mais comuns (porta já em uso, bean não encontrado etc.), e podemos acrescentar os nossos:

package tax.ws;

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

// o Spring Boot chama este analisador se a inicialização falhar por causa de uma TaxException
// (arquivo de dados ausente ou incorreto, implementação desconhecida)
public class TaxFailureAnalyzer extends AbstractFailureAnalyzer<TaxException> {

    @Override
    protected FailureAnalysis analyze(Throwable rootFailure, TaxException cause) {
        // a descrição do erro: a mensagem da exceção e a de sua causa
        String description = "The service cannot start: " + cause.getMessage()
                + (cause.getCause() == null ? "" : " (" + cause.getCause().getMessage() + ")");
        // o que o usuário deve fazer
        String action = "Check the dao.implementation and dao.file properties of the configuration.";
        return new FailureAnalysis(description, action, cause);
    }
}
  • Linha 9: a classe [AbstractFailureAnalyzer<T>] do Spring Boot procura uma exceção do tipo [T], neste caso [TaxException], na cadeia de causas que levou à exceção que provocou a falha da inicialização. Se encontrar uma, ela chama o método [analyze];
  • linha 12: o parâmetro [rootFailure] é a exceção inicial, e [cause] é a [TaxException] encontrada na cadeia;
  • linhas 14–18: o relatório é um objeto [FailureAnalysis] composto por uma descrição, uma ação recomendada e a exceção analisada.

Esse analisador não é um bean (ele deve funcionar mesmo que o contêiner não tenha podido ser criado): o Spring Boot o procura nos arquivos [META-INF/spring.factories] das bibliotecas e da aplicação. O nosso está em [src/main/resources/META-INF]:

# o analisador das falhas de inicialização causadas por uma TaxException
org.springframework.boot.diagnostics.FailureAnalyzer=tax.ws.TaxFailureAnalyzer
  • linha 2: a chave é o nome da interface [FailureAnalyzer], e o valor é o nome de nossa classe (várias classes seriam separadas por vírgulas).

Agora vamos iniciar o serviço normalmente, com [mvn spring-boot:run], e depois consultá-lo com [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}

Esse é o resultado de teste esperado: um contribuinte casado, com dois filhos e um salário anual de 60.000 euros, paga 4.282 euros de imposto (observe que a tabela de imposto usada, a de 2004, é mantida apenas para este exercício fiscal). Com parâmetros incorretos:

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"]}}

Depois, em POST, com um 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}

O log do serviço será mostrado no final do capítulo: ele contém o registro de todos os cálculos solicitados.

13.4.4. O cliente de console: uma nova camada [business]

O cliente da versão 9 usa a camada [ui] da versão 5 sem modificá-la: a classe [tax.ui.Dialog], cujo método estático [run(ITaxBusiness business)] interage com o usuário e solicita cálculos à camada [business] que lhe é passada. Basta passar a ele uma camada chamada [business] que consulte o serviço web. As dependências do projeto [ClientWsTax] são as seguintes (o restante do arquivo [pom.xml] é igual ao de [ClientWsHello], exceto pelo nome do projeto e pela classe principal: [examples.tax:client-ws-tax:9.0], [tax.client.Main]):

    <dependencies>
        <!-- a interface da camada [business] e a camada [ui] da versão 5 -->
        <!-- (tax-ui também traz tax-dao e o contêiner do 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 os documentos JSON trocados com o serviço -->
        <dependency>
            <groupId>tools.jackson.core</groupId>
            <artifactId>jackson-databind</artifactId>
            <version>3.1.5</version>
        </dependency>
    </dependencies>
  • Linhas 4–13: módulos da versão 5: [tax-business] para a interface [ITaxBusiness], [tax-ui] para a classe [Dialog]. Um projeto pode depender de um módulo que contém um programa principal: nesse caso, ele usa as classes públicas do módulo sem executar o programa em si. O módulo [tax-dao] é uma dependência indireta (ou transitiva): o cliente usa dele apenas a classe [TaxException]. Da mesma forma, [tax-ui] fornece o contêiner do Spring ([spring-context]);
  • linhas 15–19: o Jackson, para os documentos JSON. Ele também é fornecido por [tax-dao], mas o cliente o usa diretamente: é preferível declará-lo.

A nova camada [business] é a classe [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;

// a camada [business] do lado do cliente: um proxy do serviço web de cálculo do imposto
// ela implementa a mesma interface que a camada [business] local da versão 5
public class TaxBusinessHttp implements ITaxBusiness {

    // os objetos trocados com o serviço web
    private record TaxRequest(boolean married, int children, int salary) {
    }

    private record TaxResponse(int tax) {
    }

    // o cliente HTTP, a URL do método POST /tax, o 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) {
        // a requisição POST /tax, com a requisição em JSON em seu corpo
        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 {
            // envio síncrono: o método espera a resposta
            response = client.send(request, HttpResponse.BodyHandlers.ofString());
        } catch (IOException e) {
            // o serviço está inacessível
            throw new TaxException("The web service " + taxUrl + " is unreachable", e);
        } catch (InterruptedException e) {
            // a thread foi interrompida durante a espera: isso é sinalizado novamente
            Thread.currentThread().interrupt();
            throw new TaxException("The tax calculation was interrupted", e);
        }
        // o serviço aceitou a requisição?
        if (response.statusCode() != 200) {
            throw new TaxException("The web service responded " + response.statusCode()
                    + " : " + response.body(), response.statusCode());
        }
        // a resposta JSON {"tax":4282}
        return mapper.readValue(response.body(), TaxResponse.class).tax();
    }
}

Comentários:

  • linha 14: a classe implementa a interface [ITaxBusiness] da versão 5;
  • linhas 17–21: as variáveis DTO são declaradas dentro da classe ([private]) porque ninguém mais as usa;
  • linhas 28–31: a classe recebe, por seu construtor, o cliente HTTP e a URL do serviço, a partir da qual calcula a URL do método [POST /tax] ;
  • linhas 36–40: a requisição [POST tax], com a requisição serializada em JSON em seu corpo;
  • linha 44: a requisição é enviada de forma síncrona: o método [send] aguarda a resposta, o que é coerente com o método [calculateTax] da interface, que também é síncrono (ele retorna um [int]);
  • Linhas 45–47: [send] lança uma [IOException] se o serviço estiver inacessível. Trata-se de uma exceção verificada (checked), que o método [calculateTax] da interface não declara: ela é encapsulada em uma [TaxException], a exceção não verificada da aplicação [Tax];
  • linhas 48–52: o mesmo vale para [InterruptedException], lançada se a thread for interrompida durante a espera. Capturar a exceção limpa o indicador de interrupção da thread: a boa prática (Capítulo 8) é restabelecê-lo com [Thread.currentThread().interrupt()] para que o código chamador saiba que a thread foi interrompida;
  • linhas 54–57: uma resposta de erro é convertida em [TaxException], cujo código é o código de status HTTP;
  • linha 59: a resposta JSON [{"tax":4282}] é desserializada, e o valor do imposto é retornado.

Com um serviço SOAP, a ferramenta [wsimport] gerava um proxy, e uma classe semelhante a esta implementava [ITaxBusiness] delegando o cálculo a ele: hoje, escrevemos nós mesmos as poucas dezenas de linhas do proxy.

Como o método [calculateTax] da interface [ITaxBusiness] é síncrono, usamos o método síncrono [send] de [HttpClient]. Essa interface também oferece um método assíncrono, [sendAsync], que retorna imediatamente um [CompletableFuture<HttpResponse<T>>] (Capítulo 9). Para aproveitar isso, seria necessário tornar a interface assíncrona: [CompletableFuture<Integer> calculateTaxAsync(boolean married, int nbChildren, int salary)], o que exigiria modificar a interface [ITaxBusiness], suas implementações e a camada [ui]. Não fizemos isso para manter intactas as camadas da versão 5. Com as threads virtuais (Java 21), o código síncrono voltou a ser a forma recomendada de escrever programas que fazem muita E/S: uma thread virtual bloqueada por [send] não bloqueia nenhuma thread do sistema.

O programa principal do cliente integra as camadas:

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) {
        // a URL do serviço web: a passada como argumento, ou a padrão
        URI serviceUrl = URI.create(args.length > 0 ? args[0] : "http://localhost:5120/");

        // o código de saída do programa
        int code = 0;
        // integração das camadas: a camada [business] agora é um cliente do serviço web
        try (GenericApplicationContext context = new GenericApplicationContext()) {
            // a URL do serviço e o cliente HTTP, que o Spring passará ao construtor 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);

            // o diálogo da versão 5, sem nenhuma modificação
            try {
                Dialog.run(business);
            } catch (RuntimeException e) {
                // o serviço está inacessível ou recusou a requisição
                Dialog.displayError(e);
                code = 1;
            }
        }
        if (code != 0) {
            System.exit(code);
        }
    }
}

Comentários:

  • linha 13: a URL do serviço, passada como argumento ou, por padrão, [http://localhost:5120/];
  • linha 18: o contêiner do Spring, como na versão 5. Ele é fechado ao final do bloco [try];
  • Linhas 20–22: três beans são registrados: o bean da URL do serviço e o bean do cliente HTTP, fornecidos por lambdas (do tipo [Supplier]), seguidos da classe [TaxBusinessHttp]. Para criar essa classe, o Spring examina seu construtor e passa a ele os beans dos tipos [HttpClient] e [URI];
  • linha 23: o contêiner cria os beans;
  • linha 24: pede-se ao contêiner um bean do tipo [ITaxBusiness]; ele retorna o objeto [TaxBusinessHttp], que implementa essa interface. O restante do programa ignora a implementação;
  • linha 28: o diálogo da versão 5, sem nenhuma modificação;
  • linhas 29–33: se o serviço não puder ser alcançado, a exceção se propaga da camada [business] pela camada [ui], que não a trata: ela é exibida por meio do método [Dialog.displayError] da versão 5;
  • linhas 35–37: em caso de erro, o programa termina com o código 1 após fechar o contêiner.

Resultados, com o serviço em execução:

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

Os valores de verificação do cálculo do imposto são exibidos: 4.282, 2.959 e 11.519 euros. A entrada incorreta da linha 8 foi detectada pela camada [ui], que não chamou a camada [business]: o serviço recebeu apenas requisições válidas. Se o serviço for parado:

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

A [TaxException] de nosso proxy encapsula a exceção [ConnectException] lançada por [send], que por sua vez encapsula as exceções da camada de rede (Capítulo 12). Nenhuma delas tem mensagem: [getMessage()] retorna [null].

13.5. Um cliente web para o serviço de cálculo do imposto

Uma aplicação web “tradicional” gera suas páginas (HTML) no servidor: a cada clique em um botão, o formulário é enviado ao servidor, que devolve ao navegador uma página nova e completa. Hoje, o navegador na maioria das vezes consulta ele próprio um serviço web, em JavaScript, e atualiza apenas a parte da página que mudou. É isso que vamos fazer. A arquitetura é a seguinte:

Image

  • 1: o navegador solicita a página [/]; o servidor [WsTax] envia a ele o arquivo estático [index.html];
  • 2: a cada clique no botão [Calculate], o código JavaScript da página envia a requisição [POST /tax] ao serviço web e exibe na página o valor do imposto recebido, sem recarregá-la.

O serviço web não foi modificado: ele apenas serve um arquivo adicional. O Spring Boot serve automaticamente como arquivos estáticos os arquivos colocados na pasta [static] dos recursos da aplicação ([src/main/resources/static]): páginas HTML, imagens, scripts, folhas de estilo etc. O arquivo [static/index.html] também é servido para a URL [/]: essa é a página de boas-vindas. Um mesmo servidor pode, assim, hospedar tanto um site quanto um serviço web. A página [index.html] é a seguinte:

<!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>
    // os elementos da 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");

    // um inteiro digitado, ou null se a entrada não for um inteiro
    function readInteger(text) {
      return /^\s*-?\d+\s*$/.test(text) ? parseInt(text, 10) : null;
    }

    // limpa o resultado e as mensagens de erro
    function clearMessages() {
      tax.textContent = "";
      childrenError.textContent = "";
      salaryError.textContent = "";
      message.textContent = "";
    }

    // botão [Calculate]: consultamos o serviço web, sem recarregar a página
    form.addEventListener("submit", async (event) => {
      event.preventDefault();
      clearMessages();
      // a requisição, no 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: um documento "Problem Details" com os erros por parâmetro
          const errors = body.errors ?? {};
          childrenError.textContent = errors.children?.join(" ") ?? "";
          salaryError.textContent = errors.salary?.join(" ") ?? "";
          message.textContent = body.title;
        }
      } catch (e) {
        // o serviço está inacessível
        message.textContent = `Error communicating with the service: ${e.message}`;
      }
    });

    // botão [Clear]: redefinição do formulário
    document.getElementById("clear").addEventListener("click", () => {
      children.value = "";
      salary.value = "";
      clearMessages();
    });
  </script>
</body>
</html>

Comentários:

  • Linhas 15–44: o formulário: dois botões de opção para o estado civil, dois campos de entrada para o número de filhos e o salário, cada um seguido de uma célula onde será exibida a mensagem de erro (se houver), um campo para o imposto, um parágrafo para uma mensagem geral e dois botões;
  • linhas 46–108: o código da página, em JavaScript, executado pelo navegador. O curso não aborda JavaScript; no entanto, esse código é próximo o bastante do Java para ser lido sem dificuldade;
  • linha 57: uma entrada que não seja um inteiro resulta em [null]; cabe ao serviço informar o erro;
  • linha 70: o tratador de clique do botão [Calculate] (envio do formulário). Essa é uma função assíncrona ([async]): como [CompletableFuture] (Capítulo 9), ela não bloqueia o navegador enquanto aguarda uma resposta;
  • linha 71: impedimos o navegador de enviar o formulário por conta própria, o que causaria o carregamento de uma nova página;
  • linhas 74–77: a requisição, um objeto JavaScript que tem o formato esperado por [POST /tax];
  • linhas 80–83: a função [fetch] do navegador envia a requisição HTTP: o método [POST], o cabeçalho [Content-Type] e o corpo, que é a requisição serializada em JSON por [JSON.stringify]. A URL [tax] é relativa à página: a requisição é enviada ao servidor que forneceu a página. [await] aguarda a resposta sem bloquear o navegador;
  • linha 85: o corpo da resposta é desserializado em um objeto;
  • linhas 86–88: em caso de sucesso (código 2xx), o valor do imposto é exibido;
  • linhas 91–94: em caso de erro, o título do documento “Problem Details” é exibido, junto com as mensagens de erro sobre o número de filhos e o salário, cada uma ao lado de seu campo de entrada correspondente. O operador [?.] retorna [undefined] se o objeto à sua esquerda não existir, em vez de causar um erro; o operador [??] substitui um valor ausente pelo valor que o segue. O Java não tem equivalente direto para esses operadores: em Java, usam-se testes de [null] ou um [Optional];
  • linhas 103–106: o botão [Clear] redefine o formulário localmente, sem consultar o serviço.

Agora que o serviço está em execução, vamos solicitar a URL [http://localhost:5120/] usando um navegador:

Image

Depois de digitar um cálculo e clicar no botão [Calculate]:

Image

Se a entrada estiver incorreta, as mensagens de erro são as do serviço web:

Image

Essas capturas de tela foram feitas com o navegador Chromium, controlado por um programa por meio da biblioteca Playwright: é assim que se automatiza o teste de uma interface web.

Aqui, a página e o serviço compartilham a mesma origem (mesmo protocolo, mesma máquina, mesma porta: [http://localhost:5120]). Se a página fosse servida por outro site, por exemplo [http://localhost:5000], o navegador aplicaria a política de mesma origem: ele só permitiria que o código JavaScript lesse a resposta do serviço se este a autorizasse por meio do cabeçalho [Access-Control-Allow-Origin]. Para uma requisição como a nossa (POST com um corpo JSON), o navegador chegaria a pedir essa autorização antes de enviar a requisição, por meio de uma requisição preliminar com o método OPTIONS (preflight). Esse é o mecanismo CORS (Cross-Origin Resource Sharing), que protege o usuário de páginas maliciosas que poderiam tentar usar, sem que ele saiba, serviços nos quais ele está autenticado. Para permitir outras origens, um controller do Spring pode ser anotado com [@CrossOrigin(origins = "http://localhost:5000")]; também é possível uma configuração global (o método [addCorsMappings] da interface [WebMvcConfigurer]). Os clientes que não são navegadores ([curl], nossos clientes de console) não são afetados pelo CORS.

Para interfaces web mais ricas geradas pelo servidor, o Spring MVC também oferece controllers que retornam páginas HTML construídas a partir de templates (como o Thymeleaf), o que está fora do escopo deste curso.

13.6. Um serviço web é independente da linguagem de programação de seu cliente

Com um serviço SOAP, o cliente precisava ter uma ferramenta capaz de ler o WSDL e gerar o proxy, e as diferenças na interpretação dos padrões entre as plataformas frequentemente causavam problemas de interoperabilidade. Com um serviço REST/JSON, qualquer linguagem que tenha um cliente HTTP e uma biblioteca JSON, ou seja, todas as linguagens atuais, pode consultar o serviço sem nenhuma ferramenta especial. Já vimos isso com o [curl], que não é escrito em Java, e com o JavaScript do navegador. Eis um cliente escrito para o Node.js, o ambiente de execução do JavaScript fora do navegador:

// um cliente JavaScript (Node.js) do serviço web de cálculo do imposto
// chamada: node client-tax.mjs [service url]
const serviceUrl = process.argv[2] ?? "http://localhost:5120/";

// as requisições a enviar: a última é incorreta
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 com a requisição em 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)}`);
  }
}
  • linha 3: a URL do serviço, passada como argumento ou definida por padrão;
  • linhas 6–9: três requisições de cálculo, a última das quais é incorreta;
  • linhas 14–17: a mesma função [fetch] do navegador;
  • linhas 20–23: exibição do valor do imposto ou dos erros.

Com o serviço em execução:

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"]}

Em Python, usaríamos de modo semelhante o módulo [requests] ou [httpx] ; em C#, a classe [HttpClient]. Por fim, eis o log do serviço [WsTax] durante todos os testes deste capítulo ([curl], cliente de console, navegador, cliente Node.js), até seu encerramento com Ctrl-C (o curso abreviou os caminhos da linha 2 para [...]):

> 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
  • linha 8: o Spring Boot encontrou a página inicial [static/index.html];
  • linhas 14–24: mensagens de nosso controller: as linhas [INFO] registram os cálculos, enquanto as linhas [WARN] registram as requisições inválidas, junto com os nomes dos parâmetros envolvidos. As linhas 14–16 vêm do [curl], as linhas 17–19 do cliente de console, as linhas 20–21 do navegador e as linhas 22–24 do cliente Node.js;
  • os nomes das threads (de [http-nio-5120-exec-1] a [exec-10]) mostram que as requisições são distribuídas entre as threads do pool do Tomcat; requisições sucessivas de um mesmo cliente não são necessariamente tratadas pela mesma thread.

13.7. Informações adicionais

13.7.1. Tipos de resposta e tratamento de erros

O serviço [WsOperations] retorna objetos [ResponseEntity<?>]: somente pelas assinaturas de seus métodos não fica claro quais respostas eles podem produzir, e o compilador não faz nenhuma verificação. O serviço [WsTax] retorna o tipo específico de sua resposta em caso de sucesso, [TaxResponse], e sinaliza os erros por meio de exceções, que são convertidas em respostas por um tratador [@ExceptionHandler]. Essa é a abordagem mais comum com o Spring: o código dos métodos trata apenas o caso normal, e as ferramentas (em particular o gerador de documentos OpenAPI) conhecem o esquema JSON da resposta sem que isso precise ser dito explicitamente. Um teste unitário também pode chamar diretamente um método do controller e examinar seu resultado, sem passar pelo HTTP. [ResponseEntity<T>], com um tipo específico, continua útil quando é preciso escolher o código de status ou acrescentar cabeçalhos, por exemplo, para uma resposta 201 (Created) acompanhada de seu cabeçalho [Location]: [ResponseEntity.created(uri).body(client)].

Um tratador [@ExceptionHandler] colocado em um controller trata apenas as exceções desse controller. Para tratar as exceções de todos os controllers de uma aplicação, coloque os tratadores em uma classe anotada com [@RestControllerAdvice]. O Spring também fornece a classe [ErrorResponseException], uma exceção que carrega diretamente um [ProblemDetail] e produz a resposta correspondente sem um tratador, e a classe [ResponseEntityExceptionHandler], que pode ser estendida para personalizar as respostas aos erros detectados pelo próprio Spring MVC (documento JSON ilegível, tipo de documento inválido etc.).

13.7.2. Um prefixo comum para as rotas

Quando várias rotas compartilham um prefixo, ele é especificado de uma vez por todas por meio da anotação [@RequestMapping] colocada na classe do controller. Por exemplo, com [@RequestMapping("/api/operations")] na classe [OperationsController], as rotas passam a ser [GET /api/operations/add?a=1&b=2] e [POST /api/operations/calculation], sem nenhuma outra alteração. Essa também é uma maneira simples de gerenciar as versões de um serviço ([/api/v1/...], [/api/v2/...]).

13.7.3. Interceptors e validação

Nossos serviços validam seus próprios parâmetros. O Spring oferece dois mecanismos para tirar esse código dos controllers:

  • interceptors: uma classe que implementa a interface [HandlerInterceptor], registrada por meio do método [addInterceptors] de [WebMvcConfigurer], é executada antes e depois dos métodos dos controllers; ela pode examinar a requisição e responder por conta própria, sem chamar o controller. Os interceptors são usados para log, medição de tempos de resposta, autenticação e assim por diante. Os filtros de servlet ([jakarta.servlet.Filter]) têm a mesma finalidade em um nível mais baixo;
  • validação: com o starter [spring-boot-starter-validation] (que fornece o Hibernate Validator, a implementação de referência da API Jakarta Validation), os componentes de um DTO podem ser anotados com restrições: [record TaxRequest(@NotNull Boolean married, @NotNull @Min(0) Integer children, @NotNull @Min(0) Integer salary)]. Um parâmetro [@Valid @RequestBody TaxRequest request] é então validado antes da chamada do método, e uma requisição inválida é rejeitada com uma resposta 400 “Problem Details”, como as que construímos.

13.7.4. Hospedagem

Nossos serviços são executados por [mvn spring-boot:run], o que é adequado para o desenvolvimento. Em produção:

  • a aplicação é primeiro empacotada por [mvn package]: o plugin do Spring Boot gera um único arquivo “executável” [.jar], que contém a aplicação, suas dependências e o servidor Tomcat. Basta copiá-lo para o servidor e executá-lo com [java -jar ws-tax-9.0.jar]; a configuração pode ser modificada por argumentos de linha de comando ([--server.port=80]), por variáveis de ambiente ou por um arquivo [application.properties] colocado ao lado do arquivo [.jar];
  • o Tomcat pode ser exposto diretamente à Internet, mas costuma ser colocado atrás de um proxy reverso (nginx ou Apache no Linux, IIS no Windows) que recebe as requisições HTTPS, gerencia os certificados e distribui a carga entre várias instâncias da aplicação;
  • a aplicação também pode ser implantada como uma imagem de contêiner (Docker), que o plugin do Spring Boot pode gerar sem um arquivo [Dockerfile]: [mvn spring-boot:build-image]. A imagem executa então em qualquer plataforma de contêineres, seja em seu próprio servidor, seja em um provedor de hospedagem;
  • o HTTPS é essencial: as propriedades [server.ssl.*] do Spring Boot configuram o certificado do servidor Tomcat quando o servidor é exposto diretamente.

13.8. Conclusão

Este capítulo apresentou os serviços web REST/JSON, sucessores dos serviços web SOAP, escritos com o Spring Boot e o Spring MVC. Vimos:

  • que um serviço web associa URLs e métodos HTTP a métodos Java por meio das anotações [@RestController], [@GetMapping] e [@PostMapping], e que os parâmetros desses métodos vêm da rota ([@PathVariable]), da query string ([@RequestParam]), do corpo (JSON, [@RequestBody]) ou do contêiner do Spring (injeção por construtor);
  • que os resultados são enviados em JSON pelo Jackson, e que os erros são informados por um código de status e um documento “Problem Details” ([ProblemDetail], [ResponseEntity], [@ExceptionHandler]);
  • que um cliente Java usa [java.net.http.HttpClient] e o Jackson, e que um cliente escrito em qualquer outra linguagem pode fazer o mesmo;
  • que a arquitetura em camadas cumpriu o que prometia: a versão 9 do cálculo do imposto reutiliza, sem modificação, as camadas do lado do servidor [dao] e [business] da versão 5, bem como sua camada do lado do cliente [ui]; bastou escrever o serviço web (cerca de 100 linhas) e uma nova implementação da interface [ITaxBusiness] (cerca de 60 linhas).