1. Introdução
O PDF do documento está |AQUI|.
Os códigos do documento estão |AQUI|.
Este documento é um produto da IA Claude, da Anthropic. Ele dá sequência ao documento “Introdução passo a passo ao framework web [ASP.NET Core MVC]” (2026), que por sua vez seguiu o documento “Introdução passo a passo ao framework web [NestJS]” (2026). Este documento adapta o curso [ASP.NET Core MVC] ao ambiente [Java]:
- o framework [ASP.NET Core MVC] e a linguagem [C#] são substituídos pelo framework [Spring MVC], junto com o [Spring Boot] 4, e pela linguagem [Java] 21;
- as views [Razor] são substituídas por views [Thymeleaf];
- o ORM e o [Entity Framework Core] são substituídos por [Spring Data JPA] e pelo ORM [Hibernate], sempre com base no [MySQL].
O documento segue de perto a progressão do curso [ASP.NET Core MVC]: primeiro, vários pequenos projetos, cada um focado em um único conceito, seguidos de um estudo de caso completo — uma aplicação web de agendamento de consultas em um consultório médico — com todos os arquivos totalmente comentados. Os exemplos têm os mesmos números e abordam os mesmos temas que no curso [ASP.NET Core MVC]: um leitor que conheça esse curso pode comparar os dois frameworks exemplo a exemplo. No entanto, isso não é necessário: este documento é autossuficiente e não pressupõe nenhum conhecimento prévio de [ASP.NET], nem, aliás, de [Spring]. Os únicos pré-requisitos são noções básicas de programação web (o protocolo HTTP, a linguagem HTML) e a linguagem [Java].
1.1. O papel do Spring MVC em uma aplicação web
Uma aplicação web costuma ser construída em camadas, cada uma se comunicando apenas com as camadas vizinhas:

- a camada web recebe as requisições HTTP do navegador e devolve a ele páginas HTML. O [Spring MVC] nos ajuda a escrever essa camada;
- a camada de negócio contém as regras de negócio da aplicação (por exemplo, “um paciente só pode ter uma consulta futura”). Ela não sabe nada sobre a web: poderia servir igualmente a uma aplicação de linha de comando;
- a camada de acesso a dados (camada [DAO], de [Data Access Object]) lê e grava no banco de dados. Usaremos o [Spring Data JPA], que se apoia em um ORM, o [Hibernate] ([Object Relational Mapper]), para mapear as linhas das tabelas e os objetos em [Java].
A própria camada web segue o modelo [MVC] ([Model – View – Controller]):
- o controller (C) é uma classe cujos métodos, chamados de actions, tratam cada um um tipo específico de requisição (por exemplo, [GET /schedule]). Uma action lê os parâmetros da requisição, invoca a camada de negócio e, em seguida, escolhe a view a exibir;
- o modelo (M) é o conjunto de dados que a action passa à view;
- a view (V) é um arquivo chamado [Thymeleaf] (com a extensão [.html]): uma página HTML em que certas tags têm atributos [th:...] ([th:text], [th:each]...), que a engine [Thymeleaf] substitui por dados do modelo.
O processamento de uma requisição segue as etapas numeradas do diagrama:
- 1: O navegador envia uma requisição HTTP, por exemplo [GET /schedule?doctorId=1&day=2026-09-24];
- 2: O servidor web [Tomcat], embutido na aplicação pelo [Spring Boot], recebe a requisição. Ela passa por uma série de filtros (leitura de cookies, autenticação etc.) e então chega ao [DispatcherServlet], o ponto de entrada único do [Spring MVC], que seleciona a action responsável por tratar essa requisição: este é o roteamento. Antes de chegar à action, a requisição ainda pode passar por interceptors, que exploraremos em capítulos posteriores;
- 3: A action solicita à camada de negócio os dados de que precisa; se necessário, a camada de negócio aciona a camada [DAO], que consulta o banco de dados [MySQL] em SQL;
- 4: A action constrói o modelo M da view e designa a view que deve exibi-lo;
- 5: A engine de views [Thymeleaf] gera a página HTML, que o [Spring MVC] devolve ao navegador.
[Spring] é o framework mais usado do mundo ([Java]) para desenvolver aplicações corporativas. Gratuito e de código aberto, funciona em qualquer lugar onde o [Java] ([Windows], [Linux], [macOS]) funcione. [Spring MVC] é o componente web; [Spring Boot] é uma camada superior que configura automaticamente todo o conjunto (servidor web, conversão JSON, engine de views, acesso a dados etc.) de acordo com as bibliotecas presentes no projeto, e transforma a aplicação em um programa [Java] comum, iniciado por um método [main]. [Spring MVC] pode criar servidores que devolvem JSON a um cliente [JavaScript] ([Angular], [React], [Flutter]...), bem como aplicações web tradicionais, nas quais o servidor gera as páginas HTML e o navegador apenas as exibe. Este documento se concentra neste último caso de uso. Como o [ASP.NET Core], [Spring] se baseia em duas ideias: anotações ([@GetMapping], [@RequestMapping], [@PreAuthorize]...) descrevem os papéis das classes e dos métodos, e a injeção de dependência fornece a cada objeto as dependências de que ele precisa. [Spring] é, aliás, um dos frameworks que popularizaram essa segunda ideia.
1.2. Ferramentas utilizadas
Os exemplos foram escritos e testados com as seguintes ferramentas (a instalação delas é descrita no apêndice):
- [JDK] 21 ([Java Development Kit]), que contém o compilador [javac] e a máquina virtual [java]. [Java] 21 é uma versão LTS (suporte de longo prazo);
- a ferramenta de build [Maven] 3.9.11, que não precisa ser instalada: cada projeto contém um Maven Wrapper (os scripts [mvnw] e [mvnw.cmd]), que baixa automaticamente a versão correta do [Maven] no primeiro uso;
- o editor [Visual Studio Code], junto com as extensões [Extension Pack for Java] e [Spring Boot Extension Pack] ;
- um navegador recente ([Chrome], [Firefox], [Edge]);
- a ferramenta de linha de comando [curl], que exibe as respostas HTTP brutas (ela já vem com o [Windows] 10 e 11);
- o SGBD [MySQL] (ou [MariaDB]), por exemplo, o do [Laragon] no [Windows], a partir do capítulo sobre acesso a dados e para o estudo de caso.
Ao contrário do SDK do [.NET], que contém o [ASP.NET Core], o [JDK] não contém o [Spring]: o framework é um conjunto de bibliotecas que o [Maven] baixa do repositório central [Maven Central] durante a primeira compilação (portanto é preciso estar conectado à Internet nesse dia) e depois armazena em uma pasta local ([.m2] no diretório pessoal do usuário). Essas bibliotecas são agrupadas em starters: um starter é uma única dependência que fornece tudo o que é necessário para um recurso específico. Todos os exemplos usam o [spring-boot-starter-webmvc] ([Spring MVC] e o servidor [Tomcat]); além disso, há o [spring-boot-starter-validation] (validação de dados, a partir do Capítulo 3), [spring-boot-starter-thymeleaf] (views, a partir do Capítulo 4), [spring-boot-starter-security-oauth2-resource-server] ([Spring Security] e os tokens JWT, no Capítulo 8), [spring-boot-starter-data-jpa] e o driver [mysql-connector-j] (acesso ao banco de dados, no Capítulo 9). As versões usadas são as do [Spring Boot] 4.1.1: [Spring Framework] 7.0.9, [Spring Security] 7.1.1, [Hibernate] 7.4.5, [Thymeleaf] 3.1.5, [Jackson] 3 (conversão de JSON) e [Tomcat] 11.
1.3. Execute o estudo de caso
Nota do revisor: aconselho o leitor a executar o estudo de caso imediatamente, como descrito a seguir. Depois de entender bem o papel desta aplicação de agendamento de consultas, peça à sua IA favorita que modifique a aplicação da seguinte forma: a partir de agora, cada médico poderá:
- definir seus próprios horários de consulta entre duas datas. Isso permitirá que ajustem a agenda conforme necessário;
- remover certos horários da agenda em um determinado dia — por exemplo, se estiverem indisponíveis por motivos pessoais;
A modificação não é trivial, pois envolve uma alteração na estrutura do banco de dados. Peça à IA que lhe forneça o novo código da aplicação e o script SQL para criar o novo banco de dados. Para isso, você precisará fornecer a ela o arquivo ZIP com o projeto completo, bem como o script SQL do banco de dados antigo.
Além disso, não revisei o curso criado pelo Claude. Ele já havia produzido dois cursos perfeitos: [NestJS] e [ASP.NET Core MVC]. Presumi que o mesmo valesse para este. Se você tiver dificuldade para entender algo, a solução é sempre a mesma: peça à sua IA favorita que explique o que você não entendeu. Claude, por exemplo, é muito bom nisso. Talvez seja necessário “enviar” a ele o exemplo que você não entende.
Fim da nota.
O estudo de caso ao final deste documento é uma aplicação completa. O leitor provavelmente vai querer vê-la funcionando antes de mergulhar nos detalhes do framework: veja como executá-la. Ela está na pasta [rdvmedecins2-spring-mvc], ao lado da pasta [examples]:
É preciso ter instalado o [JDK] 21, o [Visual Studio Code], e o [MySQL] (veja os apêndices). O [Maven] não precisa ser instalado. Em seguida:
- Crie o banco de dados [dbrdvmedecins2] executando o script [rdvmedecins2-spring-mvc/database/dbrdvmedecins2.sql]. Com o [Laragon], abra a ferramenta [HeidiSQL] (botão Database) e execute o script pelo menu File / Run SQL. Na linha de comando, a partir da pasta [rdvmedecins2-spring-mvc]:
- Verifique a conexão com o banco de dados. A aplicação se conecta ao [MySQL] em [localhost], porta 3306, com o usuário [root] sem senha (as configurações padrão do [Laragon]). Se a sua conta [root] tiver senha, informe-a no arquivo [src/main/resources/application.properties] da aplicação, na linha [spring.datasource.password=] (por exemplo, [spring.datasource.password=myPassword]). Para evitar gravar uma senha em um arquivo do projeto, você também pode informá-la na variável de ambiente [SPRING_DATASOURCE_PASSWORD], que tem precedência sobre o arquivo: [set SPRING_DATASOURCE_PASSWORD=myPassword] no [Windows] (prompt de comando), [export SPRING_DATASOURCE_PASSWORD=myPassword] no [Linux] e no [macOS];
- abra a pasta [rdvmedecins2-spring-mvc] no [Visual Studio Code] (menu File / Open Folder) e depois abra um terminal (menu Terminal / New Terminal);
- Inicie a aplicação no [Linux] e no [macOS]:
e no [Windows]:
- Na primeira execução, o Maven Wrapper baixa o [Maven] e, em seguida, o [Maven] baixa as bibliotecas da aplicação, o que leva alguns minutos. Depois a aplicação é compilada e iniciada. O console exibe o banner do [Spring Boot], seguido das mensagens de inicialização (incluímos aqui apenas as principais):
Cada linha começa com a data e a hora (substituídas aqui por [...]), seguidas do nível da mensagem ([INFO], [WARN], [ERROR]), do número do processo e do nome da thread (também substituídos por [...]) e, por fim, do nome abreviado da classe que escreve a mensagem. Ela mostra que a aplicação está sendo executada no perfil [dev] (um conjunto de configurações específicas de desenvolvimento que, entre outras coisas, exibe as requisições SQL), que o servidor [Tomcat] está escutando na porta 8081, que a conexão com o banco de dados foi bem-sucedida (o “pool” de conexões [HikariCP] está pronto) e que a aplicação já leu a lista de médicos e de clientes (as duas requisições SQL). Junto com o [MariaDB], o [Hibernate] também exibe um aviso [HHH000511], que não tem consequências;
- Abra a URL [http://localhost:8081] em um navegador:

- Faça login com uma das contas de demonstração, cuja senha é igual ao nome de usuário: [admin] (administrador), [pelissier], [tatou], [dupont] (médicos), [martin], [durand], [bistrou], [german] (pacientes). Você também deve digitar os caracteres da imagem, em maiúsculas ou minúsculas.
Ao iniciar, a aplicação lê o banco de dados: se o [MySQL] estiver inacessível, ela para imediatamente e o console exibe o motivo. Se a mensagem for [Communications link failure] (ou [Connection refused]), significa que o [MySQL] não foi iniciado; com [Access denied for user 'root'@'localhost'], significa que a senha está incorreta; com [Unknown database 'dbrdvmedecins2'], significa que o script SQL não foi executado; com [Port 8081 was already in use], que a porta 8081 já está em uso (pela versão [ASP.NET Core] da aplicação, por exemplo); com [release version 21 not supported] (ou [invalid target release: 21]), que o [JDK] instalado é anterior à versão 21. O arquivo [README.md] da aplicação descreve outros casos. Pare a aplicação com [Ctrl-C] no terminal.
O último capítulo do documento explica como usar a aplicação e depois comenta cada um de seus arquivos.
1.4. Exemplos
Os exemplos ficam na pasta [examples], com uma subpasta por exemplo:
Cada exemplo é um projeto [Maven] independente que pode ser compilado e executado separadamente. Um projeto [Maven] é descrito por um arquivo [pom.xml] ([Project Object Model]): sua identidade, as bibliotecas das quais depende (suas dependências) e como construí-lo. Os 28 projetos são módulos de um projeto pai, descrito pelo arquivo [examples/pom.xml]. Os scripts [mvnw] ([Linux], [macOS]) e [mvnw.cmd] ([Windows]) formam o Maven Wrapper; o arquivo [.mvn/wrapper/maven-wrapper.properties] especifica a versão do [Maven] que ele deve baixar (3.9.11).
A pasta [common/bootstrap] contém o CSS e o framework [Bootstrap], compartilhados pelos exemplos que formatam suas páginas (a partir do Exemplo 15).
Cada exemplo tem a estrutura padrão de um projeto [Maven]:
- [src/main/java]: o código [Java], organizado em pacotes (as pastas [example13], [example13/controllers]...). Um pacote [Java] equivale a um namespace do [C#]; o nome de um pacote reflete o caminho de sua pasta ([example13.controllers]);
- [Example13Application.java]: a classe de inicialização da aplicação, que contém o método [main] (veja o Exemplo 01);
- [controllers]: os controllers;
- [models]: as classes que descrevem os modelos (das actions e das views);
- [src/main/resources]: arquivos que não fazem parte do código [Java];
- [templates]: as views [Thymeleaf] (a partir do Capítulo 4);
- [application.properties]: a configuração da aplicação (porta de escuta e, mais adiante, conexão com o banco de dados etc.);
- [pom.xml]: o arquivo do projeto, que descreve como construir a aplicação.
Durante a compilação, o [Maven] cria em cada exemplo uma pasta chamada [target], na qual armazena as classes compiladas; essa pasta pode ser apagada sem risco.
Para executar um exemplo, abra um terminal na pasta do exemplo (no [Visual Studio Code]: clique com o botão direito na pasta do exemplo e selecione "Open in the built-in terminal") e digite o seguinte no [Linux] e no [macOS]:
e no [Windows]:
O Maven Wrapper fica na pasta [examples], que é a pasta pai da pasta do exemplo: daí o [../] (ou [..\]). O comando [spring-boot:run] compila o exemplo (em sua pasta [target]) e depois inicia a aplicação. Todos os exemplos escutam na porta 5000: só um pode estar em execução por vez. Pare o servidor com [Ctrl-C] no terminal. Também é possível compilar todos os exemplos de uma vez a partir da pasta [examples] para verificar se a instalação está completa:
([mvnw compile] no [Windows]).
Quando você abre a pasta [examples] no [Visual Studio Code], a extensão [Extension Pack for Java] encontra o arquivo [pom.xml] pai e importa todos os módulos (eles aparecem no painel “Java Projects”): você passa a ter realce de sintaxe, autocompletar e relatório de erros em cada arquivo. Com as configurações padrão, ela também compila cada arquivo [.java] assim que você o salva. A extensão [Spring Boot Extension Pack] adiciona um painel “Spring Boot Dashboard”, que lista as aplicações encontradas e permite iniciá-las ou pará-las sem usar o terminal (a aparência exata desses painéis depende da versão das extensões). Por fim, todos os exemplos dependem do [Spring Boot DevTools] (veja abaixo): uma aplicação em execução é reiniciada automaticamente — em um ou dois segundos — assim que uma de suas classes é recompilada. Com o [Visual Studio Code], portanto, em princípio basta salvar um arquivo modificado para que a aplicação o leve em conta.
O arquivo [pom.xml] do projeto pai [examples/pom.xml]:
Vamos comentar este arquivo:
- linhas 14–19: o projeto pai herda, por sua vez, de um pai, [spring-boot-starter-parent], versão 4.1.1. Esse projeto define as versões de todas as bibliotecas do [Spring] e das bibliotecas que ele usa, escolhidas para funcionarem em conjunto: é por isso que nenhuma dependência especifica uma versão adiante. Ele também controla a compilação (codificação UTF-8 do código-fonte, versão do [Java]...). O elemento vazio [<relativePath/>] indica que esse pai não é uma pasta vizinha, mas deve ser procurado nos repositórios do [Maven];
- linhas 22–24: a identidade do projeto: um grupo ([groupId]), um nome ([artifactId]) e uma versão. Os módulos usam essa identidade para se referir ao pai;
- linha 26: um projeto do tipo [pom] não produz classes nem arquivos compactados; ele agrupa módulos e lhes repassa suas configurações;
- linhas 28–31: a versão-alvo do [Java]: [Java] 21;
- linhas 34–63: os módulos, um a um; por exemplo, o nome da pasta de cada um. Um comando [Maven] executado na pasta [examples] se aplica a todos os módulos;
- linhas 66–78: dependências comuns a todos os exemplos, herdadas por cada módulo;
- linhas 68–71: o starter [spring-boot-starter-webmvc] fornece o [Spring MVC], o servidor web [Tomcat] embutido na aplicação (não é preciso instalar nenhum servidor) e a biblioteca [Jackson], que converte objetos [Java] em JSON;
- linhas 73–77: [Spring Boot DevTools], ferramentas de desenvolvimento: reinicialização automática da aplicação quando uma classe é recompilada, desativação de caches (como o cache de views) e mensagens de erro mais detalhadas. Elas servem apenas para o desenvolvimento: o plugin do [Spring Boot] (linhas 80–88) não as inclui no arquivo executável ([.jar]) destinado à produção, e elas são desativadas automaticamente se a aplicação for iniciada por [java -jar];
- linhas 80–88: o plugin [Maven] do [Spring Boot]. Esse plugin fornece o comando [spring-boot:run], bem como a criação de um arquivo executável ([mvnw package]).
O arquivo [pom.xml] de um exemplo é muito curto. Por exemplo, [01-structure/pom.xml]:
- linhas 6–10: o pai — o projeto [examples], identificado por seu ID. O módulo herda suas dependências e configurações e, por meio dele, as do [spring-boot-starter-parent];
- linha 11: o nome do módulo. Seu grupo e sua versão são os do pai.
Um exemplo que exige uma biblioteca adicional a declara em seu próprio [pom.xml]. Por exemplo, [13-first-view/pom.xml], que usa a engine de views [Thymeleaf]:
- linhas 3–6: uma dependência é identificada por seu grupo e seu nome; sua versão é definida pelo [spring-boot-starter-parent].
O arquivo [src/main/resources/application.properties] começa da mesma forma em todos os exemplos:
- linha 2: a porta de escuta do servidor. Sem essa linha, o [Spring Boot] escutaria na porta 8080; escolhemos a porta 5000, a usada no curso [ASP.NET Core MVC];
- linha 4: quando uma requisição falha, o [Spring Boot] devolve uma resposta de erro (trataremos disso no próximo capítulo). Essa configuração garante que a resposta nunca contenha a pilha de chamadas (a lista de métodos em execução no momento do erro), o que revelaria informações sobre o código da aplicação a um atacante.
Cada linha tem a forma [key=value]; as linhas que começam com [#] são comentários. Alguns exemplos acrescentam suas próprias chaves depois dessas duas linhas.
Por fim, os exemplos que usam o [Bootstrap] o encontram na pasta [common/bootstrap], e não em sua própria pasta: assim, existe apenas uma cópia do arquivo. Cada um desses exemplos tem uma classe de configuração que serve essa pasta na URL [/bootstrap/...]. Por exemplo, [15-layout/src/main/java/example15/config/WebConfig.java]:
- linhas 8–9: uma classe de configuração do [Spring MVC] (os exemplos 06 e 12 explicarão esse mecanismo);
- linhas 14–18: os arquivos de URL que começam com [/bootstrap/] são servidos a partir da pasta [../common/bootstrap/], relativa à pasta atual — isto é, a pasta do exemplo quando ele é iniciado como descrito acima. Uma página pode assim usar a folha de estilo [/bootstrap/css/bootstrap.min.css]. A segunda pasta, [common/bootstrap/], é usada quando a aplicação é iniciada a partir da pasta [examples], e não da pasta do exemplo.
1.5. Conteúdo do documento
O documento se desenvolve da seguinte forma:
Capítulo | Conteúdo | Exemplos |
Controllers, actions e | Do navegador à action: rotas, respostas, redirecionamentos, serviços e injeção de dependência | 01–06 |
O modelo da action | Parâmetros da requisição: binding, conversão, validação, formulários POST | 07 a 12 |
A view e seu template | Thymeleaf, template, fragmentos, formulários, validação, PRG | 13 a 21 |
Internacionalização | Uma aplicação em francês e inglês | 22 |
Escopos de dados | aplicação, requisição, sessão, cliente | 23 |
O ciclo de vida de uma requisição | filtros de servlet, interceptors, [@ControllerAdvice], binding de template, página de erro | 24 |
Autenticação e autorização | Spring Security, JWT em um cookie, papéis, CAPTCHA, limite de tentativas | 25–27 |
Arquitetura em camadas | Web / negócio / DAO com Spring Data JPA e MySQL | 28 |
Estudo de caso | A aplicação RdvMedecins, explicada arquivo por arquivo | - |
Cada exemplo introduz apenas alguns conceitos novos, e os capítulos se apoiam uns nos outros: o melhor é lê-los em ordem. O estudo de caso, por sua vez, reúne todos os conceitos dos capítulos anteriores: sempre que pertinente, seu comentário remete ao exemplo em que o conceito foi introduzido. Os apêndices descrevem como instalar as ferramentas: o [JDK] 21, o [Visual Studio Code] e suas extensões, o Maven Wrapper, o [MySQL] com o [Laragon] e o [curl].