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á continuidade ao documento “Introdução passo a passo ao framework web [Spring MVC]” (2026), que por sua vez seguiu os documentos “Introdução passo a passo ao framework web [ASP.NET Core MVC]” e “Introdução passo a passo ao framework web [NestJS]” (2026). Este documento adapta o curso [Spring MVC] ao ambiente [Python]:
- o framework [Spring MVC] e a linguagem [Java] são substituídos pelo framework [Flask] 3.1 e pela linguagem [Python] (versão 3.12 ou posterior);
- as views [Thymeleaf] são substituídas por views [Jinja2], a engine de views do [Flask];
- a validação com [Bean Validation] é substituída pela biblioteca [Pydantic] (parâmetros das actions) e pela biblioteca [WTForms] (formulários HTML);
- o [Spring Security] é substituído por algumas dezenas de linhas de [Python] escritas para essa finalidade, que se apoiam nas bibliotecas [PyJWT] (os tokens JWT) e [bcrypt] (hash de senhas);
- o ORM [Hibernate] e o [Spring Data JPA] são substituídos pelo ORM [SQLAlchemy], ainda com [MySQL].
O documento segue de perto a estrutura do curso [Spring MVC]: primeiro, numerosos pequenos projetos, cada um centrado em um conceito específico, 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 integralmente comentados. Os exemplos têm os mesmos números e tratam dos mesmos temas que nos cursos [Spring MVC] e [ASP.NET Core MVC]: um leitor familiarizado com um desses cursos pode comparar os frameworks exemplo por exemplo. No entanto, isso não é necessário: este documento é autossuficiente e não pressupõe nenhum conhecimento prévio de [Spring] nem de [ASP.NET]. Os únicos pré-requisitos são noções básicas de programação web (o protocolo HTTP, a linguagem HTML) e da linguagem [Python] (funções, classes, dicionários, módulos). Um curso anterior do autor deste, Introdução à linguagem Python e ao framework web Flask por meio de exemplos (2020), apresenta a própria linguagem [Python], para quem precisar aprendê-la primeiro.
1.1. O papel do Flask em uma aplicação web
Uma aplicação web costuma ser construída em camadas, e cada camada se comunica apenas com as camadas vizinhas:

- a camada web recebe as requisições HTTP do navegador e devolve a ele páginas HTML. É a camada que o [Flask] nos ajuda a escrever;
- 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 igualmente atender 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 [SQLAlchemy], um ORM ([Object Relational Mapper]) que mapeia as linhas das tabelas para objetos [Python].
A própria camada web segue o modelo [MVC] ([Model – View – Controller]):
- o controller (C) é um conjunto de funções [Python], chamadas de actions, cada uma das quais trata um tipo de requisição (por exemplo, [GET /schedule]). Uma action lê os parâmetros da requisição, invoca a camada de negócio e depois escolhe a view a exibir;
- o modelo (M) é o conjunto de dados que a action transmite à view;
- a view (V) é um arquivo [Jinja2] (extensão [.html]): uma página HTML que contém expressões [{{ ... }}] e instruções [{% ... %}] ([{% if %}], [{% for %}]...), que a engine [Jinja2] substitui por dados do modelo.
Uma observação sobre a terminologia, para evitar confusão: a documentação do [Flask] refere-se à função que trata uma requisição como uma “view function” e ao arquivo [Jinja2] como “template”. Este documento usa a terminologia do modelo [MVC], bem como a dos cursos [Spring MVC] e [ASP.NET Core MVC] : a função que trata uma requisição é uma action, o arquivo [Jinja2] que gera a página é uma view, e o termo “template” designa a view comum da qual as outras páginas herdam (Capítulo 4).
O tratamento de uma requisição segue as etapas numeradas do diagrama:
- 1: O navegador envia uma requisição HTTP, como [GET /schedule?doctorId=1&day=2026-09-26];
- 2: O servidor web recebe a requisição e a repassa à aplicação [Flask]. Durante o desenvolvimento, esse servidor é o [Werkzeug], a biblioteca sobre a qual o [Flask] é construído; em produção, será um servidor como o [Waitress] ou o [Gunicorn]. [Werkzeug] compara o caminho solicitado com as rotas da aplicação e seleciona a action responsável por tratar essa requisição: é o roteamento. Antes de chegar à action, a requisição ainda pode passar por funções executadas para todas as requisições ([before_request]), que exploraremos nos capítulos seguintes;
- 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] por meio de SQL;
- 4: A action constrói o modelo M da view e instrui a engine [Jinja2] a gerar a página (função [render_template]);
- 5: A página HTML gerada pela view é a resposta da action, que o [Flask] devolve ao navegador.
O [Flask] é um dos dois frameworks web mais usados no mundo [Python], junto com o [Django]. Livre e de código aberto, funciona em qualquer lugar em que o [Python] funcione ([Windows], [Linux], [macOS]). É um microframework: seu núcleo é intencionalmente pequeno (roteamento, requisições e respostas, sessões, views [Jinja2]), e todo o resto (validação de formulários, acesso a banco de dados, autenticação etc.) fica a cargo de bibliotecas escolhidas pelo desenvolvedor. Enquanto o [Spring Boot] configura sozinho um conjunto coerente de componentes, [Flask] deixa que o desenvolvedor monte os seus: a aplicação fica mais transparente, e é possível ver tudo o que acontece dentro dela. É justamente isso que o torna uma boa ferramenta de aprendizado: quase nada fica escondido. [Flask] pode criar servidores que devolvem JSON a um cliente [JavaScript] ([Angular], [React], [Flutter]...) assim como aplicações web tradicionais, em que o servidor gera as páginas HTML e o navegador apenas as exibe. Este documento examina esse segundo caso de uso. Dois conceitos de [Python] aparecem em todas as páginas: os decoradores ([@app.get("/")], [@app.before_request]...), que associam uma função a um papel, e a passagem explícita dos objetos de que cada função precisa, ao passo que o [Spring] os injeta automaticamente.
1.2. Ferramentas utilizadas
Os exemplos foram escritos e testados com as ferramentas a seguir (sua instalação é descrita no apêndice):
- [Python] 3.13 (qualquer versão 3.12 ou posterior serve). O instalador do [Python] também fornece a ferramenta [pip], que baixa e instala as bibliotecas, e o módulo [venv], que cria ambientes virtuais (veremos mais adiante o que são);
- o editor [Visual Studio Code], com a extensão [Python] da Microsoft (que também instala a extensão [Pylance], que analisa o código);
- 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 [JDK], que não contém o [Spring], o [Python] vem com uma biblioteca padrão muito completa; mas o [Flask] e as demais bibliotecas do documento não estão incluídos: o [pip] os baixa do repositório [PyPI] ([Python Package Index]) durante a instalação (portanto, é preciso estar conectado à Internet nesse dia). Cada projeto descreve suas bibliotecas em um arquivo [requirements.txt]. A tabela a seguir as lista, com as versões utilizadas:
Biblioteca | Papel | Versão |
[Flask] | o framework web: roteamento, requisições, respostas, sessões, views; inclui o [Werkzeug] (requisições HTTP, servidor de desenvolvimento), o [Jinja2] (views) e o [itsdangerous] (assinaturas) | 3.1.3 |
[asgiref] | actions assíncronas ([async def]), instalado por [Flask[async]] (exemplo 03) | 3.12.1 |
[Pydantic] | Binding e validação dos parâmetros das actions (Capítulo 3) | 2.13.5 |
[email-validator] | Validação de endereços de e-mail, para o [Pydantic] e o [WTForms] | 2.3.0 |
[Flask-WTF] | os formulários HTML ([WTForms]) e a proteção anti-CSRF (Capítulo 4) | 1.3.0 |
[Babel] | Formatação de datas e valores de acordo com o idioma (Capítulos 3 e 4) | 2.18.0 |
[PyJWT] | Tokens JWT (Capítulo 8) | 2.15.0 |
[bcrypt] | Hashes de senhas (Capítulo 8) | 5.0.0 |
[SQLAlchemy] | ORM, acesso ao banco de dados (Capítulo 9) | 2.1.1 |
[PyMySQL] | O driver [MySQL], escrito em [Python] (Capítulo 9) | 1.2.3 |
[Waitress] | Um servidor web de produção (estudo de caso) | 3.0.2 |
1.3. Executar o estudo de caso
Nota do revisor: aconselho o leitor a executar imediatamente o estudo de caso, conforme descrito a seguir. Depois de compreender bem o papel dessa aplicação 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 é simples, pois envolve uma mudança 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 por Claude. Ele já havia produzido os cursos perfeitos de [NestJS], [ASP.NET Core MVC] e [Spring 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 entendeu.
Fim da nota.
O estudo de caso ao final deste documento é uma aplicação completa. Provavelmente o leitor vai querer vê-la em funcionamento antes de mergulhar nos detalhes do framework: veja como executá-la. Ela fica na pasta [rdvmedecins2-flask], ao lado da pasta [examples]:
É preciso ter instalado o [Python] (versão 3.12 ou posterior), o [Visual Studio Code] e o [MySQL] (veja os apêndices). Em seguida:
- Crie o banco de dados [dbrdvmedecins2] executando o script [rdvmedecins2-flask/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-flask]:
- Abra a pasta [rdvmedecins2-flask] no [Visual Studio Code] (menu File / Open Folder) e depois abra um terminal (menu Terminal / New Terminal);
- crie o ambiente virtual da aplicação e ative-o. Um ambiente virtual é uma pasta (aqui, [.venv]) que contém uma cópia do interpretador [Python] e as bibliotecas de um projeto específico — e somente essas bibliotecas: cada projeto tem as suas, nas versões que lhe convêm, sem interferir nos demais projetos do computador. No [Windows] (prompt de comando ou terminal do [Visual Studio Code]):
e no [Linux] e no [macOS]:
- Com o ambiente ativado, o prompt do terminal começa com [(.venv)], e os comandos [python] e [pip] são os do ambiente. No [Windows], o terminal [PowerShell] às vezes se recusa a executar o script de ativação (mensagem: “Script execution is disabled on this system”): o comando [Set-ExecutionPolicy -Scope CurrentUser RemoteSigned], digitado uma única vez, resolve o problema. [Visual Studio Code] detecta o ambiente e se oferece para usá-lo no projeto: aceite (também é possível selecioná-lo com o comando Python: Select Interpreter, Ctrl-Shift-P); os terminais abertos depois o ativam automaticamente;
- Instale as bibliotecas da aplicação no ambiente virtual:
- 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 [config.py] da aplicação, na linha [DB_PASSWORD = ""] (por exemplo, [DB_PASSWORD = "myPassword"]). Para evitar gravar uma senha em um arquivo do projeto, também é possível informá-la na variável de ambiente [FLASK_DB_PASSWORD], que tem precedência sobre o arquivo: [set FLASK_DB_PASSWORD=myPassword] no [Windows] (prompt de comando), [$env:FLASK_DB_PASSWORD="myPassword"] no [PowerShell], [export FLASK_DB_PASSWORD=myPassword] no [Linux] e no [macOS];
- inicie a aplicação (no [Linux] e no [macOS], [python3] se [python] não existir):
- A aplicação lê o banco de dados e depois inicia o servidor de desenvolvimento do [Flask]. O console exibe os comandos SQL enviados ao banco de dados (mantivemos aqui apenas os principais), seguidos das mensagens do servidor:
Cada linha do [SQLAlchemy] começa com a data e a hora (substituídas aqui por [...]). Ela mostra que a aplicação leu a lista de médicos e de clientes (as duas requisições SQL), que o servidor está escutando na porta 8081, no endereço [127.0.0.1] (ou seja, [localhost]), e que está executando em modo debug: a aplicação é reiniciada automaticamente sempre que um arquivo [Python] é modificado ([Restarting with stat]: o processo que monitora os arquivos reinicia a aplicação, que lê o banco de dados novamente), e um erro inesperado exibe uma página de depuração (o “PIN” protege essa página no console). O aviso lembra que esse servidor se destina ao desenvolvimento, não à produção (o estudo de caso explica como usar um servidor de produção);
- Abra a URL [http://localhost:8081] em um navegador:

- Faça login com uma das contas de demonstração, cada uma das quais usa o nome de usuário como senha: [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.
Na inicialização, a aplicação lê o banco de dados: se o [MySQL] estiver inacessível, ela é encerrada imediatamente, e o console exibe o motivo no final de uma longa mensagem de erro (antes da linha “Background on this error”). Se a mensagem for [Can't connect to MySQL server on 'localhost' ([Errno 111] Connection refused)] (ou [[WinError 10061]] no [Windows]), 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'], que o script SQL não foi executado; com [ModuleNotFoundError: No module named 'flask'], que o ambiente virtual não está ativado (ou que as bibliotecas não foram instaladas nele); com [Address already in use] (ou [Port 8081 is in use by another program]), que a porta 8081 já está em uso (pela versão [Spring MVC] da aplicação, por exemplo). O arquivo [README.md] da aplicação descreve outros cenários. Pare a aplicação com [Ctrl-C] no terminal.
O estudo de caso ao final do documento mostra como usar a aplicação e depois explica cada um de seus arquivos.
1.4. Exemplos
Os exemplos ficam na pasta [examples], com uma subpasta por exemplo:
Cada exemplo é uma pequena aplicação ([Flask]) que funciona por conta própria. Todos os exemplos usam as mesmas bibliotecas, descritas no arquivo [examples/requirements.txt]:
- linha 3: [Flask], e o necessário para escrever actions assíncronas (o extra [[async]], que adiciona a biblioteca [asgiref]; veja o exemplo 03);
- linhas 4 a 7: formulários, validação e formatação de acordo com o idioma;
- linhas 8 e 9: autenticação (Capítulo 8);
- linhas 10 e 11: acesso ao banco de dados (Capítulo 9). O extra [[rsa]] do [PyMySQL] adiciona a biblioteca [cryptography], necessária para se conectar a um servidor [MySQL] 8 com uma conta protegida por senha.
Cada linha tem a forma [name==version]: o operador [==] exige exatamente essa versão, aquela com a qual os exemplos foram testados. Seria possível ser menos rígido ([Flask>=3.1]: versão 3.1 ou posterior); no entanto, uma versão futura de uma biblioteca pode mudar seu comportamento, e um curso deve ser reproduzível exatamente como foi escrito. As linhas que começam com [#] são comentários.
Para executar os exemplos, crie primeiro, uma vez por todas, o ambiente virtual dos exemplos na pasta [examples] (veja os detalhes no estudo de caso):
([source .venv/bin/activate] no [Linux] e no [macOS]). 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).
Quase todos os exemplos têm a mesma estrutura. Por exemplo, a do Exemplo 13:
- [app.py]: o arquivo de inicialização da aplicação, que é o executado; ele constrói a aplicação e inicia o servidor (veja o Exemplo 01);
- [controllers]: os controllers, isto é, os arquivos que contêm as actions. É um pacote [Python]: uma pasta que contém módulos (arquivos [.py]), que podem ser importados ([from controllers.views import views]). O arquivo [__init__.py], que aqui está vazio, transforma a pasta em um pacote (ele é executado na primeira importação do pacote);
- [models]: as classes que descrevem os modelos (das actions e das views);
- [templates]: as views [Jinja2] (a partir do Capítulo 4). [Flask] as procura nessa pasta, ao lado do arquivo da aplicação;
- [static] (a partir do Exemplo 15): arquivos enviados como estão ao navegador (folhas de estilo, imagens, scripts [JavaScript]).
Para executar um exemplo, abra um terminal em sua pasta (no [Visual Studio Code]: clique com o botão direito na pasta do exemplo e selecione “Open in Integrated Terminal”), e ative o ambiente virtual dos exemplos, se ainda não estiver ativo ([..\.venv\Scripts\activate] no [Windows], [source ../.venv/bin/activate] no [Linux] e no [macOS]: o ambiente fica na pasta [examples], que é a pasta pai da pasta do exemplo), e digite:
Todos os exemplos escutam na porta 5000: só é possível executar um de cada vez. Pare o servidor digitando [Ctrl-C] no terminal. No [macOS], a porta 5000 às vezes já está ocupada pelo “AirPlay Receiver” do sistema (mensagem [Address already in use]): é possível desativá-lo em System Settings / General / AirDrop and Handoff, ou alterar a porta no arquivo [app.py] do exemplo ([port=5001]).
Quando você abre a pasta [examples] no [Visual Studio Code], a extensão [Python] sugere usar o ambiente [.venv]: isso permite aproveitar o realce de sintaxe, o autocompletar e a indicação de erros em cada arquivo. Cada exemplo é iniciado a partir de sua própria pasta; por isso as importações de um exemplo ([from controllers.views import views]) partem dessa pasta. [Pylance], que analisa o código a partir da pasta aberta ([examples]), pode então sublinhar essas importações, indicando que não foram encontradas: isso não tem efeito na execução. Para que o [Pylance] as encontre, basta abrir a própria pasta do exemplo (menu File / Open Folder). Por fim, todos os exemplos são executados em modo debug (veja o Exemplo 01): uma aplicação em execução é reiniciada automaticamente, em cerca de um segundo, assim que um de seus arquivos [Python] é modificado e salvo.
Os exemplos que usam o [Bootstrap] o encontram na pasta [common/bootstrap], e não na própria pasta: isso garante que exista uma única cópia do arquivo. Cada um desses exemplos o chama pela URL [/bootstrap/...], por meio de algumas linhas em seu arquivo [app.py]. Por exemplo, [15-layout/app.py]:
- Linha 11: o caminho da pasta [common/bootstrap]. [__file__] é o caminho do arquivo em execução ([app.py]); [Path(...).resolve()] o transforma em um caminho absoluto; [.parent] designa a pasta que o contém ([15-layout]), e [.parent.parent] designa a pasta pai ([examples]). O operador [/] de um objeto [Path] acrescenta um elemento ao caminho, usando o separador correto ([\] no [Windows], [/] nos demais). O caminho, portanto, não depende da pasta atual: o exemplo encontra o [Bootstrap] de onde quer que seja iniciado;
- linhas 20 e 21: um blueprint é um grupo de rotas registrado na aplicação (veja o Exemplo 02). Esse blueprint não tem rotas: serve apenas para publicar a pasta [common/bootstrap] (parâmetro [static_folder]) na URL [/bootstrap] (parâmetro [static_url_path]). Uma página pode então usar a folha de estilo [/bootstrap/css/bootstrap.min.css].
As demais linhas desse arquivo serão explicadas no Exemplo 15.
1.5. Conteúdo do documento
O documento está estruturado da seguinte forma:
Capítulo | Conteúdo | Exemplos |
Actions, roteamento, respostas | Da requisição à action: rotas, blueprints, respostas, redirecionamentos, serviços compartilhados | 01 a 06 |
O modelo da action | Parâmetros da requisição: binding, conversão, validação com [Pydantic], formulários POST | 07 a 12 |
A view e seu template | [Jinja2], template, macros, formulários [WTForms], validação, PRG, proteção anti-CSRF | 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 | middleware WSGI, [before_request], [after_request], [teardown_request], conversores, tratadores de erros | 24 |
Autenticação e autorização | JWT em um cookie, decoradores, papéis, CAPTCHA, limite de tentativas | 25–27 |
Arquitetura em camadas | Web / negócio / DAO com [SQLAlchemy] 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, utiliza 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: [Python], [Visual Studio Code] e sua extensão [Python], [MySQL] com o [Laragon] e o [curl].