Skip to content

2. Controllers, actions, roteamento

Este capítulo examina o caminho que uma requisição percorre, do navegador até a action que a processa, e a resposta que essa action devolve. As views só serão abordadas no Capítulo 4: aqui, as actions devolvem texto ou JSON diretamente.

2.1. Exemplo 01: A estrutura de uma aplicação Spring MVC

O primeiro exemplo é a menor aplicação [Spring MVC] possível. Além dos arquivos [pom.xml] e [application.properties] apresentados na introdução, ela tem dois arquivos:

01-structure/
├── src/
│   └── main/
│       ├── java/
│       │   └── example01/
│       │       ├── controllers/
│       │       │   └── HomeController.java
│       │       └── Example01Application.java
│       └── resources/
│           └── application.properties
└── pom.xml

2.1.1. O ponto de entrada: Example01Application.java

package example01;

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

// @SpringBootApplication: esta classe é o ponto de partida da aplicação.
// O Spring Boot procura os componentes (controllers, serviços...) em seu
// pacote [example01] e em todos os seus subpacotes.
@SpringBootApplication
public class Example01Application {

    // o método main do Java: o ponto de entrada do programa
    public static void main(String[] args) {
        // iniciamos o Spring: configuração, criação dos objetos, servidor web Tomcat
        // (http://localhost:5000, veja application.properties); Ctrl-C o interrompe
        SpringApplication.run(Example01Application.class, args);
    }
}

Vamos percorrer este código:

  • linha 1: o pacote da classe. Ele deve corresponder ao diretório do arquivo ([src/main/java/example01]);
  • linhas 3–4: classes de outros pacotes usadas por este arquivo. Ao contrário do [C#], o [Java] não tem imports implícitos (exceto o pacote [java.lang], que contém [String], [Integer]...): cada arquivo importa explicitamente as classes que usa;
  • linha 9: [@SpringBootApplication] é uma anotação. Uma anotação [Java] é escrita como [@Name], imediatamente antes do elemento que ela descreve (uma classe, um método, um parâmetro...): ela acrescenta informações que o framework lê na inicialização. Isso equivale aos atributos [[...]] do [C#]. [@SpringBootApplication] marca a classe de inicialização da aplicação e combina três anotações: [@Configuration] (a classe pode declarar objetos gerenciados pelo [Spring]; veja o Exemplo 06), [@EnableAutoConfiguration] (autoconfiguração: o [Spring Boot] configura automaticamente tudo o que as bibliotecas disponíveis permitem, neste caso [Spring MVC], [Tomcat] e [Jackson]) e [@ComponentScan] (varredura de componentes: o [Spring] procura classes anotadas com [@Controller], [@Service]... no pacote dessa classe, [example01], e em todos os seus subpacotes, como [example01.controllers]);
  • linha 13: o método [main], o ponto de entrada de qualquer programa [Java]. Ele é [public] (visível de qualquer lugar) e [static] (pertence à classe, e não a um objeto da classe). O parâmetro [args] contém os argumentos da linha de comando;
  • linha 16: [SpringApplication.run] inicia o [Spring]: lê a configuração (o arquivo [application.properties], as variáveis de ambiente, os argumentos da linha de comando...), cria os objetos da aplicação e então inicia o servidor web [Tomcat], que aguarda requisições até que a aplicação seja interrompida ([Ctrl-C]). [Example01Application.class] refere-se à própria classe: o [Spring] lê dela a anotação [@SpringBootApplication] e deduz o pacote a ser varrido.

Não há mais nada a escrever: nenhuma lista de controllers, nenhuma declaração de rotas. A varredura de componentes encontra os controllers, e a autoconfiguração cuida de todo o resto.

2.1.2. O controller: controllers/HomeController.java

package example01.controllers;

import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.ResponseBody;

// @Controller: esta classe é um controller do Spring MVC
@Controller
public class HomeController {

    // uma ação: o método chamado para a requisição GET /
    @GetMapping("/")
    // @ResponseBody: o valor retornado pela ação É a resposta enviada ao navegador
    @ResponseBody
    public String index() {
        return "Hello from Spring MVC!";
    }
}
  • linha 1: a classe está no pacote [example01.controllers], um subpacote de [example01]: a varredura de componentes a encontra;
  • linha 8: a anotação [@Controller] designa a classe como um controller do [Spring MVC]. A classe não precisa herdar de uma classe do framework (isso difere do [ASP.NET Core MVC]); por convenção, seu nome termina com [Controller]. O [Spring] cria o próprio objeto controller na inicialização;
  • linha 12: a anotação [@GetMapping("/")] associa o método [index] às requisições do tipo [GET /]. Um método associado dessa forma a uma rota é uma action;
  • linha 14: a anotação [@ResponseBody] especifica que o valor devolvido pela action é o corpo da resposta enviada ao navegador. Sem ela, o [Spring MVC] trataria a string devolvida como o nome de uma view a ser exibida (veremos isso no Exemplo 04 e depois no Capítulo 4);
  • linhas 15–16: a action devolve uma string. Por convenção, os nomes dos métodos [Java] começam com letra minúscula.

2.1.3. Execução

Em uma janela de terminal aberta na pasta [01-structure], digite [../mvnw spring-boot:run] ([..\mvnw spring-boot:run] no [Windows]). Após a compilação, o [Spring Boot] exibe seu banner, seguido de suas mensagens de inicialização (substituímos a data, a hora, o número do processo e o nome da thread por [...] e abreviamos os caminhos):

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v4.1.1)

... INFO ... example01.Example01Application : Starting Example01Application using Java 21.0.10 with PID 4545 (.../examples/01-structure/target/classes ...)
... INFO ... example01.Example01Application : No active profile set, falling back to 1 default profile: "default"
... INFO ... o.s.boot.tomcat.TomcatWebServer : Tomcat initialized with port 5000 (http)
... INFO ... o.apache.catalina.core.StandardEngine : Starting Servlet engine: [Apache Tomcat/11.0.24]
... INFO ... o.s.boot.tomcat.TomcatWebServer : Tomcat started on port 5000 (http) with context path '/'
... INFO ... example01.Example01Application : Started Example01Application in 1.509 seconds (process running for 1.864)

As mensagens de inicialização indicam a versão do [Java], a porta de escuta (5000, definida em [application.properties]) e a versão do servidor [Tomcat] embutido na aplicação. Elas também indicam o perfil ativo: [default]. Um perfil é um conjunto de configurações (desenvolvimento, produção etc.); o estudo de caso usará um. Vamos requisitar a URL [http://localhost:5000/] com um navegador:

Image

e depois com o [curl]. A opção [-i] também exibe os cabeçalhos HTTP da resposta (incluiremos aqui apenas alguns):

curl -i http://localhost:5000/
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 22

Hello from Spring MVC!

A primeira linha da resposta é o código de status, 200, sem o texto habitual [OK]: o [Tomcat] não o envia, porque o protocolo HTTP não o exige. O navegador e o [curl] aceitam apenas o código.

O [curl] recebeu a string com o cabeçalho [Content-Type: text/plain]: texto simples. No entanto, o navegador a exibiu como HTML (como se vê pela fonte, que é a mesma das páginas HTML). Isso acontece porque, para uma string devolvida por uma action sem outras especificações, o [Spring MVC] escolhe o tipo da resposta com base no cabeçalho [Accept] da requisição, pelo qual o cliente especifica os tipos que aceita: é a negociação de conteúdo. O [curl] envia [Accept: */*] (todos os tipos) e recebe [text/plain]; um navegador envia [Accept: text/html,...] e recebe [text/html]. Vamos verificar isso enviando um cabeçalho de navegador (opção [-H]) com o [curl]:

curl -i -H "Accept: text/html" http://localhost:5000/
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 22

Hello from Spring MVC!

Isso difere do [ASP.NET Core MVC], que sempre enviava uma string como texto simples. O Exemplo 02 mostrará como especificar o tipo da resposta.

Na primeira requisição, o console exibe mais três linhas:

1
2
3
... INFO ... o.a.c.c.C.[Tomcat].[localhost].[/] : Initializing Spring DispatcherServlet 'dispatcherServlet'
... INFO ... o.s.web.servlet.DispatcherServlet : Initializing Servlet 'dispatcherServlet'
... INFO ... o.s.web.servlet.DispatcherServlet : Completed initialization in 1 ms

O [DispatcherServlet] é o ponto de entrada do [Spring MVC] (veja o diagrama na introdução): o [Tomcat] encaminha todas as requisições para ele, e é ele que seleciona a action atribuída a cada uma. O [Tomcat] só o prepara quando a primeira requisição é recebida.

2.2. Exemplo 02: Roteamento

O roteamento associa uma URL e um método HTTP (GET, POST...) a uma action. O Exemplo 02 tem dois controllers:

1
2
3
4
5
02-routing/src/main/java/example02/
├── controllers/
│   ├── HomeController.java
│   └── FirstController.java
└── Example02Application.java

A classe [Example02Application] é idêntica, exceto pelo nome, à do Exemplo 01: isso vale para todos os exemplos. O arquivo [controllers/HomeController.java]:

package example02.controllers;

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

// @RestController = @Controller + @ResponseBody em cada ação
@RestController
public class HomeController {

    // GET /: uma página HTML contendo links para as outras ações.
    // produces: o tipo da resposta (cabeçalho Content-Type), aqui HTML
    @GetMapping(value = "/", produces = MediaType.TEXT_HTML_VALUE)
    public String index() {
        return """
            <h2>Example 02 - routing</h2>
            <ul>
              <li><a href="/first">/first</a></li>
              <li><a href="/first/action01">/first/action01</a></li>
              <li><a href="/first/products/17">/first/products/17</a></li>
              <li><a href="/first/products/17/reviews/3">/first/products/17/reviews/3</a></li>
              <li><a href="/first/files/images/logo.png">/first/files/images/logo.png</a></li>
              <li><a href="/first/products/abc">/first/products/abc</a></li>
              <li><a href="/unknown">/unknown</a></li>
            </ul>
            """;
    }
}
  • linha 8: [@RestController] combina [@Controller] e [@ResponseBody]: todas as actions da classe devolvem diretamente o corpo da resposta. Esta é a forma mais comum para um controller que não gera views; vamos usá-la até o Capítulo 4;
  • linha 13: uma anotação pode ter vários atributos, escritos como [name = value]. [value] é o caminho da rota (quando está sozinho, [value =] pode ser omitido, como no Exemplo 01); [produces] especifica o tipo da resposta (o cabeçalho [Content-Type]), aqui [text/html], independentemente do cabeçalho [Accept] da requisição. [MediaType.TEXT_HTML_VALUE] é uma constante igual a ["text/html"]: um erro de digitação em seu nome causaria um erro de compilação, o que não acontece com uma string escrita à mão;
  • linhas 15–26: um bloco de texto ([text block], [Java] 15), delimitado por três aspas. Ele pode ocupar várias linhas e conter aspas sem escapá-las. A indentação comum a todas as suas linhas (incluindo a das aspas de fechamento ["""]) é removida.

A action [index] devolve assim uma página HTML que contém links para as actions do outro controller:

Image

O arquivo [controllers/FirstController.java]:

package example02.controllers;

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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

// prefixo compartilhado por todas as rotas do controller
@RestController
@RequestMapping("/first")
public class FirstController {

    // GET /first
    @GetMapping("")
    public String index() {
        return "Action [index] of the [First] controller";
    }

    // GET /first/action01
    @GetMapping("/action01")
    public String action01() {
        return "Action [action01] of the [First] controller, GET request";
    }

    // POST /first/action01: mesmo caminho, outro método HTTP
    @PostMapping("/action01")
    public String action01Post() {
        return "Action [action01Post] of the [First] controller, POST request";
    }

    // GET /first/products/17: {id} é uma variável de caminho; \d+: somente dígitos
    @GetMapping("/products/{id:\\d+}")
    public String product(@PathVariable int id) {
        return "Product no. " + id;
    }

    // GET /first/products/17/reviews/3: duas variáveis de caminho
    @GetMapping("/products/{id:\\d+}/reviews/{number:\\d+}")
    public String review(@PathVariable int id, @PathVariable int number) {
        return "Review no. %d of product no. %d".formatted(number, id);
    }

    // GET /first/files/...: {*path} aceita qualquer final de caminho
    @GetMapping("/files/{*path}")
    public String file(@PathVariable String path) {
        return "Requested file: " + path;
    }
}

Vamos comentar este código:

  • linhas 10–11: a anotação ***[@RequestMapping("/first")]***, aplicada à classe, define o prefixo comum a todas as rotas do controller: suas actions tratam as rotas de URL que começam com ***[/first]***;
  • linhas 15–16: [@GetMapping("")]: a action [index] trata [GET /first]. A URL da action é a concatenação do prefixo do controller com o caminho da action;
  • linhas 21–22: a action [action01] trata [GET /first/action01];
  • linhas 27–28: o mesmo caminho, mas para o método POST: [@PostMapping] substitui [@GetMapping]. Existem também [@PutMapping], [@DeleteMapping], [@PatchMapping]... (e [@RequestMapping], aplicada a um método, aceita todos os métodos HTTP). O nome do método [Java] ([action01Post]) é arbitrário: apenas as anotações importam para o roteamento. Além disso, em uma mesma classe, dois métodos não podem ter o mesmo nome com os mesmos parâmetros;
  • linhas 33–34: [{id}] é uma variável de caminho: esse segmento da URL pode assumir vários valores. [\d+] é uma expressão regular: o segmento deve ser composto por um ou mais dígitos; caso contrário, a rota não corresponde. Em uma string [Java], o caractere [\] é escrito como [\\]: daí [{id:\\d+}]. A anotação [@PathVariable] instrui o [Spring MVC] a passar o valor do segmento ao parâmetro de mesmo nome da action, [id], após convertê-lo em [int]: para [/first/products/17], [id] é igual ao número 17. Este é o binding de dados ([data binding]), que o próximo capítulo examinará em detalhes. Para que o [Spring] conheça os nomes dos parâmetros, o compilador deve preservá-los nas classes compiladas (opção [-parameters]): o [spring-boot-starter-parent] cuida disso;
  • linha 35: o operador [+] concatena uma string e um número;
  • linhas 39–41: duas variáveis de caminho são passadas como dois parâmetros da action. O método [formatted] substitui cada ocorrência de [%d] no texto por um inteiro, na ordem dos argumentos;
  • linhas 45–47: [{*path}] é uma variável “catch-all” ([catch-all]): ela aceita qualquer final de URL, inclusive [/]. Seu valor começa com [/].

Eis os resultados de algumas requisições:

curl -i http://localhost:5000/first
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 40

Action [index] of the [First] controller
curl -i http://localhost:5000/first/action01
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 56

Action [action01] of the [First] controller, GET request
curl -i http://localhost:5000/first/products/17
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 14

Product no. 17
curl -i http://localhost:5000/first/products/17/reviews/3
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 30

Review no. 3 of product no. 17
curl -i http://localhost:5000/first/files/images/logo.png
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 32

Requested file: /images/logo.png

Para enviar uma requisição POST, use a opção [-X POST] do [curl]:

curl -i -X POST http://localhost:5000/first/action01
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 61

Action [action01Post] of the [First] controller, POST request

Um método HTTP que não é tratado por nenhuma action para esse caminho resulta em um erro 405 ([Method Not Allowed]). O cabeçalho [Allow] lista os métodos aceitos:

curl -i -X PUT http://localhost:5000/first/action01
1
2
3
4
5
HTTP/1.1 405
Allow: POST, GET
Content-Type: application/json

{"timestamp":"2026-09-25T16:45:30.867Z","status":405,"error":"Method Not Allowed","message":"Method 'PUT' is not supported.","path":"/first/action01"}

Por fim, uma URL que não é tratada por nenhuma rota resulta em um erro 404. Isso também vale para um identificador que não respeita a expressão regular [\d+]: nenhuma rota corresponde a [/first/products/abc].

curl -i http://localhost:5000/first/products/abc
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-25T16:45:30.828Z","status":404,"error":"Not Found","message":"No static resource first/products/abc.","path":"/first/products/abc"}
curl -i http://localhost:5000/unknown
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"timestamp":"2026-09-25T16:45:30.841Z","status":404,"error":"Not Found","message":"No static resource unknown.","path":"/unknown"}

Ao contrário das do [ASP.NET Core], as respostas de erro do [Spring Boot] contêm as seguintes informações: a data do erro, o código de status, sua descrição, uma mensagem e o caminho requisitado. A mensagem [No static resource] se explica assim: quando nenhuma action corresponde à URL, o [Spring MVC] procura um arquivo estático com esse nome (uma imagem, uma folha de estilo... armazenada na pasta [src/main/resources/static] da aplicação); como não encontra nenhum, ele informa um erro 404. O [Spring Boot] gera então a resposta de erro, e a negociação de conteúdo entra em jogo novamente: o [curl] recebe JSON; um navegador, uma página HTML, a “Whitelabel Error Page” (uma página de erro “sem marca”):

Image

O Capítulo 7 mostrará como substituir essa página por uma página de erro específica da aplicação.

2.3. Exemplo 03: Respostas das actions

O que uma action devolve determina a resposta HTTP. O Exemplo 03 revisa os principais casos. O arquivo [controllers/ResponsesController.java]:

package example03.controllers;

import java.time.Duration;
import java.time.Instant;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CompletableFuture;
import java.util.concurrent.TimeUnit;

import org.springframework.http.HttpStatus;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/responses")
public class ResponsesController {

    // uma string, anunciada como texto simples: o navegador a exibe como está
    @GetMapping(value = "/text", produces = MediaType.TEXT_PLAIN_VALUE)
    public String text() {
        return "<h1>Action [text]</h1>";
    }

    // a mesma string, anunciada como HTML: o navegador a interpreta
    @GetMapping(value = "/html", produces = MediaType.TEXT_HTML_VALUE)
    public String html() {
        return "<h1>Action [html]</h1>";
    }

    // um record: uma classe de dados (veja o exemplo 06), declarada aqui dentro do controller
    public record Person(String lastName, String firstName, int age) {
    }

    // um objeto: serializado em JSON, com o tipo [application/json]
    @GetMapping("/json")
    public Person json() {
        return new Person("Martin", "Jean", 42);
    }

    // uma lista: serializada como um array JSON
    @GetMapping("/list")
    public List<String> list() {
        return List.of("Mme", "Melle", "Mr");
    }

    // ResponseEntity: a ação escolhe a resposta completa (código, cabeçalhos, conteúdo)
    // status(201): o código 201 (Created) em vez de 200 (OK)
    @GetMapping("/created")
    public ResponseEntity<Map<String, String>> created() {
        return ResponseEntity.status(HttpStatus.CREATED).body(Map.of("message", "resource created"));
    }

    // sem resposta: o código 204 (No Content) significa "nada a exibir"
    @GetMapping("/empty")
    public ResponseEntity<Void> empty() {
        return ResponseEntity.noContent().build();
    }

    // uma ação assíncrona: o Spring MVC espera o fim do processamento (CompletableFuture)
    @GetMapping("/task")
    public CompletableFuture<Map<String, String>> task() {
        Instant start = Instant.now();
        // uma espera de 500 ms, sem bloquear a thread que recebeu a requisição
        return CompletableFuture.supplyAsync(
                () -> Map.of("wait", Duration.between(start, Instant.now()).toMillis() + " ms"),
                CompletableFuture.delayedExecutor(500, TimeUnit.MILLISECONDS));
    }

    // um erro "esperado": status(404) produz uma resposta 404
    @GetMapping("/not-found")
    public ResponseEntity<Map<String, String>> notFound() {
        return ResponseEntity.status(HttpStatus.NOT_FOUND).body(Map.of("message", "This resource does not exist"));
    }

    // um erro "inesperado": uma exceção não tratada produz uma resposta 500
    @GetMapping("/exception")
    public String exception() {
        throw new IllegalStateException("An unexpected error");
    }
}

Vamos detalhar este código:

  • linhas 22–25: uma string, marcada como texto simples pelo atributo [produces] (veja o Exemplo 02): o navegador a exibe como está, tags incluídas;
  • linhas 28–31: a mesma string, declarada como HTML: o navegador a interpreta;
  • linhas 34–35: um record ([Java] 16): uma classe de dados, declarada em uma única linha. O compilador cria um campo privado e somente leitura para cada componente ([lastName], [firstName], [age]), um construtor que os inicializa, um método de acesso para cada um ([lastName()], [firstName()], [age()]) e métodos utilitários ([equals], [hashCode], [toString]). O record é declarado aqui dentro do controller: é uma classe aninhada, cujo nome completo é [ResponsesController.Person];
  • linhas 38–41: um objeto é serializado em JSON, com o cabeçalho [Content-Type: application/json]. É a biblioteca [Jackson], fornecida pelo starter [spring-boot-starter-webmvc], que faz a conversão: os nomes das propriedades JSON correspondem aos componentes do record;
  • linhas 44–47: uma lista é serializada em um array JSON. [List.of(...)] cria uma lista somente leitura. [List<String>] é um tipo genérico: uma lista cujos elementos são strings;
  • linhas 51–54: quando a action precisa escolher o código de status, ela devolve um [ResponseEntity<T>]: um objeto que descreve a resposta completa (código, cabeçalhos, corpo do tipo [T]). Ele é criado por meio de métodos estáticos da classe [ResponseEntity], que são chamados em sequência: [status(HttpStatus.CREATED)] define o código como 201 ([Created]), [body(...)] define o conteúdo, que será serializado em JSON. [Map.of("message", "resource created")] cria um dicionário não modificável (um [Map]) com uma única chave, que o [Jackson] serializa no objeto JSON;
  • linhas 57–60: [noContent()] devolve uma resposta 204 ([No Content]): “sem conteúdo”. [build()] devolve uma resposta sem corpo, resultando no tipo [ResponseEntity<Void>];
  • linhas 63–70: uma action assíncrona. Ela devolve um [CompletableFuture<T>], um resultado “pendente” (o equivalente a uma tarefa [Task<T>] do [C#] ou a uma promise do [JavaScript]); o [Spring MVC] libera imediatamente a thread do [Tomcat] que estava processando a requisição e só envia a resposta quando o resultado estiver disponível. [supplyAsync(function, executor)] calcula o resultado por meio da função, que aqui é executada após um atraso de 500 ms. A função é escrita como uma lambda: [() -> expression] é uma função sem parâmetros que devolve o valor da expressão. [Duration.between] mede o tempo decorrido entre dois instantes;
  • linhas 73–76: um erro previsto pelo programa: um [ResponseEntity] com código 404, contendo JSON. A classe [ResponseEntity] também tem atalhos: [ok(...)] (200), [badRequest()] (400), [notFound()] (404)...;
  • linhas 79–82: um erro inesperado: a action lança uma exceção, que ela não trata. O [Spring Boot] responde então com um erro 500 ([Internal Server Error]).

Respostas recebidas:

curl -i http://localhost:5000/responses/text
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 22

<h1>Action [text]</h1>
curl -i http://localhost:5000/responses/html
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/html;charset=UTF-8
Content-Length: 22

<h1>Action [html]</h1>
curl -i http://localhost:5000/responses/json
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 49

{"lastName":"Martin","firstName":"Jean","age":42}
curl -i http://localhost:5000/responses/list
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 20

["Mme","Melle","Mr"]
curl -i http://localhost:5000/responses/created
1
2
3
4
HTTP/1.1 201
Content-Type: application/json

{"message":"resource created"}
curl -i http://localhost:5000/responses/empty
HTTP/1.1 204
curl -i http://localhost:5000/responses/task
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 17

{"wait":"506 ms"}
curl -i http://localhost:5000/responses/not-found
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"message":"This resource does not exist"}
curl -i http://localhost:5000/responses/exception
1
2
3
4
HTTP/1.1 500
Content-Type: application/json

{"timestamp":"2026-09-25T16:45:56.039Z","status":500,"error":"Internal Server Error","message":"An unexpected error","path":"/responses/exception"}

Para a exceção, a resposta de erro do [Spring Boot] (veja o Exemplo 02) contém a mensagem da exceção, mas não a pilha de chamadas, o que é proibido pelo arquivo [application.properties] (veja a introdução). A própria mensagem só aparece ali porque as ferramentas de desenvolvimento ([Spring Boot DevTools]) estão ativas: em produção, sem elas, a resposta seria:

1
2
3
4
HTTP/1.1 500
Content-Type: application/json

{"timestamp":"2026-09-25T16:46:17.984Z","status":500,"error":"Internal Server Error","path":"/responses/exception"}

Uma mensagem de exceção pode, de fato, fornecer informações a um atacante. Os detalhes do erro são gravados no console do servidor (reproduzimos aqui apenas o início):

1
2
3
4
5
... ERROR ... o.a.c.c.C.[.[.[/].[dispatcherServlet] : Servlet.service() for servlet [dispatcherServlet] in context with path [] threw exception [Request processing failed: java.lang.IllegalStateException: An unexpected error] with root cause

java.lang.IllegalStateException: An unexpected error
    at example03.controllers.ResponsesController.exception(ResponsesController.java:81) ~[classes/:na]
    ...

No navegador, a diferença entre [text/plain] e [text/html] é visível:

Image

Image

2.4. Exemplo 04: Redirecionamentos

Uma action pode responder com um redirecionamento: um código de status 301 ou 302 e um cabeçalho [Location] que informa ao navegador qual URL requisitar em seguida. O navegador a requisita imediatamente, sem nenhuma intervenção do usuário. Os redirecionamentos são onipresentes em uma aplicação web: após o envio bem-sucedido de um formulário, após o login, após a troca de idioma...

O arquivo [controllers/RedirectsController.java]:

package example04.controllers;

import java.net.URI;

import org.springframework.http.HttpStatus;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Controller;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.ResponseBody;
import org.springframework.web.servlet.mvc.support.RedirectAttributes;

// @Controller (e não @RestController): uma string retornada por uma ação é
// aqui o NOME DE UMA VIEW, e "redirect:..." um nome de view especial
@Controller
public class RedirectsController {

    // redirecionamento permanente (301): a página mudou de endereço definitivamente
    @GetMapping("/old")
    public ResponseEntity<Void> oldPage() {
        return ResponseEntity.status(HttpStatus.MOVED_PERMANENTLY).location(URI.create("/new")).build();
    }

    @GetMapping("/new")
    @ResponseBody
    public String newPage() {
        return "You are on the [new] page";
    }

    // redirecionamento temporário (302), para um endereço calculado
    @GetMapping("/go/{destination}")
    public String go(@PathVariable String destination) {
        return "redirect:/page/" + destination;
    }

    // redirecionamento para um endereço de TEMPLATE: o Spring substitui {name} pelo valor
    // do atributo [name], codificando-o corretamente para uma URL
    @GetMapping("/to-template/{destination}")
    public String toTemplate(@PathVariable String destination, RedirectAttributes attributes) {
        attributes.addAttribute("name", destination);
        return "redirect:/page/{name}";
    }

    @GetMapping("/page/{name}")
    @ResponseBody
    public String page(@PathVariable String name) {
        return "You are on the [" + name + "] page";
    }

    // redirecionamento para outro site
    @GetMapping("/documentation")
    public String documentation() {
        return "redirect:https://docs.spring.io/spring-framework/reference/web/webmvc.html";
    }
}

Vamos comentar este código:

  • linha 15: a classe é anotada como [@Controller], e não como [@RestController]. Uma string devolvida por uma action é, portanto (exceto com [@ResponseBody]), o nome de uma view; e um nome de view que começa com [redirect:] é um nome especial que dispara um redirecionamento;
  • linhas 19–22: um redirecionamento permanente (código de status 301, [Moved Permanently]): a página mudou definitivamente para um novo endereço. Navegadores e mecanismos de busca podem guardar o novo endereço. Ele é criado com um [ResponseEntity] (veja o Exemplo 03): [location(...)] define o cabeçalho [Location], cujo valor é um objeto [URI] (um endereço);
  • linhas 24–28: a anotação [@ResponseBody] é obrigatória aqui: a string devolvida é o corpo da resposta, e não um nome de view;
  • linhas 31–34: ["redirect:" + url] gera um redirecionamento temporário (código de status 302, [Found]), neste caso para um endereço calculado;
  • linhas 38–42: um redirecionamento para um endereço com template: em [redirect:/page/{name}], o [Spring MVC] substitui [{name}] pelo valor do atributo [name], que é armazenado no objeto [RedirectAttributes]. Esse objeto é fornecido pelo [Spring MVC] à action que o solicita como parâmetro. A vantagem em relação à forma anterior: o valor é corretamente codificado para uma URL (veja abaixo). O objeto [RedirectAttributes] também será usado, no Capítulo 4, para enviar mensagens à página seguinte;
  • linhas 51–54: é possível redirecionar para outro site.

O [curl] demonstra o redirecionamento sem segui-lo de fato:

curl -i http://localhost:5000/old
1
2
3
HTTP/1.1 301
Location: /new
Content-Length: 0

Com a opção [-L], o [curl] segue o redirecionamento, exatamente como faria um navegador. Vemos então as duas respostas sucessivas:

curl -i -L http://localhost:5000/old
1
2
3
4
5
6
7
8
9
HTTP/1.1 301
Location: /new
Content-Length: 0

HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 25

You are on the [new] page
curl -i http://localhost:5000/go/contact
1
2
3
HTTP/1.1 302
Location: http://localhost:5000/page/contact
Content-Length: 0
curl -i http://localhost:5000/to-template/contact
1
2
3
HTTP/1.1 302
Location: http://localhost:5000/page/contact
Content-Length: 0

As duas actions resultam no mesmo redirecionamento. Observe que, desta vez, o endereço do cabeçalho [Location] é absoluto ([http://localhost:5000/...]), embora a action tenha devolvido um endereço relativo ([/page/contact]): um redirecionamento [redirect:] passa pelo servidor [Tomcat], que completa o endereço porque o [Spring Boot] assim o configura por padrão (propriedade [server.tomcat.use-relative-redirects], definida como [false]). O redirecionamento da action [oldPage], gerado por um [ResponseEntity], por outro lado, mantém o endereço como está. As duas formas são corretas.

A diferença entre as duas actions aparece quando o destino contém um caractere que precisa ser codificado em uma URL, como um espaço (codificado como [%20]):

curl -i http://localhost:5000/go/my%20contact
1
2
3
HTTP/1.1 302
Location: http://localhost:5000/page/my contact
Content-Length: 0
curl -i http://localhost:5000/to-template/my%20contact
1
2
3
HTTP/1.1 302
Location: http://localhost:5000/page/my%20contact
Content-Length: 0

A variável de caminho [destination] recebeu o valor decodificado, [my contact]. A concatenação da action [go] o copia exatamente como está: o cabeçalho [Location] contém um espaço bruto, o que o torna um endereço inválido (uma URL não contém espaço). Alguns clientes corrigem isso por conta própria ([curl -L], por exemplo, ainda segue o redirecionamento e chega à página [my contact]), enquanto outros não: isso é uma armadilha, pois o erro passa despercebido durante os testes. A URL com template da action [toTemplate], por outro lado, é codificada corretamente: esta é a maneira adequada de inserir o valor de uma variável em um redirecionamento. No navegador, apenas a página final é visível; a barra de endereços exibe a nova URL:

Image

curl -i http://localhost:5000/documentation
1
2
3
HTTP/1.1 302
Location: https://docs.spring.io/spring-framework/reference/web/webmvc.html
Content-Length: 0

2.5. Exemplo 05: Os objetos Request e Response

[Spring MVC] se baseia na API [Servlet] e no [Jakarta EE] (antes chamado [Java EE]), o padrão de servidor web [Java]: [Tomcat] é um contêiner de servlets, e [DispatcherServlet] é um servlet — ou seja, um objeto ao qual o servidor delega requisições. Nesse padrão, cada requisição é representada por um objeto [HttpServletRequest], e a resposta em construção por um objeto [HttpServletResponse]. Uma action pode receber qualquer um deles: basta solicitá-los como parâmetros. Isso às vezes é necessário, e o faremos no estudo de caso (para ler ou definir um cookie, por exemplo), mas é preciso saber o que se está fazendo.

O arquivo [controllers/HttpController.java]:

package example05.controllers;

import java.io.IOException;
import java.util.LinkedHashMap;
import java.util.Map;

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;

@RestController
@RequestMapping("/http")
public class HttpController {

    // a requisição: método, caminho, parâmetros, cabeçalhos...
    // O Spring fornece o objeto HttpServletRequest à ação que o solicita
    @GetMapping("/request")
    public Map<String, String> request(HttpServletRequest request) {
        // LinkedHashMap: um dicionário que mantém a ordem de inserção das chaves
        Map<String, String> info = new LinkedHashMap<>();
        info.put("method", request.getMethod());
        info.put("path", request.getRequestURI());
        info.put("parameters", request.getQueryString());
        info.put("browser", request.getHeader("User-Agent"));
        info.put("ip", request.getRemoteAddr());
        return info;
    }

    // a resposta: adicionamos um cabeçalho a ela, depois a ação retorna seu valor normalmente
    @GetMapping("/header")
    public String header(HttpServletResponse response) {
        response.setHeader("X-Example", "05-request-response");
        return "Response with an added header";
    }

    // a resposta escrita "à mão": código, tipo e depois o corpo
    @GetMapping("/response")
    public void response(HttpServletResponse response) throws IOException {
        response.setStatus(200);
        response.setContentType("text/plain;charset=UTF-8");
        response.getWriter().write("Response written by [response.getWriter()]");
    }

    // ERRO a não cometer: escrever a resposta e ENTÃO retornar um resultado
    @GetMapping("/double")
    public ResponseEntity<Void> doubleResponse(HttpServletResponse response) throws IOException {
        response.getWriter().write("Start of the response... ");
        // flushBuffer: os primeiros bytes seguem para o navegador
        response.flushBuffer();
        // a resposta já saiu: seu código e seus cabeçalhos não podem mais mudar
        return ResponseEntity.notFound().build();
    }
}

Vamos comentar este código:

  • linhas 12–13: as classes da API [Servlet] estão no pacote [jakarta.servlet...];
  • linha 22: a action declara um parâmetro do tipo [HttpServletRequest]: o [Spring MVC] lhe passa a requisição atual. É assim que o [Spring MVC] fornece a uma action o que ela precisa: com base no tipo de seus parâmetros ou em suas anotações ([@PathVariable]...);
  • linha 24: um dicionário mutável. [Map] é uma interface (um tipo que descreve operações sem implementá-las; voltaremos a isso no Exemplo 06), [LinkedHashMap] é uma de suas implementações; [<>] usa os tipos genéricos da declaração ([<String, String>]);
  • linhas 25–29: a requisição: o método HTTP ([getMethod]), o caminho ([getRequestURI]), os parâmetros da URL ([getQueryString], sem o [?], ou [null] se não houver), um cabeçalho ([getHeader]) e o endereço IP do cliente ([getRemoteAddr]);
  • linhas 34–38: a action adiciona um cabeçalho à resposta e depois devolve normalmente o valor dele, que o [Spring MVC] envia. Este é o uso mais comum do objeto de resposta;
  • linhas 41–46: a action escreve a resposta ela mesma — código de status, tipo e depois o corpo — usando o objeto [PrintWriter] devolvido por [getWriter()]. Ela não devolve nada ([void]): o [Spring MVC] considera então que a resposta foi escrita pela action. A cláusula [throws IOException] declara que o método pode lançar uma [IOException] (um erro de escrita): em [Java], um método deve declarar dessa forma as chamadas exceções verificadas que ele não trata;
  • linhas 49–56: o erro a evitar: escrever parte da resposta e depois devolver um resultado. Depois que os primeiros bytes do corpo foram enviados ao navegador (aqui, forçado por [flushBuffer]), o código de status e os cabeçalhos — que são enviados antes do corpo — não podem mais ser alterados.

As respostas obtidas:

curl -i -A "Mozilla/5.0 (example)" "http://localhost:5000/http/request?name=martin"
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 117

{"method":"GET","path":"/http/request","parameters":"name=martin","browser":"Mozilla/5.0 (example)","ip":"127.0.0.1"}

(a opção [-A] do [curl] define o cabeçalho [User-Agent], que identifica o navegador)

curl -i http://localhost:5000/http/header
1
2
3
4
5
6
HTTP/1.1 200
X-Example: 05-request-response
Content-Type: text/plain;charset=UTF-8
Content-Length: 29

Response with an added header
curl -i http://localhost:5000/http/response
1
2
3
4
5
HTTP/1.1 200
Content-Type: text/plain;charset=UTF-8
Content-Length: 42

Response written by [response.getWriter()]
curl -i http://localhost:5000/http/double
1
2
3
HTTP/1.1 200

Start of the response...

Na última requisição, o cliente recebe um código de status 200 e o início da resposta, em vez do 404 solicitado. E, ao contrário do [ASP.NET Core], o servidor não informa nada: o console permanece em silêncio, e o erro pode passar despercebido. A resposta revela uma segunda falha: ela não tem cabeçalho [Content-Type]. A action não definiu o tipo da resposta antes de escrever nela: o objeto de resposta codifica então o texto de acordo com o conjunto de caracteres padrão do padrão [Servlet], [ISO-8859-1], enquanto o terminal espera UTF-8, de modo que quaisquer caracteres acentuados seriam substituídos por [�] (o texto desta resposta não contém nenhum). O navegador, por sua vez, não recebe nenhuma indicação de conjunto de caracteres; ele tenta adivinhar um — neste caso, com sucesso:

Image

Mais adiante no documento, as actions quase sempre devolverão um valor (um objeto, um [ResponseEntity], um nome de view) e deixarão o [Spring MVC] escrever a resposta. [HttpServletRequest] e [HttpServletResponse] serão usados apenas para ler a requisição e definir cookies.

2.6. Exemplo 06: Serviços e injeção de dependência

Os controllers não devem conter lógica de aplicação; eles a delegam a serviços. Um serviço é um objeto comum que o [Spring] cria e fornece às classes que precisam dele: isso é a injeção de dependência. Os objetos que o [Spring] cria e gerencia dessa forma são chamados de beans (da palavra inglesa para “grãos”; os controllers também são beans). O conjunto de beans de uma aplicação forma o [Spring] contexto, ou contêiner de beans. O Exemplo 06 divide uma pequena aplicação em duas partes: produtos e clientes:

06-services/src/main/java/example06/
├── clients/
│   └── ClientsController.java
├── products/
│   ├── Product.java
│   ├── ProductsConfig.java
│   ├── ProductsController.java
│   ├── ProductsService.java
│   └── InMemoryProductsService.java
└── Example06Application.java

2.6.1. O produto

1
2
3
4
5
6
7
package example06.products;

import java.math.BigDecimal;

// um "record": uma classe de dados cujos campos são definidos pelo construtor
public record Product(int id, String name, BigDecimal price) {
}

Um record (veja o Exemplo 03), desta vez em seu próprio arquivo. O tipo [BigDecimal] representa valores monetários sem erros de arredondamento, o que o tipo [double] não garante.

2.6.2. O contrato do serviço: ProductsService

package example06.products;

import java.util.List;
import java.util.Optional;

// o CONTRATO do serviço: o que ele pode fazer, sem dizer como
public interface ProductsService {

    List<Product> findAll();

    Optional<Product> findById(int id);
}
  • linha 7: uma interface descreve o que o serviço pode fazer, sem especificar como. As classes que usam o serviço conhecerão apenas essa interface. Ao contrário da convenção do [C#] ([IProductsService]), o nome de uma interface [Java] não começa com [I];
  • linha 9: [List<Product>]: uma lista de produtos;
  • linha 11: [Optional<Product>]: um produto, ou nada se nenhum produto tiver esse identificador. Um [Optional] é uma caixa, vazia ou contendo um valor: ele obriga o chamador a considerar o caso em que não há produto, ao passo que um [null] poderia ser esquecido (e causar uma [NullPointerException]).

2.6.3. A implementação: InMemoryProductsService

package example06.products;

import java.math.BigDecimal;
import java.util.List;
import java.util.Optional;

// uma IMPLEMENTAÇÃO do contrato: aqui, dados em memória
public class InMemoryProductsService implements ProductsService {

    private final List<Product> products = List.of(
            new Product(1, "pen", new BigDecimal("1.5")),
            new Product(2, "notebook", new BigDecimal("3.2")),
            new Product(3, "eraser", new BigDecimal("0.8")));

    @Override
    public List<Product> findAll() {
        return products;
    }

    @Override
    public Optional<Product> findById(int id) {
        return products.stream().filter(p -> p.id() == id).findFirst();
    }
}
  • linha 8: a classe implementa a interface ([implements]): ela deve fornecer todos os seus métodos;
  • linhas 10–13: os dados, aqui em memória, em uma lista somente leitura. Os valores são construídos a partir de strings: [new BigDecimal("1.5")] é exatamente 1,5;
  • linhas 15 e 20: a anotação [@Override] indica que o método pertence a uma interface (ou a uma classe pai): o compilador verifica se ele realmente existe;
  • linha 22: um iterador ([stream]) percorre a lista: [filter] retém apenas os produtos que satisfazem a condição, escrita como uma lambda de um único parâmetro (veja o Exemplo 03), [p]; [findFirst] devolve o primeiro produto restante em um [Optional], que fica vazio se não houver nenhum. [p.id()] é o método de acesso ao componente [id] do record.

A classe não tem anotações: é uma classe [Java] comum, que não sabe nada sobre o [Spring]. Veremos mais adiante como ela se torna um bean.

2.6.4. O controller ProductsController

package example06.products;

import java.util.List;
import java.util.Map;

import org.springframework.http.HttpStatus;
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.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/products")
public class ProductsController {

    private final ProductsService productsService;

    // injeção de dependência: o Spring fornece a implementação de ProductsService
    public ProductsController(ProductsService productsService) {
        this.productsService = productsService;
    }

    @GetMapping("")
    public List<Product> list() {
        return productsService.findAll();
    }

    @GetMapping("/{id:\\d+}")
    public ResponseEntity<?> oneProduct(@PathVariable int id) {
        return productsService.findById(id)
                .<ResponseEntity<?>>map(ResponseEntity::ok)
                .orElseGet(() -> ResponseEntity.status(HttpStatus.NOT_FOUND)
                        .body(Map.of("message", "Product no. " + id + " not found")));
    }
}
  • linhas 17–22: injeção de dependência. O controller declara em seu construtor que precisa de um [ProductsService]; o [Spring], que cria o controller, lhe fornece um bean desse tipo (veja abaixo). O controller nunca chama [new InMemoryProductsService()]: ele nem sequer conhece essa classe, apenas a interface. Poderíamos substituir a implementação (por uma versão que lê um banco de dados ou por uma versão de teste) sem modificar o controller. O campo é declarado como ***[final]***: ele só pode ser atribuído uma vez, no construtor;
  • linhas 24–27: a action delega ao serviço. A lista é serializada como JSON;
  • linhas 29–35: [{id:\\d+}] aceita apenas números; um produto inexistente devolve uma resposta 404. O [Optional] devolvido pelo serviço é processado em duas etapas: [map] transforma seu conteúdo, se houver, em uma resposta 200; [orElseGet] fornece a resposta a usar se o [Optional] estiver vazio — neste caso, uma resposta 404 acompanhada de uma mensagem. [ResponseEntity::ok] é uma referência de método: uma forma mais curta de escrever a lambda [p -> ResponseEntity.ok(p)]. O tipo [ResponseEntity<?>] ([?]: qualquer tipo de corpo) permite que a action devolva um produto ou um dicionário; a notação [.<ResponseEntity<?>>map(...)] especifica esse tipo ao compilador, que não consegue inferi-lo sozinho.

2.6.5. O controller ClientsController

package example06.clients;

import java.math.BigDecimal;
import java.util.List;

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

import example06.products.Product;
import example06.products.ProductsService;

// um único construtor: o Spring o usa para a injeção, sem nenhuma outra indicação.
// O campo [final] é, portanto, necessariamente inicializado.
@RestController
@RequestMapping("/clients")
public class ClientsController {

    private final ProductsService productsService;

    public ClientsController(ProductsService productsService) {
        this.productsService = productsService;
    }

    // o conteúdo do carrinho, retornado como JSON
    public record Cart(String client, int items, BigDecimal total) {
    }

    @GetMapping("/cart")
    public Cart cart() {
        List<Product> products = productsService.findAll();
        // a soma dos preços: map (transformar) e depois reduce (acumular)
        BigDecimal total = products.stream().map(Product::price).reduce(BigDecimal.ZERO, BigDecimal::add);
        return new Cart("Jean Martin", products.size(), total);
    }
}
  • linhas 19–23: o [ClientsController] recebe o mesmo serviço que o [ProductsController]. A classe tem apenas um construtor: o [Spring] o usa para a injeção sem nenhuma outra especificação. Esta é a forma de injeção recomendada, e a usada em todo o documento;
  • linhas 26–27: um record aninhado que descreve a resposta JSON;
  • linha 33: o cálculo do total. [map] converte o stream de produtos em um stream de preços ([Product::price] é uma referência ao método de acesso [price()] do record), depois [reduce] os acumula, partindo de zero ([BigDecimal.ZERO]) e somando-os dois a dois ([BigDecimal::add]).

2.6.6. Declarando beans

O [Spring] só pode fornecer um serviço se o conhecer: cada serviço deve ser declarado como um bean. Os controllers são declarados por meio de sua anotação [@RestController], detectada durante a varredura de componentes (veja o Exemplo 01). A classe [InMemoryProductsService], por outro lado, não tem anotação: ela é declarada no arquivo [products/ProductsConfig.java]:

package example06.products;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

// uma classe de CONFIGURAÇÃO: seus métodos @Bean constroem objetos que o Spring
// gerencia ("beans") e fornece a quem precisa deles. Ela agrupa
// as declarações da parte "produtos" da aplicação.
@Configuration
public class ProductsConfig {

    // "quando um ProductsService for solicitado, forneça ESTE objeto"; por padrão, um
    // bean é um singleton: uma única instância, compartilhada por todas as requisições
    @Bean
    public ProductsService productsService() {
        return new InMemoryProductsService();
    }
}
  • linha 9: a anotação [@Configuration] designa a classe como uma classe de configuração; ela também é encontrada pela varredura de componentes, e o [Spring] executa seus métodos anotados com [@Bean] na inicialização. Ela reúne as declarações da parte de “produtos” da aplicação;
  • linhas 14–17: um método anotado com [@Bean] cria um bean. Isso significa: “quando uma classe solicita um [ProductsService], forneça a ela o objeto devolvido por este método”. O nome do método ([productsService]) se torna o nome do bean.

Há outra forma, mais curta, de declarar um bean: anotar a própria classe com [@Service] (ou [@Component], do qual [@Service], [@Controller] e [@Repository] são variantes), que a varredura de componentes encontra da mesma forma que encontra os controllers. Colocar [@Service] antes da classe [InMemoryProductsService] tornaria desnecessário o arquivo [ProductsConfig.java] . O método [@Bean] é útil quando a classe não pode receber uma anotação (uma classe de uma biblioteca, por exemplo) ou quando a criação do objeto exige código. As duas formas serão usadas mais adiante neste documento.

Por padrão, um bean é um singleton: o [Spring] cria uma única instância na inicialização e a fornece a todas as classes que a solicitam durante toda a vida da aplicação. [ProductsController] e [ClientsController] recebem assim o mesmo objeto [InMemoryProductsService]. Existem outros escopos: [prototype] (uma nova instância a cada solicitação), [request] (uma instância por requisição HTTP), [session]... O Capítulo 6 voltará a esse assunto.

Os controllers também são singletons: um único objeto [ProductsController] trata todas as requisições, potencialmente ao mesmo tempo, em várias threads. Esta é uma diferença fundamental em relação ao [ASP.NET Core MVC], que cria um novo objeto controller para cada requisição. Um controller [Spring] não deve, portanto, armazenar em seus campos dados específicos de uma requisição: seus campos contêm apenas os serviços injetados, declarados como [final].

A classe [Example06Application] é igual à dos exemplos anteriores: não há nada a registrar nela; a varredura de componentes encontra os controllers e a classe de configuração nos subpacotes [clients] e [products].

2.6.7. Execução

curl -i http://localhost:5000/products
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 111

[{"id":1,"name":"pen","price":1.5},{"id":2,"name":"notebook","price":3.2},{"id":3,"name":"eraser","price":0.8}]
curl -i http://localhost:5000/products/2
1
2
3
4
HTTP/1.1 200
Content-Type: application/json

{"id":2,"name":"notebook","price":3.2}
curl -i http://localhost:5000/products/9
1
2
3
4
HTTP/1.1 404
Content-Type: application/json

{"message":"Product no. 9 not found"}
curl -i http://localhost:5000/clients/cart
1
2
3
4
5
HTTP/1.1 200
Content-Type: application/json
Content-Length: 46

{"client":"Jean Martin","items":3,"total":5.5}

O estudo de caso é estruturado exatamente assim: controllers enxutos que delegam a serviços injetados, descritos por interfaces e declarados como beans.