13. Serviços web
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, 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 especificar o serviço Si;
- a lista dos parâmetros a fornecer e seus tipos;
- o tipo de resultado devolvido pelo serviço. Uma vez conhecidos esses elementos, o diálogo cliente/servidor segue o mesmo formato, qualquer que seja o serviço web consultado. Isso padroniza a comunicação do cliente;
- Para se proteger de ataques vindos da Internet, muitas organizações abrem apenas algumas portas de seus servidores para o exterior: principalmente as portas 80 (HTTP) e 443 (HTTPS) para o serviço web. Todas as outras portas são bloqueadas. Consequentemente, aplicações cliente/servidor como as descritas no capítulo anterior ficam geralmente restritas à rede privada da organização (intranet). 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 tornam-se 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 esconde toda a comunicação de rede. Isso nos 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ço web é a seguinte:

Trata-se de uma extensão da arquitetura em camadas do Capítulo 6, à qual se acrescentam camadas especializadas na 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 de imposto (versão 8) do capítulo anterior.
13.1.1. Ontem: SOAP e WSDL
Nos anos 2000, os serviços web seguiam na maioria das vezes o padrão SOAP (Simple Object Access Protocol). O cliente enviava uma requisição HTTP 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. Com base nesse documento, ferramentas geravam automaticamente o proxy do serviço.
Na JVM, esses serviços eram definidos com a API JAX-WS: uma classe anotada com [@WebService], cujos métodos públicos (que podiam ser anotados com [@WebMethod]) tornavam-se os métodos do serviço; a ferramenta [wsimport] gerava o proxy 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 agora existe fora do JDK, com o nome Jakarta XML Web Services. O Kotlin, lançado (na versão 1.0) em 2016, não existia de fato nessa época: o JAX-WS pode ser usado a partir do Kotlin como qualquer biblioteca Java, mas os novos serviços raramente o utilizam hoje. Entre os motivos dessa mudança estão a lentidão e 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 na 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 determinado cliente.
Os métodos HTTP mais usados são os seguintes:
Método | Uso | Exemplo |
GET | Ler um recurso; os 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, ganham 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] informa 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), em 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, vale mencionar 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 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 na JVM com a biblioteca [grpc-java], complementada para Kotlin por [grpc-kotlin] (as funções [suspend] e [Flow], Capítulo 9), 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 inclui também um módulo web, o Spring MVC, que associa uma URL e um método HTTP a uma função 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 adoção do Spring:
- ele configura automaticamente a aplicação com base nas bibliotecas disponíveis: se o Spring MVC e o Jackson estão 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) é uma simples biblioteca, iniciada pelo programa principal. Portanto, não é preciso instalar um servidor web ou de aplicações separado (Tomcat, GlassFish, WildFly…), no qual a aplicação costumava ser implantada como um arquivo [.war];
- ele fornece os starters — dependências que reúnem tudo o que é necessário para um caso de 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 uma lista de materiais (BOM), que especifica as versões de todas essas bibliotecas — compatíveis entre si — e um plugin do Gradle, [org.springframework.boot], que inicia a aplicação ([gradlew bootRun]) e a empacota em um único arquivo executável ([.jar]) ([gradlew bootJar]).
O Spring é escrito em Java, mas trata o Kotlin como linguagem de primeira classe desde o Spring Framework 5 (2017): sua documentação traz exemplos nas duas linguagens, ele suporta os tipos anuláveis do Kotlin, sabe chamar construtores primários e seus valores padrão, e oferece funções de extensão específicas para Kotlin ([runApplication], [getBean<T>()], [registerBean<T>()] do Capítulo 6…). 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 com Kotlin. Merece destaque o Ktor, o framework web da JetBrains escrito em Kotlin para Kotlin: suas rotas são descritas por uma linguagem dedicada (DSL) em vez de anotações, e seus handlers são funções [suspend] (Capítulo 9). 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:

Os projetos deste capítulo formam um build Gradle multiprojeto (Capítulo 6), a pasta [13-web-services]:
O arquivo [settings.gradle.kts] lista os subprojetos:
- linhas 3–6: o plugin que permite ao Gradle baixar o próprio JDK 25 caso não o encontre na máquina (Capítulo 2);
- linha 11: os seis subprojetos, identificados pelos nomes de suas pastas;
- linha 14: o build do Capítulo 6 é incluído neste (composite build, já usado nos Capítulos 10 e 11): os projetos [WsTax] e [ClientWsTax] podem depender dos módulos da versão 5 da aplicação de imposto [TaxV5] por suas coordenadas ([examples.tax:tax-business:5.0]), e o Gradle compilará esses módulos a partir do código-fonte, se necessário.
O projeto raiz declara os plugins usados pelos subprojetos, com suas versões, sem aplicá-los:
- linha 4: o plugin Kotlin, que já conhecemos;
- linha 5: o plugin [all-open] para o Spring, usado no Capítulo 6. No Kotlin, as classes e suas funções são final por padrão; porém, o Spring precisa derivar subclasses (proxies) de algumas de suas classes. Esse plugin torna abertas as classes anotadas pelo Spring ([@Configuration], [@Component], [@RestController], [@SpringBootApplication]…) e seus métodos.
- Linha 6: o plugin Spring Boot.
Os projetos já estão configurados no código do curso: basta abrir a pasta [13-web-services] no IntelliJ IDEA, que a reconhece como um build Gradle, ou digitar nessa pasta o comando Gradle indicado. Os serviços são iniciados com [gradlew :WsHello:bootRun] (o caminho [:WsHello] designa o subprojeto), e os clientes de console com [gradlew -q :ClientWsHello:run]. O comando [gradlew build] compila todos os projetos de uma só vez.
Para criar você mesmo um projeto Spring Boot, o mais fácil é usar o site Spring Initializr: nele, você seleciona “Gradle - Kotlin” (um projeto Gradle cujos arquivos de build são escritos em Kotlin), a linguagem Kotlin, a versão do Spring Boot, o nome do projeto e suas dependências (neste caso, “Spring Web”), e depois baixa um arquivo ZIP contendo um projeto pronto para uso: os arquivos [build.gradle.kts] e [settings.gradle.kts], o Gradle wrapper, a classe principal e o arquivo [application.properties]. O IntelliJ IDEA (edição Ultimate) oferece o mesmo assistente. Para um projeto Kotlin, o Spring Initializr adiciona automaticamente as dependências [kotlin-reflect] e [jackson-module-kotlin], sobre as quais falaremos.
13.2.1. O lado do servidor

O arquivo [build.gradle.kts] do projeto [WsHello] é o seguinte:
Comentários:
- Linhas 3–7: os três plugins, sem versão especificada — a versão é determinada pelo projeto raiz. O plugin Spring Boot adiciona ao projeto a tarefa [bootRun], que compila e executa a aplicação, e a tarefa [bootJar], que cria um arquivo chamado [build/libs/WsHello-1.0.jar] contendo a aplicação e todas as suas dependências, que é então iniciado por [java -jar build/libs/WsHello-1.0.jar]. Não é necessário aplicar o plugin [application]: a classe principal é encontrada pelo plugin Spring Boot, que procura a função [main];
- Linha 19: a versão 4.1.1 do Spring Boot (a versão do plugin). A função [platform] importa para o projeto as versões de várias centenas de bibliotecas, selecionadas e testadas em conjunto pela equipe do Spring Boot. É por isso que as dependências das linhas 21–23 não têm versão. É o equivalente ao projeto pai [spring-boot-starter-parent] em um projeto Maven;
- linha 21: o starter web. Ele fornece o Spring MVC (Spring Framework 7.0), o servidor Tomcat 11 embutido, o Jackson 3 e o log;
- linha 23: a biblioteca de reflexão do Kotlin. A reflexão do Java ([java.lang.reflect]) enxerga apenas parte do que o código Kotlin expressa: ela não sabe se um parâmetro é anulável ([String?]), se tem um valor padrão, nem qual é o construtor primário de uma classe. O Spring lê essas informações por meio de [kotlin-reflect] (que decodifica os metadados que o compilador Kotlin armazena em cada arquivo [.class]): veremos que ele a usa para os parâmetros opcionais. A versão utilizada é a do plugin Kotlin;
- linha 31: a opção [-java-parameters] do compilador, que armazena os nomes dos parâmetros das funções nos arquivos [.class]. O Spring precisa disso para associar um parâmetro de função ([name]) ao parâmetro de mesmo nome em uma URL, e o Jackson precisa disso para associar os parâmetros do construtor de uma data class às propriedades de um documento JSON (Capítulo 5). O plugin Spring Boot já ativa essa opção quando detecta o plugin Kotlin; nós a incluímos aqui para torná-la explícita;
- linhas 35–38: os programas iniciados pelo Gradle escrevem sua saída em UTF-8 para que os caracteres acentuados sejam exibidos corretamente no Windows (Capítulo 2).
A classe principal é a seguinte:
- 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 — controllers, configurações etc. — no pacote dessa classe e em seus subpacotes);
- Linha 8: a classe não tem corpo; serve apenas para carregar a anotação. Como é (indiretamente) anotada com [@Configuration], o plugin [plugin.spring] a torna não final. Aqui isso não é essencial: verificamos que a aplicação também inicia quando a classe permanece final, já que o Spring não precisa derivar uma classe de configuração que não define nenhum bean. No entanto, uma classe de configuração que define beans por meio de funções [@Bean] — como o serviço de cálculo de imposto — provocaria o erro [@Configuration class '...' may not be final] encontrado no Capítulo 6: o plugin cuida disso para você;
- linhas 10–12: o programa principal é uma função de nível superior, compilada na classe [WsHelloApplicationKt]. A função [runApplication<WsHelloApplication>(*args)], uma função de extensão do Spring Boot escrita em Kotlin, substitui a chamada Java [SpringApplication.run(WsHelloApplication.class, args)]: o tipo da classe de configuração é passado como argumento de tipo ([reified], Capítulo 4), e o operador [*] (spread) passa os elementos do array [args] para o parâmetro [vararg] da função (Capítulo 3). [runApplication] 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 então devolve o controle. No entanto, o programa não para: 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]:
- linha 2: o nome da aplicação;
- linha 4: o servidor escuta na porta 5100 (8080 por padrão). Esse valor também poderia ser passado como argumento: [gradlew :WsHello:bootRun --args=--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. Vamos reduzi-lo à hora, ao nível da mensagem, ao nome da thread, ao nome curto da classe emissora ([%logger{0}]) e à mensagem.
O serviço web em si é a classe [HelloController]. Ela oferece uma função que devolve a string [Hello Mrs xx], em que xx é o nome recebido:
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 encaminha as requisições HTTP cuja URL corresponde a uma de suas funções. O resultado de cada método é enviado tal como está ao cliente, no corpo da resposta;
- linhas 12–13: a anotação [@GetMapping("/")] associa o método HTTP GET e a URL [/] (a raiz do site) à função [home], que devolve um texto explicando como usar o serviço. A função tem um corpo de expressão ([= ...]): seu tipo, [String], é inferido. As chaves em [{name}] não têm nada de extraordinário em uma string Kotlin: apenas o caractere [$] introduz um template;
- Linhas 18–19: o modelo da URL (chamado de path) [/hello/{name}] contém uma variável [{name}]: ela corresponde a qualquer segmento da URL colocado depois de [/hello/]. Assim, a URL [/hello/Carla%20Bruni] atribui o valor [Carla Bruni] a [{name}] (o código [%20] representa um espaço em uma URL). A anotação [@PathVariable] instrui o Spring a passar esse valor ao parâmetro de mesmo nome da função: é o binding de dados. A função devolve uma string, construída por meio de um template: essa string é enviada tal como está ao cliente, como um documento de texto (tipo [text/plain]);
- linhas 22–23: o mesmo procedimento, mas a função devolve um objeto do tipo [Greeting]. O Spring o serializa em JSON usando o Jackson (Capítulo 5) e o envia ao cliente como um documento do tipo [application/json]. Esse é o formato padrão de resposta de um serviço web REST;
- linha 26: o tipo do resultado, uma data class (Capítulo 4) aninhada no controller (o equivalente a um record do Java). O Jackson a serializa por meio de seus acessores [getName()] e [getMessage()], gerados pelo compilador: cada propriedade se torna uma propriedade JSON de mesmo nome.
O serviço é iniciado pelo comando [gradlew :WsHello:bootRun], digitado na pasta [13-web-services] (ou [..\gradlew bootRun] digitado na pasta [WsHello]: o wrapper está na raiz do projeto). O diretório de execução da aplicação é o do subprojeto. Ela exibe seu log (o curso abreviou os caminhos da linha 2 para [...] e omitiu as mensagens do Gradle):
- 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. Observe o nome [WsHelloApplicationKt]: o Spring Boot dá à aplicação o nome da classe que contém a função [main] — neste caso, a classe gerada pelo compilador Kotlin para o arquivo [WsHelloApplication.kt], e não a classe [WsHelloApplication];
- 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 Spring está pronto: criou seus beans, inclusive nosso controller;
- linhas 8–9: o Tomcat agora aceita conexões; a aplicação está pronta. A inicialização levou cerca de quinze segundos em nossa máquina de teste, o que é bastante lento (e ela estava ocupada com outras tarefas); 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 neste 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 é processada por uma das threads do servidor Tomcat;
- linhas 13–14: essas mensagens apareceram quando o servidor foi encerrado com Ctrl-C, depois dos testes descritos nos parágrafos seguintes: o encerramento é “elegante” (graceful); o Tomcat conclui as requisições pendentes antes de parar.
Cada mensagem de log inclui sua hora, seu 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] exibe também as mensagens de nível inferior de um determinado pacote.
13.2.2. Consultando o serviço com curl
Com o serviço 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:
- Linha 2: a requisição foi bem-sucedida. O Tomcat não envia o texto que costuma seguir o código de status ([OK]): ele é opcional desde o HTTP/1.1 (e não existe mais no HTTP/2); só o código importa;
- Linha 3: o documento é 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 da função [hello].
Agora vamos solicitar a versão JSON:
- 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 têm os mesmos nomes das propriedades da data class, [name] e [message], e são listadas na ordem de seu construtor primário. Isso não era óbvio: por padrão, o Jackson 3 ordena as propriedades de uma classe comum em ordem alfabética (veremos isso com a classe [ProblemDetail]), mas lista primeiro, na ordem em que aparecem, as que são parâmetros do construtor escolhido para criar os objetos. Graças à opção [javaParameters], ele conhece os nomes desses parâmetros e reconhece o construtor primário da data class. Como os nomes em Kotlin já estão em “camelCase”, assim como em “JavaScript” e “JSON”, não há nada a converter.
Uma URL que não corresponde a nenhuma rota devolve uma resposta 404:
- Linha 4: o documento é enviado em blocos (chunks), cada um precedido de 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 uma 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.
Também é possível 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

É possível escrever o cliente do serviço com 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] do JDK (Java 11), também apresentada no capítulo anterior; ela cuida do protocolo HTTP para nós e usa o Jackson para os documentos JSON. O projeto [ClientWsHello] é um projeto Kotlin comum, cujo arquivo [build.gradle.kts] declara a dependência do Jackson e a classe principal:
- linha 3: a dependência do Jackson 3; ela tem versão porque este projeto não usa a convenção de versões do Spring Boot;
- linha 11: o Jackson precisa dos nomes dos parâmetros do construtor para criar um objeto [Greeting] a partir de um documento JSON (Capítulo 5);
- linhas 15–17: a classe principal, executada por [gradlew -q :ClientWsHello:run];
- Linhas 20–22: o programa lê o teclado.
O programa é o seguinte:
Comentários:
- linha 13: 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, uma data class com os mesmos nomes de propriedades. Um cliente não compartilha o código do servidor, apenas o formato dos documentos trocados;
- Linha 18: a URL do serviço é passada como argumento; caso contrário, assume por padrão [http://localhost:5100/]: se o endereço do serviço mudar, o cliente não precisa ser recompilado. [firstOrNull()] devolve o primeiro elemento do array, ou [null] se ele estiver vazio, e o operador Elvis [?:] substitui esse [null] pela URL padrão;
- linha 20: o conversor JSON do Jackson 3 (Capítulo 5);
- linha 23: 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 função Kotlin [use] (Capítulo 3) o fecha ao final do bloco, mesmo que ocorra uma exceção;
- linhas 26–27: a pergunta, seguida da leitura da resposta; no fim do fluxo, [readlnOrNull] devolve [null], que o operador Elvis converte em uma string vazia;
- linha 33: o nome digitado se torna um segmento de URL: os caracteres não permitidos nela precisam ser codificados. [URLEncoder.encode] codifica o “é” como [%C3%A9], mas foi projetado para parâmetros de formulário, nos quais o espaço é codificado como [+]. Em um caminho de URL, o espaço deve ser codificado como [%20]: por isso substituímos o [+] (um [+] válido digitado é codificado como [%2B] e não é afetado). [Charsets.UTF_8] é a constante Kotlin para o conjunto de caracteres UTF-8 (a constante Java, [StandardCharsets.UTF_8], também funciona);
- linha 35: 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. A função [get] é chamada como um método de [HttpClient]: é uma função de extensão, definida mais abaixo;
- linhas 38–39: a resposta JSON é desserializada em um objeto [Greeting] por meio do método [readValue] do Jackson;
- linhas 41–43: a exceção [ConnectException] é lançada quando a conexão com o serviço é impossível, por exemplo, quando nenhum serviço escuta no endereço indicado. Ela não tem mensagem; nós construímos uma. O nome [_] indica que a exceção não é usada. Este [catch] deve preceder o da linha 44, porque [ConnectException] deriva de [IOException];
- linhas 44–46: outros erros de comunicação e respostas de erro do serviço (veja a linha 59);
- linhas 54–61: uma requisição GET, cujo corpo da resposta é devolvido como string. Nós a escrevemos como uma função de extensão da classe [HttpClient] (Capítulo 4): em seu corpo,
[send]refere-se ao método[send]do cliente sobre o qual ela é chamada (*[this]*). Em Java, era um método estático que recebia o cliente como parâmetro; - linha 55: a requisição é construída com um builder: URL, método HTTP e, depois, [build];
- Linha 56: o método [send] envia a requisição e espera a resposta. Seu segundo parâmetro, um [BodyHandler], especifica o que fazer com o corpo da resposta: [ofString] lê-o por inteiro em uma string, decodificada de acordo com o conjunto de caracteres indicado pelo cabeçalho [Content-Type] (UTF-8 por padrão). [send] lança [IOException] em caso de erro de comunicação e [InterruptedException] se a thread for interrompida durante a espera. Como o Kotlin não tem exceções verificadas, nem a função [get] nem a função [main] precisam declará-las ([throws IOException, InterruptedException] em Java);
- Linhas 58–59: ao contrário de outras bibliotecas, o [HttpClient] não trata um código de status de erro (4xx, 5xx) como uma exceção: a resposta é devolvida normalmente, e cabe a nós examinar seu código de status. Aqui, disparamos uma [IOException] para qualquer código diferente de 2xx.
Resultados, com o serviço em execução (os dados de entrada, fornecidos ao programa por redirecionamento, foram reinseridos após as consultas):
A linha 4 exibe o objeto [Greeting] recebido, no formato da função [toString] gerada para as data classes: [Greeting(name=…, message=…)], onde um record do Java exibia antes [Greeting[name=…, message=…]]. A opção [-q] (quiet) do Gradle suprime suas próprias mensagens. Se você indicar um endereço onde nenhum serviço escuta, a conexão é recusada:
E se a URL do serviço estiver incorreta, o serviço devolve um 404:
A classe [Greeting] do cliente tem duas propriedades não anuláveis do tipo [String]. O que aconteceria se o serviço omitisse uma delas — [message], por exemplo? O Jackson chamaria o construtor com o valor [null] para o parâmetro [message], e seria o código gerado pelo compilador Kotlin — que verifica, na entrada de toda função pública, que seus parâmetros não anuláveis não são [null] — que rejeitaria esse valor. Verificamos isso com um pequeno programa de teste:
A segurança em relação a [null] é, portanto, preservada, mesmo para objetos criados por reflexão. Já uma propriedade ausente do tipo [Int] é rejeitada pelo próprio Jackson 3 (***[Cannot mapnullinto typeint]***). Para permitir que uma propriedade esteja ausente, ela é declarada como anulável ([String?], [Int?]); é o que faremos nos serviços seguintes. O módulo Kotlin do Jackson, [jackson-module-kotlin] (dependência [tools.jackson.module:jackson-module-kotlin]), vai um passo além: ele inclui valores padrão para parâmetros (uma propriedade ausente assume o valor padrão) e fornece mensagens de erro mais específicas. Fornece também a função de extensão [mapper.readValue<Greeting>(json)], que substitui [mapper.readValue(json, Greeting::class.java)]. Quando incluído entre as dependências de uma aplicação Spring Boot, ele é registrado automaticamente no conversor JSON do Spring (MVC); o Spring Initializr também o adiciona aos projetos Kotlin. Não o usaremos neste curso, pois as data classes e a opção [javaParameters] bastam para nossas necessidades.
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 verdadeiro proxy para o serviço de cálculo de 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 de testes interativa, o Swagger UI, na URL [/swagger-ui.html]. O documento descreve cada rota: sua URL, seu método HTTP, seus parâmetros e seus tipos, e o esquema JSON de suas respostas. Com Kotlin, ela leva em conta a anulabilidade dos tipos: uma propriedade do tipo [String] é declarada obrigatória, enquanto uma propriedade do tipo [String?] é opcional. Geradores como o OpenAPI Generator usam isso para gerar um cliente tipado em várias linguagens (inclusive Kotlin), como o [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 uma única função. 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 formas de passar parâmetros a um serviço web e de informar 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 na query string |
POST /calculation | um documento JSON no corpo da requisição: [{"operation":"add","a":1.5,"b":2}] |
Nos dois casos, a resposta é um documento JSON: [{"operation":"add","a":1.5,"b":2.0,"result":3.5}]. GET é adequado para requisições simples que não modificam nada no servidor: a URL pode ser digitada em um navegador, salva como favorito, e sua resposta pode ser armazenada em cache. POST é adequado para dados volumosos ou estruturados. O arquivo [build.gradle.kts] do projeto é igual ao de [WsHello], exceto pelo comentário, e seu arquivo [WsOperationsApplication.kt] é idêntico ao de [WsHello], exceto pelos nomes ([WsOperationsApplication], pacote [wsoperations]). Seu arquivo [application.properties] é o seguinte:
- 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. É a maneira padrão de um serviço REST indicar o que está errado.
O controller é o seguinte:
Comentários:
- Linhas 20 a 25: a requisição GET. O parâmetro [operation] da função 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: um parâmetro ausente assume o valor [null]. Em Java, era preciso escrever ([@RequestParam(required = false) String a]); em Kotlin, basta declarar o parâmetro como anulável, [String?]: o Spring lê a anulabilidade do tipo por meio de [kotlin-reflect] e deduz que o parâmetro é opcional. Inversamente, um parâmetro não anulável ([String]) é obrigatório: o Spring rejeitaria com uma resposta 400 uma requisição sem esse parâmetro. O tipo declarado informa, portanto, tanto ao compilador quanto ao Spring o que pode estar ausente;
- linhas 23 e 24: [a] e [b] são declarados com o tipo [String?]. Poderíamos tê-los declarado com o tipo [Double?]: o Spring teria então feito a conversão por conta própria e rejeitado um valor incorreto com uma resposta 400 de mensagem genérica. Ao recebê-los como strings, mantemos o controle sobre as mensagens de erro;
- linha 25: a função tem um corpo de expressão. Seu tipo de retorno, [ResponseEntity<*>], é especificado explicitamente: o tipo com asterisco [*] (Capítulo 4) designa uma resposta cujo tipo de corpo não é especificado, equivalente ao [ResponseEntity<?>] do Java;
- linhas 29 a 31: a requisição POST. O parâmetro [request], anotado com [@RequestBody], é construído pelo Jackson a partir do corpo JSON da requisição. As propriedades da classe [CalculationRequest] são anuláveis (linha 79): uma propriedade ausente do documento JSON assume então o valor [null], o que permite detectá-la;
- Linha 35: conversão de uma string em número; se a conversão falhar ([null]), ela é escrita como uma expressão. O operador [?.] propaga o [null] de uma string ausente; a função Kotlin [toDoubleOrNull] retorna [null] em vez de lançar uma exceção; a função [takeIf] retorna seu objeto se a condição for verdadeira, e [null] caso contrário: aqui, ela rejeita os valores [NaN] e os infinitos, que [toDoubleOrNull] aceita (os textos [NaN] e [Infinity]). Tanto na URL quanto no JSON, os números são escritos com ponto decimal: [toDoubleOrNull], que é independente do idioma do sistema, é portanto a ferramenta correta (e não [NumberFormat], que esperaria uma vírgula em um servidor francês; veja o Capítulo 5). Em Java, era necessário um bloco de [try]/[catch] em torno de [Double.parseDouble];
- linha 40: o nome da operação, em minúsculas. A função Kotlin [lowercase] faz a conversão independentemente do idioma do sistema (ela usa [Locale.ROOT], que era preciso especificar em Java);
- linhas 42 a 47: a operação solicitada é representada por uma função do tipo [(Double, Double) -> Double] (Capítulo 7), que é anulável: [((Double, Double) -> Double)?]. Uma expressão [when] seleciona o lambda correspondente à operação; [null] é usado para uma operação desconhecida. O tipo declarado de
*[calculation]permite ao compilador inferir os tipos dos parâmetros*[x]e*[y]* do lambda; - linhas 50 a 64: os três parâmetros são validados. Se algum deles estiver incorreto, é construída uma lista de erros: um dicionário que associa cada parâmetro à sua lista de mensagens de erro. A função [buildMap], que pertence à mesma família de [buildString] e [buildList] (Capítulo 5), cria um dicionário mutável, passando-o como receptor ([this]) ao bloco, no qual [put] o preenche e depois o torna somente leitura; ele preserva a ordem de inserção;
- linhas 60 a 64: a resposta 400. A classe [ProblemDetail] do Spring representa um documento “Problem Details”: [forStatus] o cria com um código de status. A função [apply] (Capítulo 4) executa o bloco com o objeto criado como receptor e depois retorna esse objeto: seu título é definido escrevendo-se a propriedade [title] (o Kotlin trata os métodos Java [getTitle]/[setTitle] como propriedades) e, com [setProperty], adiciona-se qualquer propriedade, 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;
- linha 66: depois do [return] da linha 64, o compilador sabe que [calculation], [a] e [b] não são [null]: são variáveis locais (ou parâmetros) que não podem mais mudar. Ele passa a tratá-los como valores de tipos não anuláveis [(Double, Double) -> Double] e [Double]: é o “smart cast” discutido no Capítulo 3. Estruturamos o teste para aproveitar isso: o código Java testava cada parâmetro separadamente e acumulava os erros em um dicionário, depois verificava se o dicionário estava vazio; no entanto, essa verificação final não diria nada ao compilador sobre [a] e [b];
- linhas 68 a 72: a divisão por zero resulta em uma resposta 400, e desta vez o documento inclui um detalhe ([forStatusAndDetail]). Essa rejeição é necessária: 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.0] compara dois valores [Double]: o literal precisa ser [0.0], porque o Kotlin se recusa a comparar um [Double] com um [Int] ([b == 0] causa um erro de compilação: [operator '==' cannot be applied to 'Double' and 'Int']);
- linha 75: a resposta 200, cujo corpo é o objeto [CalculationResult] serializado em JSON. [calculation(a, b)] chama a função selecionada acima;
- linhas 79 a 82: os dois tipos trocados com os clientes. Esses objetos, que servem apenas para transportar dados entre duas aplicações, são chamados de DTO (Data Transfer Object). As data classes são ideais para essa finalidade. As propriedades de [CalculationRequest], recebidas do cliente, são anuláveis; as de [CalculationResult], produzidas pelo serviço, não são.
As duas funções 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 com [gradlew :WsOperations:bootRun]. Uma adição:
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:
- 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 conexão para a próxima requisição;
- linha 8: o documento contém as propriedades [title], [status] e [detail], definidas pelo nosso código, e [instance], adicionada pelo Spring: o caminho da requisição que causou o erro. A propriedade [type], uma URL que documenta o tipo do erro, está ausente: a RFC 9457 lhe atribui então o valor [about:blank], o que significa que o código de status é suficiente para descrever o problema. Observe que as propriedades estão em ordem alfabética: esse é o comportamento padrão do Jackson 3 para uma classe Java comum como [ProblemDetail], cujos objetos não são criados por um construtor parametrizado; as data classes, como vimos, mantêm a ordem de seu construtor primário.
Uma operação desconhecida, um número escrito com vírgula decimal e um número ausente:
A propriedade [errors] do documento contém os erros de validação, parâmetro por parâmetro; adicionada por [setProperty], ela é colocada depois das propriedades normalizadas. O parâmetro [b], ausente da URL, foi de fato recebido como [null]: ele é opcional porque é anulável. Agora, uma requisição 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] adiciona um cabeçalho à requisição, neste caso o tipo do documento enviado:
Uma propriedade ausente do documento JSON, aqui [operation], é recebida como [null] graças ao tipo anulável da propriedade [operation] de [CalculationRequest]; a operação é então desconhecida:
Se o documento JSON enviado estiver incorreto, o Jackson não consegue construir o parâmetro [request]: o Spring retorna um erro 400 por conta própria, sem executar nossa função:
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 vale se o cabeçalho [Content-Type] for omitido: [curl] envia então o corpo como um formulário HTML, e o Spring rejeita esse tipo de documento:
O código de erro 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

Nosso cliente de console pede 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 [build.gradle.kts] é idêntico ao de [ClientWsHello], exceto pelos nomes do projeto e da classe principal ([clientwsoperations.MainKt]). Seu programa é o seguinte:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 | |
Comentários:
- Linhas 14 a 23: os DTOs 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. As propriedades de [CalculationRequest] não são anuláveis: o cliente envia apenas requisições completas. A classe [ProblemDetail] do Spring faz parte do framework web; uma simples data class é suficiente para o cliente. Suas propriedades são anuláveis: uma propriedade ausente do documento, como [detail] ou [errors], é tratada como [null];
- linha 27: os números são digitados e exibidos no formato do idioma do sistema, neste caso o inglês: ponto decimal. [FORMAT] é uma propriedade de nível superior, privada ao arquivo;
- linha 33: a partir do Jackson 3, as propriedades JSON desconhecidas da classe (aqui, [instance]) são ignoradas por padrão durante a desserialização;
- linhas 43 a 49: a entrada é dividida em campos por meio de uma expressão regular (um ou mais espaços), e depois a lista de três elementos é desestruturada em três variáveis (Capítulo 3): a declaração [val (operation, textA, textB) = fields] chama as funções [component1()], [component2()], e [component3()] da lista;
- Linhas 50 a 58: 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 está chamando), mas um cliente pode evitar tráfego de rede desnecessário. Depois do [continue] da linha 59, o compilador sabe que [a] e [b] não são [null]: eles agora são do tipo [Double] (conversão inteligente de tipo);
- linha 61: o texto que descreve o cálculo, com os números no formato do idioma do sistema;
- linha 64: a URL da requisição GET. Os números devem ser escritos com ponto decimal: um [Double] inserido em um template de string é convertido por sua função [toString], que é independente do idioma do sistema. A operação, digitada pelo usuário, é codificada por [URLEncoder];
- linhas 66 e 67: a requisição GET;
- linhas 68 a 70: em caso de sucesso (código de status 200), o JSON da resposta é desserializado em um objeto [CalculationResult];
- linhas 72 e 73: se a requisição falhar, o código de status e o documento recebido são exibidos como estão;
- linhas 75 a 77: a exceção [IOException] indica um erro de comunicação, como um serviço inacessível;
- linhas 82 a 86: 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 94 a 98: se a validação falhar, o corpo é um documento “Problem Details”, desserializado em um objeto [Problem], cujo título, detalhes e erros de validação são exibidos. As propriedades anuláveis [detail] e [errors] são tratadas pelo operador [?.]: [problem.detail?.let { ... }] executa o bloco somente se o detalhe existir ([it] é então do tipo [String]), e [problem.errors?.forEach { ... }] só percorre o dicionário se ele existir. O lambda passado a [forEach] recebe cada elemento do dicionário ([Map.Entry]), desestruturado em [(parameter, messages)] (Capítulo 7); a função [joinToString] combina as mensagens de um parâmetro;
- linhas 110 a 114: 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 (propriedade [index], método Java [getIndex()]): se não parou no final, a entrada contém caracteres extras ([2.5x]). [parse] retorna um [Number] (ou [null]), convertido por [toDouble()].
Resultados, com o serviço em execução (entradas substituídas após as consultas):
- linha 3: a URL da requisição GET: o número 2 digitado ali é escrito como 2.0;
- Linhas 6 a 8: o mesmo erro observado nas duas requisições: o documento bruto na requisição GET e seu tratamento na requisição POST;
- Linhas 10 a 12: a operação desconhecida foi detectada pelo serviço;
- 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 o cálculo do imposto
Voltamos à aplicação de cálculo do imposto. No capítulo anterior (versão 8), criamos um servidor chamado TCP que podia ser consultado remotamente, usando seu próprio protocolo de comunicação. Vamos agora transformá-lo em um serviço web chamado REST.
13.4.1. A arquitetura
A arquitetura da versão 9 é a seguinte:

- 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] não sabe que o cálculo é realizado em outra máquina;
- nos dois 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. Graças ao build composto declarado em [settings.gradle.kts] ([includeBuild("../06-architectures")]), o Gradle os encontra diretamente na pasta do Capítulo 6 e os compila conforme necessário: diferentemente do Maven, não é preciso instalá-los previamente em um repositório local. As dependências do arquivo [build.gradle.kts] de [WsTax] são as seguintes (o restante do arquivo é igual ao de [WsHello], exceto pelas coordenadas do projeto: [examples.tax:WsTax:9.0]):
- linhas 2 a 5: as dependências de qualquer serviço Spring Boot escrito em Kotlin;
- linha 8: o módulo [tax-business] da versão 5, identificado por suas coordenadas. Ele declara o módulo [tax-dao] como uma dependência de sua API ([api(project(":TaxV5:tax-dao"))], Capítulo 6): esse módulo é, portanto, também visível para o serviço, junto com as classes [ITaxDao], [JsonTax]… da camada [dao] e [TaxBracket] , e [TaxException] da camada [entities]. O módulo [tax-dao] depende do Jackson 3, que o starter web já fornece; portanto, é usada a versão selecionada pela lista de dependências do Spring Boot.
O arquivo de configuração [application.properties] é o seguinte:
- linha 4: o serviço escuta na porta 5120;
- Linhas 13 e 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. Essas não são propriedades do Spring Boot, mas propriedades específicas da nossa aplicação: um arquivo [application.properties] pode conter quantas se desejar. Aqui usamos o arquivo JSON [TaxData.json], localizado na pasta do projeto, que é a pasta de execução do serviço com [gradlew :WsTax:bootRun].
As camadas [dao] e [business] são integradas ao contêiner do Spring por meio de uma classe de configuração:
Comentários:
- Linhas 17 e 18: as propriedades de configuração [dao.*] são agrupadas em um objeto do tipo [DaoProperties], uma data class. A anotação [@ConfigurationProperties("dao")] instrui o Spring Boot a mapear as propriedades com o prefixo [dao] para os parâmetros do construtor de mesmo nome: [dao.implementation] para o parâmetro [implementation], [dao.file] para o parâmetro [file]. Os valores padrão dos parâmetros são usados para as propriedades ausentes da configuração: o Spring Boot, que lê o construtor primário e seus valores padrão por meio de [kotlin-reflect], sabe chamar o construtor sem os argumentos ausentes. Verificamos isso iniciando o serviço sem o arquivo [application.properties]: ele usou a implementação [HardwiredTax]. Essa vinculação é tipada (uma propriedade do tipo [Int] ou [Boolean] seria convertida, e um valor incorreto impediria a inicialização), e o objeto resultante é imutável;
- linha 22: a anotação registra a classe [DaoProperties] no Spring Boot, que cria o objeto na inicialização e o transforma em um bean. Também é possível colocar [@ConfigurationPropertiesScan] na classe principal: o Spring Boot passa então a procurar, por conta própria, as classes anotadas com [@ConfigurationProperties];
- Linhas 21 a 23: a anotação [@Configuration] (Capítulo 6): a classe define beans. O Spring a encontra porque ela está no mesmo pacote da classe principal ([@ComponentScan]). O plugin [plugin.spring] a torna aberta, junto com suas funções;
- Linhas 27 a 32: a função anotada com [@Bean] cria a camada [dao]. Seu parâmetro é fornecido pelo Spring: é o bean [DaoProperties]. Uma expressão [when] seleciona a implementação; uma implementação desconhecida dispara uma [TaxException] ([throw] é uma expressão Kotlin: pode aparecer em um ramo de [when]);
- linha 38: a camada [business]. O parâmetro [dao] da função recebe o bean do tipo [ITaxDao]: o Spring cria, portanto, a camada [dao] antes da camada [business].
O Capítulo 6 injetava cada propriedade separadamente por meio da anotação [@Value]: [@Value("\${dao.implementation}") implementation: String]. Essa abordagem continua possível com o Spring Boot; observe que, em Kotlin, o caractere [$] em [${...}] deve ser escapado com uma barra invertida, caso contrário o compilador o interpretaria como um template de string. [@ConfigurationProperties] é preferível sempre que um grupo de propriedades forma um conjunto: a configuração é descrita por uma classe, que é tipada e validada na inicialização, e é injetada em um bloco onde for necessária. As funções [dao] e [business] reproduzem as da classe [TaxConfig] da versão 5, sem a anotação [@PropertySource]: o Spring Boot lê o arquivo [application.properties] por conta própria.
Essas linhas substituem a integração das camadas que era feita pelo programa principal na versão 5: o contêiner Spring é o mesmo, mas agora o Spring Boot o cria e localiza a classe de configuração por conta própria. Os beans definidos dessa forma são singletons, criados quando a aplicação inicia, antes de qualquer requisição ser processada: se o arquivo de dados estiver ausente ou incorreto, o serviço não inicia, em vez de responder com um erro 500 a todas as requisições. Verificaremos isso mais adiante.
O serviço web é o controller [TaxController]:
Comentários:
- Linha 17: o controller recebe a camada [business] por meio de seu construtor primário. O Spring, que cria o controller, passa a ele o bean [ITaxBusiness] definido por [TaxConfig]: é a injeção por construtor discutida no Capítulo 6. A propriedade [business], declarada como [private val] no construtor, garante que a camada não mudará. O código Java exigia um campo [final] e um construtor de quatro linhas;
- linhas 20 a 31: a requisição GET. Os três parâmetros da query string são recebidos como strings anuláveis (e, portanto, são opcionais) e convertidos: [y]/[n] para [isMarried] (uma expressão [when] cujo tipo é [Boolean?], com o valor [null] de [married?.lowercase()] caindo no ramo [else]), inteiros para [children] e [salary] por meio de [toIntOrNull] e [null] em caso de erro;
- linhas 35 a 37: a requisição POST: o corpo JSON é desserializado em um objeto [TaxRequest] (linha 72), cujas propriedades anuláveis ([Boolean?], [Int?]) permitem detectar valores ausentes. A mesma URL [/tax] está associada a duas funções, de acordo com o método HTTP da requisição;
- linhas 40 a 60: 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 resultado, como o das funções [calculateGet] e [calculatePost], é portanto simplesmente [TaxResponse]: ao ler suas assinaturas, vemos o que o serviço retorna quando tudo corre bem;
- Linha 42: os três parâmetros estão corretos? As comparações [children >= 0] e [salary >= 0] só são avaliadas se eles não forem [null], graças à avaliação preguiçosa do operador [&&]; o compilador sabe disso e trata [children] como [Int] a partir da comparação que segue o teste. Dentro do bloco, [married], [children], e [salary] são de tipos não anuláveis: podem ser passados à função [calculateTax] da camada [business], cujos parâmetros são dos tipos [Boolean] e [Int];
- linha 43: o cálculo é delegado à camada [business] da versão 5;
- linha 44: cada cálculo é registrado no log no nível [INFO]. O texto da mensagem é um template: cada [{}] é substituído pelo argumento correspondente, em ordem. Diferentemente de um template de string do Kotlin (["Tax(married=$married...)"]), a mensagem só é construída se precisar ser exibida (dependendo do nível de log), e as ferramentas de log podem registrar cada valor separadamente;
- linhas 48 a 60: 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 64 a 68: uma função anotada com [@ExceptionHandler] atua como tratador de exceções: o Spring a chama quando uma função do controller lança uma exceção do tipo especificado por seu parâmetro, neste caso [BadRequestException]. O que ela retorna se torna a resposta HTTP: um [ProblemDetail], cujo código de status (400) se torna o código de status da resposta. O documento é construído e renderizado em uma única expressão, usando [apply];
- linhas 72 a 75: os DTOs do serviço;
- linhas 77 a 79: o log da classe. O Spring Boot usa a API de logging SLF4J (Simple Logging Facade for Java), implementada aqui com o Logback. [LoggerFactory.getLogger] retorna um logger cuja categoria é o nome completo da classe. O logger é compartilhado por todas as instâncias da classe: ele é armazenado em seu companion object, o equivalente ao campo [static] do Java (Capítulo 4). Também pode ser declarado como uma propriedade privada de nível superior no arquivo.
A exceção [BadRequestException] é a seguinte:
- Linha 5: a lista de erros é uma propriedade declarada no construtor primário, que também é usada para construir a mensagem passada ao construtor da classe pai, [RuntimeException]. Em Kotlin, todas as exceções são não verificadas: nenhuma função precisa declará-las. As três linhas dessa classe substituem as cerca de vinte linhas da versão Java: não há acessores a escrever nem número de versão de serialização ([serialVersionUID]) a declarar, pois o compilador Kotlin não emite o aviso correspondente que o compilador Java emite; e se quiséssemos excluir a propriedade [errors] da serialização binária, como fazia a palavra-chave Java [transient], nós a anotaríamos com [@Transient]. Nossas exceções nunca são serializadas.
A classe principal [WsTaxApplication.kt] é idêntica à dos outros dois serviços. A pasta [src/main/resources/static] contém o cliente web, discutido na próxima seção.
O serviço web é stateless: as funções do controller não retêm nenhum estado de uma requisição para a seguinte. O controller e as camadas [business] e [dao] são singletons, criados uma única vez, que existem enquanto a aplicação existir; 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 do imposto são lidas uma única vez, e o controller tem apenas uma propriedade, [val]. Um controller nunca deve armazenar em suas propriedades dados específicos de uma requisição. Singleton é o escopo padrão dos beans do Spring; mas existem outros: [prototype] (um objeto por 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 com que cada requisição seja processada por uma thread virtual (Java 21, Capítulo 8) em vez de uma thread do pool do Tomcat: o serviço pode então tratar um número muito grande de requisições simultâneas que aguardam operações de E/S. O Spring MVC também aceita funções de controller [suspend] (Capítulo 9); esses recursos são particularmente úteis com o Spring WebFlux, a variante não bloqueante do Spring MVC, em que uma requisição não ocupa nenhuma thread enquanto espera.
13.4.3. Execução do serviço
Comecemos por um erro de configuração. Os argumentos de linha de comando da forma [--property=value] fazem parte da configuração da aplicação e substituem os valores de [application.properties]. Com o Gradle, eles são passados à tarefa [bootRun] por meio da opção [--args]. Vejamos um arquivo de dados inexistente (no curso, as linhas desse log, que são muito longas, foram abreviadas com [...] e as mensagens do Gradle foram omitidas):
- 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, assim como as do Spring, estão em inglês;
- linha 7: o servidor Tomcat é interrompido; o serviço não aceitou nenhuma requisição;
- linhas 9 a 21: o relatório de falha de inicialização. Sua descrição (linha 17) e a ação recomendada (linha 21) são geradas por uma classe que escrevemos para esse fim.
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 útil é difícil de encontrar. O Spring Boot também pode passar a exceção a 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 adicionar os nossos:
- Linha 9: a classe abstrata
*[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 a função [analyze]. Nossa classe deriva dela: os parênteses em [AbstractFailureAnalyzer<TaxException>()]* representam a chamada ao seu construtor; - linha 11: o parâmetro [rootFailure] é a exceção original, e [cause] é a [TaxException] encontrada na cadeia. A redefinição é indicada pela palavra-chave [override], que é obrigatória em Kotlin. Na classe Java do Spring Boot, o método pode retornar [null] (“não consigo analisar esta exceção”); nossa sobrescrita declara um tipo de retorno não anulável, [FailureAnalysis], o que o Kotlin permite: uma sobrescrita pode restringir o tipo de seu valor de retorno;
- linhas 13 e 14: a descrição do erro: a mensagem da exceção, seguida, entre parênteses, da mensagem de sua eventual causa. [cause.cause?.let { ... } ?: ""] retorna o texto entre parênteses se a causa existir, e uma string vazia caso contrário;
- linhas 16 e 17: 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 precisa 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 fica em [src/main/resources/META-INF]:
- linha 2: a chave é o nome da interface [FailureAnalyzer], e o valor é o nome da nossa classe (várias classes seriam separadas por vírgulas).
Agora vamos iniciar o serviço normalmente, com [gradlew :WsTax:bootRun], e depois consultá-lo com [curl]:
Este é o resultado esperado: um contribuinte casado com dois filhos e renda 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:
Depois, em POST, com um documento JSON:
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 reutiliza a camada [ui] da versão 5 sem modificá-la: o objeto [tax.ui.Dialog], cuja função [run(business: ITaxBusiness)] interage com o usuário e solicita cálculos à camada [business] que lhe é passada. Basta passar a ele uma camada [business] que consulte o serviço web. As dependências do projeto [ClientWsTax] são as seguintes (o restante do arquivo [build.gradle.kts] é igual ao de [ClientWsHello], exceto pelos nomes do projeto e da classe principal: [examples.tax:ClientWsTax:9.0], [tax.client.MainKt]):
- Linhas 3 e 4: os módulos da versão 5: [tax-business] para a interface [ITaxBusiness], [tax-ui] para o objeto [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. O módulo [tax-dao] é uma dependência de API, que por sua vez depende de [tax-business]: o cliente usa dele apenas a classe [TaxException];
- Linha 6: o contêiner Spring. O módulo [tax-ui] depende dele, mas o declara por meio de [implementation] (Capítulo 6): a biblioteca está presente quando o cliente é executado, mas não é visível quando seu código é compilado. O Gradle distingue assim o que um módulo usa internamente do que ele expõe ([api]); como nosso programa principal usa o Spring diretamente, ele mesmo deve declará-lo (enquanto o Maven tornava visíveis todas as dependências indiretas);
- Linha 8: o Jackson, para documentos JSON. Ele também é fornecido por [tax-dao], mas, novamente, como dependência interna: o cliente, que o usa diretamente, deve declará-lo.
A nova camada [business] é a classe [TaxBusinessHttp]:
Comentários:
- linha 14: a classe implementa a interface [ITaxBusiness] da versão 5. Por meio de seu construtor primário, ela recebe o cliente HTTP, que transforma em uma propriedade privada ([private val client]), e a URL do serviço, um simples parâmetro do construtor;
- linhas 17 a 19: os DTOs, declarados dentro da classe ([private]) porque ninguém mais os usa;
- linhas 22 e 23: a URL da função [POST /tax], calculada a partir do valor do serviço durante a inicialização da propriedade (o parâmetro [serviceUrl] do construtor primário pode ser usado em inicializadores de propriedades), e o conversor JSON;
- linhas 27 a 31: a requisição [POST /tax], com a requisição serializada em JSON em seu corpo;
- linhas 32 a 34: a requisição é enviada de forma síncrona: o método [send] aguarda a resposta, o que é apropriado para a função [calculateTax] da interface, que é ela própria síncrona (retorna um [Int]). [try] é uma expressão Kotlin (Capítulo 3): seu valor, neste caso a resposta, é o do bloco [try] se tudo correr bem; como os blocos da forma [catch] terminam com um [throw] (do tipo [Nothing]), a variável [response] é do tipo [HttpResponse<String>] e pode ser um [val], enquanto em Java era preciso declará-la antes do [try];
- Linhas 35 a 37: [send] lança uma [IOException] se o serviço estiver inacessível. Ela é encapsulada em uma [TaxException], a exceção da aplicação [Tax]. O Kotlin não exige isso (ele não tem exceções verificadas), mas é uma boa prática em uma arquitetura em camadas: a camada [ui] trata apenas exceções da aplicação, não as relacionadas ao mecanismo de comunicação usado pela camada [business];
- linhas 38 a 41: o mesmo vale para a exceção [InterruptedException], que é 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) é restaurá-lo com [Thread.currentThread().interrupt()] para que o código chamador saiba que a thread foi interrompida;
- linhas 44 a 47: uma resposta de erro é convertida em [TaxException], cujo código é o código de status HTTP. O construtor de [TaxException] (Capítulo 6) tem um parâmetro [cause] com um valor padrão; para definir o código sem especificar uma causa, o argumento é nomeado: [code = response.statusCode()];
- Linha 51: o JSON da resposta [{"tax":4282}] é desserializado 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 a função [calculateTax] da interface [ITaxBusiness] é síncrona, usamos o método síncrono [send] de [HttpClient]. Este também oferece um método assíncrono, [sendAsync], que retorna imediatamente um [CompletableFuture<HttpResponse<T>>]. Em Kotlin, nós o chamaríamos a partir de uma função [suspend], aguardando o resultado com a função de extensão [await()] de kotlinx-coroutines (Capítulo 9): [suspend fun calculateTax(married: Boolean, nbChildren: Int, salary: Int): Int]. Isso 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 volta a ser uma maneira razoável de escrever programas que envolvem muita E/S: uma thread virtual bloqueada por [send] não bloqueia nenhuma thread do sistema.
O programa principal do cliente integra as camadas:
Comentários:
- linha 14: a URL do serviço, passada como argumento ou, por padrão, [http://localhost:5120/];
- linha 18: o contêiner Spring, como na versão 5. Ele é fechado no final do bloco [use]. O valor do bloco, sua última expressão, é retornado por [use]: é o código de saída do programa;
- linhas 20 a 22: três beans são registrados por meio das funções de extensão [registerBean<T>] do Spring para Kotlin (Capítulo 6): a URL do serviço e o cliente HTTP, fornecidos por lambdas, seguidos da classe [TaxBusinessHttp]. Para criar essa classe, o Spring examina seu construtor primário e lhe passa 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 desconhece a implementação;
- linha 28: o diálogo da versão 5, sem nenhuma modificação; se terminar normalmente, o valor do bloco [try] é sua expressão final, 0;
- linhas 30 a 32: 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 da função [Dialog.displayError] da versão 5, e o valor de [try] é o do bloco [catch], 1;
- Linhas 36 e 37: se ocorrer um erro, o programa termina com o código 1 depois de fechar o contêiner. [exitProcess] é a função Kotlin que chama [System.exit]; seu tipo de retorno é [Nothing], porque ela nunca devolve o controle.
Resultados, com o serviço em execução (entradas substituídas após as consultas):
Vemos os valores de verificação do cálculo do imposto: 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 corretas. Se o serviço for interrompido:
A [TaxException] do 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: sua propriedade [message] vale [null], que o template de string de [displayError] exibe como [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: cada vez que um botão é clicado, o formulário é enviado ao servidor, que devolve ao navegador uma nova página completa. Hoje, o navegador na maioria das vezes consulta diretamente um serviço web, em JavaScript, e atualiza apenas a parte da página que mudou. É isso que vamos fazer. A arquitetura é a seguinte:

- 1: o navegador solicita a página [/]; o servidor [WsTax] envia a ele o arquivo estático [index.html];
- 2: cada vez que o botão [Calculate] é clicado, 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 a mais. 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 [/]: é a página de boas-vindas. Um único servidor pode, assim, hospedar tanto um site quanto um serviço web. A página [index.html], totalmente independente da linguagem em que o serviço é escrito (é a mesma do curso de Java), é a seguinte:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 | |
Comentários:
- linhas 15 a 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 uma mensagem de erro será exibida, se necessário, um campo para o imposto, um parágrafo para uma mensagem geral e dois botões;
- linhas 46 a 108: o código da página, em JavaScript, executado pelo navegador. Este curso não aborda JavaScript; porém, esse código é parecido o bastante com Kotlin para ser entendido com facilidade;
- linha 58: uma entrada que não é um número 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). É uma função assíncrona ([async]): como uma função Kotlin (Capítulo 9), ela não bloqueia o navegador enquanto espera 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 a 77: a requisição, um objeto JavaScript que tem o formato esperado por [POST /tax];
- linhas 80 a 83: a função [fetch] do navegador envia a requisição HTTP: o método [POST], o cabeçalho [Content-Type] e o corpo, a requisição serializada em JSON por [JSON.stringify]. A URL e [tax] são relativas à página: a requisição é enviada ao servidor que forneceu a página. [await] aguarda a resposta sem bloquear o navegador, de modo semelhante à chamada de uma função [suspend] em uma corrotina;
- linha 85: o corpo JSON da resposta é desserializado em um objeto JavaScript;
- linhas 86 a 88: em caso de sucesso (código 2xx), o imposto é exibido;
- Linhas 91 a 94: se ocorrer um erro, o título do documento “Problem Details” é exibido, junto com as mensagens de erro relativas ao número de filhos e ao salário, cada uma ao lado do 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. Os leitores terão reconhecido a chamada segura [?.] e o operador Elvis [?:] do Kotlin, que o JavaScript adotou em 2020;
- Linhas 103 a 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/] com um navegador:

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

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

Essas capturas de tela foram feitas com o navegador Chromium, controlado por um programa por meio da biblioteca Playwright: é assim que automatizamos o teste de uma interface web. Repetimos o experimento com o serviço escrito em Kotlin: a página, as respostas e, portanto, as capturas de tela são idênticas às do serviço escrito em Java. Esse é todo o sentido de um serviço web: seu cliente enxerga apenas os documentos trocados.
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 o serviço 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 solicitar 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 aceitar outras origens, um controller do Spring pode ser anotado com [@CrossOrigin(origins = ["http://localhost:5000"])] (em Kotlin, um argumento do tipo array é escrito entre colchetes dentro de uma anotação); também é possível uma configuração global (o método [addCorsMappings] da interface [WebMvcConfigurer]). 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 no servidor, o Spring MVC também oferece controllers que retornam páginas HTML construídas a partir de templates (Thymeleaf, por exemplo), o que está além do escopo deste curso. O Kotlin também oferece uma solução própria: Kotlin/JS e Kotlin/Wasm compilam código Kotlin para o navegador, permitindo escrever o cliente web na mesma linguagem do serviço, compartilhando as data classes de DTO quando necessário (projetos Kotlin Multiplatform).
13.6. Um serviço web é independente da linguagem de seu cliente
Com um serviço SOAP, o cliente precisava ter uma ferramenta capaz de ler WSDL e gerar o proxy, e as diferenças na interpretação dos padrões entre 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 [curl], que não é escrito em Kotlin, e com o JavaScript do navegador. Eis um cliente escrito para Node.js, o ambiente de execução do JavaScript fora do navegador:
- linha 3: a URL do serviço, passada como argumento ou definida como padrão;
- linhas 6 a 9: três requisições de cálculo, a última das quais é incorreta;
- linhas 14 a 17: a mesma função [fetch] do navegador;
- linhas 20 a 23: exibição do valor do imposto ou dos erros.
Com o serviço em execução:
Em Python, usaríamos de modo semelhante o módulo [requests] ou [httpx] ; em C#, a classe [HttpClient]; e em Java, a classe [HttpClient] que usamos a partir do Kotlin. Por fim, eis o log do serviço [WsTax] ao longo de todos os testes deste capítulo ([curl], cliente de console, navegador, cliente Node.js), até ser encerrado com Ctrl-C (no curso, os caminhos da linha 2 foram abreviados com [...] e as mensagens do Gradle foram omitidas):
- linha 8: o Spring Boot encontrou a página inicial [static/index.html];
- Linhas 14 a 24: mensagens do nosso controller. As linhas que começam com [INFO] registram os cálculos, enquanto as que começam com [WARN] registram requisições inválidas, junto com os nomes dos parâmetros envolvidos. As linhas 14 a 16 vêm do [curl], as linhas 17 a 19 do cliente de console, as linhas 20 e 21 do navegador e as linhas 22 a 24 do cliente Node.js. A categoria do log, [TaxController], é de fato o nome da classe, não o de seu companion object;
- os nomes das threads ([http-nio-5120-exec-1] até [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 processadas pela mesma thread. As duas últimas requisições do cliente de console (linhas 18 e 19) foram tratadas pela mesma thread: o cliente reutilizou a mesma conexão (o HTTP/1.1 mantém a conexão aberta entre duas requisições), e o Tomcat atribui a próxima requisição de uma conexão à primeira thread disponível.
13.7. Informações adicionais
13.7.1. Tipos de resposta e tratamento de erros
O serviço [WsOperations] retorna objetos [ResponseEntity<*>]: pelas assinaturas de suas funções, não fica claro quais respostas elas 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 da função trata apenas o caso normal, e as ferramentas (em particular o gerador de documentos OpenAPI) conhecem o esquema JSON da resposta sem que seja necessário informá-lo explicitamente. Um teste de unidade 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 adicionar 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 rejeitado etc.).
Em Kotlin, o resultado de uma operação também pode ser representado por uma sealed class (Capítulo 4): [sealed interface Result], com uma data class para o sucesso e outra para a falha. Uma expressão [when] exaustiva transforma então cada caso em uma resposta HTTP, e o compilador verifica que nenhum caso foi omitido. Essa é uma alternativa às exceções, preferida pelos desenvolvedores Kotlin, que mantém as possíveis falhas de uma operação visíveis nos tipos.
13.7.2. Um prefixo comum para as rotas
Quando várias rotas compartilham um prefixo, ele é especificado uma única vez 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 versões do 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 pelo método [addInterceptors] de [WebMvcConfigurer], é executada antes e depois dos métodos do controller; ela pode examinar a requisição e responder por conta própria, sem chamar o controller. Eles são usados para logging, medição de tempos de resposta, autenticação etc. 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), as propriedades de um DTO podem ser anotadas com restrições: [data class TaxRequest(@NotNull val married: Boolean?, @NotNull @Min(0) val children: Int?, @NotNull @Min(0) val salary: Int?)]. Com o Kotlin 2.4, uma anotação colocada em uma propriedade declarada no construtor primário se aplica tanto ao parâmetro do construtor quanto ao campo da propriedade, que o validador lê (verificamos isso por reflexão com uma anotação personalizada). Nas versões anteriores do Kotlin, a anotação se aplicava apenas ao parâmetro: era preciso especificar o alvo da anotação, [@field:NotNull], uma forma que ainda é encontrada em muitos exemplos. Um parâmetro [@Valid @RequestBody request: TaxRequest] é então validado antes de a função ser chamada, 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 [gradlew bootRun], o que é adequado para o desenvolvimento. Em produção:
- a aplicação é primeiro empacotada por [gradlew bootJar]: o plugin do Spring Boot gera um único arquivo [.jar] “executável”, que contém a aplicação, suas dependências (incluindo a biblioteca padrão do Kotlin) e o servidor Tomcat. Basta copiá-lo para o servidor e executá-lo com [java -jar WsTax-9.0.jar]; a configuração pode ser modificada por argumentos de linha de comando ([--server.port=80]), variáveis de ambiente ou um arquivo [application.properties] colocado ao lado do arquivo [.jar]. Para a JVM, uma aplicação Kotlin é como qualquer outra aplicação Java;
- o Tomcat pode ser exposto diretamente à Internet, mas muitas vezes é 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]: [gradlew bootBuildImage]. A imagem é então executada em qualquer plataforma de contêineres, seja em seu próprio servidor ou em um provedor de hospedagem;
- o HTTPS é essencial: as propriedades [server.ssl.*] do Spring Boot configuram o certificado do servidor Tomcat quando ele é exposto diretamente.
13.8. Conclusão
Este capítulo apresentou os serviços web REST/JSON, sucessores dos serviços web SOAP, escritos em Kotlin com Spring Boot e Spring MVC. Vimos:
- que um serviço web associa URLs e métodos HTTP a funções Kotlin por meio das anotações [@RestController], [@GetMapping] e [@PostMapping], e que os parâmetros dessas funções vêm da rota ([@PathVariable]), da query string ([@RequestParam]), do corpo (JSON) ([@RequestBody]) ou do contêiner Spring (injeção por meio do construtor primário);
- que o Spring oferece suporte ao Kotlin: [runApplication], parâmetros anuláveis que se tornam opcionais, construtores primários e seus valores padrão ([@ConfigurationProperties]), desde que a biblioteca [kotlin-reflect] seja fornecida e o plugin [plugin.spring] seja aplicado;
- que os resultados são enviados em formato JSON pelo Jackson, com base em data classes, e que os erros são informados por meio de um código de status e de um documento “Problem Details” ([ProblemDetail], [ResponseEntity], [@ExceptionHandler]);
- que um cliente Kotlin 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 prometido: 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, assim 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 50 linhas).