Skip to content

2. Actions, roteamento, respostas

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

2.1. Exemplo 01: a estrutura de uma aplicação Flask

O primeiro exemplo é a menor aplicação [Flask] possível: um único arquivo.

01-structure/
└── app.py

2.1.1. O arquivo app.py

# app.py: a menor aplicação Flask possível
from flask import Flask

# a aplicação: um objeto da classe Flask. __name__ (aqui "__main__" ou "app")
# informa ao Flask onde a aplicação está, para que ele procure seus arquivos ali
app = Flask(__name__)


# uma ação (o Flask diz uma "view"): a função chamada para a requisição GET /
@app.get("/")
def index():
    # o valor retornado pela função É a resposta enviada ao navegador
    return "Hello from Flask!"


# executado somente quando o próprio arquivo é executado: python app.py
if __name__ == "__main__":
    # o servidor de desenvolvimento: http://localhost:5000; Ctrl-C o interrompe.
    # debug=True: recarregamento automático após uma modificação, e uma página
    # de depuração em caso de erro (NUNCA em produção)
    app.run(port=5000, debug=True)

Vamos analisar este código:

  • linha 2: importa a classe [Flask] do pacote [flask], instalado no ambiente virtual pelo [pip]. Em [Python], um arquivo com extensão [.py] é um módulo, e um módulo só usa os nomes que importou ou definiu por conta própria (exceto as funções nativas da linguagem, como [print] ou [len]);
  • linha 6: a aplicação, um objeto da classe [Flask]. Ela recebe as requisições e seleciona a função que trata cada uma. O parâmetro é o nome do módulo atual, que o [Python] guarda na variável [__name__]: o [Flask] o usa para localizar a pasta da aplicação, onde procurará mais adiante as views (pasta [templates]) e os arquivos estáticos (pasta [static]);
  • linha 10: [@app.get("/")] é um decorador. Um decorador é escrito como [@expression], imediatamente antes da definição de uma função (ou de uma classe); o [Python] chama a expressão com a função como parâmetro ao executar a definição. Aqui, [app.get("/")] registra a função [index] na aplicação: ela tratará as requisições [GET /]. Isso é o roteamento. Uma função associada dessa forma a uma rota é uma action (a documentação do [Flask] a chama de view function; veja a introdução);
  • linhas 11 a 13: a action devolve uma string. O valor devolvido por uma action é a resposta enviada ao navegador: o [Flask] a coloca no corpo da resposta HTTP. Por convenção, os nomes de funções ([Python]) são escritos em minúsculas, com as palavras separadas por sublinhados ([action01_post]);
  • linha 17: quando o próprio arquivo é executado ([python app.py]), o [Python] atribui o valor ["__main__"] à variável [__name__]; quando o módulo é importado por outro módulo, ela recebe o nome do módulo (["app"]). Esse teste, muito comum em [Python], reserva portanto o restante do código para quando o arquivo é iniciado diretamente;
  • linha 21: [app.run] inicia o [Werkzeug] servidor de desenvolvimento, que escuta as requisições na porta 5000 da máquina (5000 é o valor padrão) até ser interrompido por [Ctrl-C]. [debug=True] ativa o modo debug: o servidor monitora os arquivos da aplicação e a reinicia assim que um deles é modificado; uma exceção não tratada exibe uma página de depuração (veja o Exemplo 03). Esse modo se destina ao desenvolvimento, e somente a ele: a página de depuração permite executar código [Python] no servidor.

2.1.2. Execução

Em uma janela de terminal aberta na pasta [01-structure], com o ambiente virtual dos exemplos ativado, digite [python app.py]. O [Flask] exibe suas mensagens de inicialização:

1
2
3
4
5
6
7
8
 * Serving Flask app 'app'
 * Debug mode: on
WARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.
 * Running on http://127.0.0.1:5000
Press CTRL+C to quit
 * Restarting with stat
 * Debugger is active!
 * Debugger PIN: 332-612-699

As mensagens mostram o nome da aplicação, o modo debug, o endereço de escuta e a porta. [127.0.0.1] é o endereço da própria máquina ([localhost]): o servidor só aceita requisições dessa máquina, o que é adequado para o desenvolvimento ([app.run(host="0.0.0.0")] o abriria para as outras máquinas da rede). A linha [Restarting with stat] indica o mecanismo de recarga automática: o processo iniciado por [python app.py] apenas monitora os arquivos; ele inicia a aplicação em um processo separado, que reinicia a cada alteração. O “PIN” protege o console [Python] da página de depuração.

Há uma segunda maneira de iniciar uma aplicação: o comando [flask], instalado junto com o [Flask] no ambiente virtual:

flask --app app run --debug

A opção [--app] indica o módulo da aplicação ([app], isto é, o arquivo [app.py]), [run] inicia o servidor de desenvolvimento e [--debug] ativa o modo debug; [--port 5001] mudaria a porta. O próprio comando localiza, dentro do módulo, o objeto [Flask] chamado [app] (ou, como veremos no Exemplo 02, uma função chamada [create_app]). Com isso, o teste [if __name__ == "__main__"] deixa de ser necessário. Os exemplos usam [python app.py], que é mais fácil de lembrar; o estudo de caso fará o mesmo.

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

curl -i http://localhost:5000/
1
2
3
4
5
6
7
8
HTTP/1.1 200 OK
Server: Werkzeug/3.1.8 Python/3.13.7
Date: Sat, 26 Sep 2026 13:22:44 GMT
Content-Type: text/html; charset=utf-8
Content-Length: 17
Connection: close

Hello from Flask!

A primeira linha da resposta contém a versão do protocolo, o código de status (200) e seu rótulo ([OK]). Em seguida vêm os cabeçalhos: o nome do servidor, a data, o tipo do conteúdo, o tamanho do conteúdo em bytes e [Connection: close] (o servidor de desenvolvimento fecha a conexão após cada resposta). Uma linha em branco separa os cabeçalhos do corpo da resposta. No restante deste documento, não incluiremos mais os cabeçalhos [Server], [Date] e [Connection], pois eles não mudam.

O cabeçalho [Content-Type: text/html; charset=utf-8] indica que a resposta está no formato HTML, cujos caracteres são codificados em UTF-8. Essa é a codificação padrão ([Flask]) para qualquer string devolvida por uma action: o navegador, portanto, interpreta a string como HTML (aqui, sem nenhuma tag, ela é exibida como está). O Exemplo 03 mostrará como especificar outro tipo de conteúdo.

A cada requisição, o console do servidor exibe uma linha de log: o endereço do cliente, a data, a requisição e o código da resposta.

127.0.0.1 - - [26/Sep/2026 15:22:44] "GET / HTTP/1.1" 200 -

2.2. Exemplo 02: roteamento

O roteamento associa uma URL e um método (HTTP, GET, POST...) a uma action. O Exemplo 02 organiza essas actions em dois arquivos:

1
2
3
4
5
6
02-routing/
├── controllers/
│   ├── __init__.py
│   ├── first.py
│   └── home.py
└── app.py

A pasta [controllers] é um pacote [Python] (veja a introdução). Cada um desses dois módulos define um blueprint: um grupo de rotas, que a aplicação então registra. É o equivalente, no [Flask], das classes controller do [Spring MVC] ou do [ASP.NET Core MVC].

2.2.1. A aplicação: app.py

# app.py: a aplicação, construída por uma "factory"
from flask import Flask

from controllers.home import home
from controllers.first import first


# a factory: uma função que constrói e configura a aplicação
def create_app():
    app = Flask(__name__)
    # cada blueprint (um grupo de rotas) é registrado na aplicação
    app.register_blueprint(home)
    app.register_blueprint(first)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linhas 4 e 5: importam os dois blueprints, os objetos [home] e [first], dos módulos [controllers/home.py] e [controllers/first.py];
  • Linhas 9 a 14: a aplicação deixa de ser uma variável do módulo criada na importação; ela é construída por uma função chamada de *factory*. Essa é a abordagem recomendada pela documentação do [Flask], que todos os exemplos seguintes adotarão: a configuração da aplicação fica concentrada em um único lugar, e é possível criar várias aplicações com configurações diferentes (para testes, por exemplo). O comando [flask --app app run] reconhece essa abordagem: na ausência de uma variável [app], ele chama a função [create_app] do módulo;
  • linhas 12 e 13: cada blueprint é registrado na aplicação; suas rotas passam a ser as da aplicação;
  • linha 18: a aplicação é construída e, em seguida, o servidor é iniciado.

2.2.2. O blueprint "home": controllers/home.py

# controllers/home.py: a página inicial
from flask import Blueprint

# um blueprint: um conjunto de rotas, depois registrado na aplicação.
# "home": seu nome; __name__: o módulo onde ele é definido
home = Blueprint("home", __name__)


# GET /: uma página HTML que contém links para as outras ações.
# Uma string retornada por uma ação é enviada com o tipo text/html
@home.get("/")
def 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 6: o blueprint. Seu primeiro parâmetro é seu nome, [home]: ele servirá para identificar suas actions ([home.index], veja o Exemplo 04). O segundo parâmetro, como no caso da aplicação, é o nome do módulo;
  • linha 11: um blueprint tem os mesmos decoradores que a aplicação: a action [index] trata [GET /];
  • linhas 13 a 23: uma string delimitada por aspas triplas pode se estender por várias linhas e conter aspas. A action devolve HTML, enviado com o tipo [text/html] (veja o Exemplo 01).

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

Image

2.2.3. O primeiro blueprint: controllers/first.py

# controllers/first.py: um blueprint cujas rotas começam todas com /first
from flask import Blueprint

# url_prefix: prefixo compartilhado por todas as rotas do blueprint
first = Blueprint("first", __name__, url_prefix="/first")


# GET /first: a rota "" designa o próprio prefixo
@first.get("")
def index():
    return "Action [index] of the [first] blueprint"


# GET /first/action01
@first.get("/action01")
def action01():
    return "Action [action01] of the [first] blueprint, GET request"


# POST /first/action01: mesmo caminho, outro método HTTP, outra função
@first.post("/action01")
def action01_post():
    return "Action [action01_post] of the [first] blueprint, POST request"


# GET /first/products/17: <int:id> é uma variável de caminho;
# o conversor [int] aceita apenas dígitos, e fornece um inteiro
@first.get("/products/<int:id>")
def product(id):
    return f"Product no. {id}"


# GET /first/products/17/reviews/3: duas variáveis de caminho
@first.get("/products/<int:id>/reviews/<int:number>")
def review(id, number):
    return f"Review no. {number} of product no. {id}"


# GET /first/files/...: o conversor [path] aceita qualquer final de
# caminho, barras incluídas
@first.get("/files/<path:path>")
def file(path):
    return f"Requested file: {path}"

Vamos analisar este código:

  • linha 5: o parâmetro [url_prefix] define o prefixo comum a todas as rotas do blueprint: suas actions tratam as rotas de URL que começam por [/first];
  • linhas 9 e 10: a rota [""] designa o próprio prefixo: a action [index] trata [GET /first]. A URL de uma action é a concatenação do prefixo do blueprint com o caminho de sua rota. O nome da action ([index]) pode ser o mesmo de outro blueprint: o [Flask] as distingue pelo nome do blueprint ([first.index], [home.index]);
  • linhas 15 e 16: a action [action01] trata [GET /first/action01];
  • linhas 21 e 22: o mesmo caminho, mas para o método POST: o decorador [post] substitui [get]. Também existem [put], [delete] e [patch], além do decorador geral [route], que aceita uma lista de métodos: [@first.route("/action01", methods=["GET", "POST"])]. Dentro de um mesmo módulo, duas funções não podem ter o mesmo nome (a segunda substituiria a primeira): daí o nome [action01_post];
  • linhas 28 a 30: [<int:id>] é uma variável de caminho: esse segmento da URL pode assumir vários valores. [int] é um conversor: o segmento deve ser formado por dígitos; caso contrário, a rota não corresponde; seu valor é convertido em inteiro e depois passado ao parâmetro de mesmo nome da action, [id]. Para [/first/products/17], [id] é igual ao número 17. Isso é o binding de dados (*data binding*), que o próximo capítulo examinará em detalhe. Sem conversor ([<id>]), a variável aceita qualquer texto sem barra e continua sendo uma string. [Werkzeug] também fornece os conversores [float], [uuid] e [path], e o Exemplo 12 mostrará como escrever o seu próprio;
  • linha 30: uma f-string (o prefixo [f]): cada expressão entre chaves é avaliada, e seu valor é inserido no texto;
  • linhas 34 a 36: duas variáveis de caminho, passadas como dois parâmetros da action;
  • linhas 41 a 43: o conversor [path] aceita qualquer final de URL, inclusive [/].

2.2.4. Execução

Aqui estão as respostas a algumas requisições:

curl -i http://localhost:5000/first
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 39

Action [index] of the [first] blueprint
curl -i http://localhost:5000/first/products/17/reviews/3
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 30

Review no. 3 of product no. 17

O texto tem 30 caracteres, e a resposta também tem 30 bytes: em UTF-8, cada um desses caracteres (ASCII) ocupa um byte.

curl -i http://localhost:5000/first/files/images/logo.png
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Content-Length: 31

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 OK
Content-Type: text/html; charset=utf-8
Content-Length: 61

Action [action01_post] of the [first] blueprint, POST request

Um método HTTP que nenhuma action trata para esse caminho resulta em um erro 405 ([Method Not Allowed]). O cabeçalho [Allow] lista os métodos aceitos; o [Flask] acrescenta [HEAD] (a mesma requisição que GET, sem o corpo da resposta) e [OPTIONS] (a lista dos métodos aceitos), que ele mesmo trata para toda rota GET:

curl -i -X PUT http://localhost:5000/first/action01
HTTP/1.1 405 METHOD NOT ALLOWED
Content-Type: text/html; charset=utf-8
Allow: HEAD, OPTIONS, POST, GET
Content-Length: 153

<!doctype html>
<html lang=en>
<title>405 Method Not Allowed</title>
<h1>Method Not Allowed</h1>
<p>The method is not allowed for the requested URL.</p>

Por fim, uma URL que nenhuma rota trata resulta em um erro 404. É o que acontece também com um identificador que não é um inteiro: nenhuma rota corresponde a [/first/products/abc].

curl -i http://localhost:5000/first/products/abc
1
2
3
4
5
6
7
8
9
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 207

<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>The requested URL was not found on the server. If you entered the URL manually please check your spelling and try again.</p>

As respostas de erro do [Flask] (na verdade, do [Werkzeug]) são pequenas páginas HTML, em inglês. Em um navegador:

Image

O Capítulo 7 mostrará como substituí-las por páginas próprias da aplicação. Observe também que o [Flask] distingue [/first] de [/first/]: esta última URL também produz um erro 404, pois nenhuma rota termina com uma barra. Inversamente, uma rota declarada com uma barra final ([@first.get("/list/")]) também aceita a URL sem a barra, por meio de um redirecionamento.

O comando [flask routes], executado na pasta do exemplo, lista todas as rotas da aplicação:

flask --app app routes
Endpoint             Methods  Rule
-------------------  -------  ---------------------------------------------
first.action01       GET      /first/action01
first.action01_post  POST     /first/action01
first.file           GET      /first/files/<path:path>
first.index          GET      /first
first.product        GET      /first/products/<int:id>
first.review         GET      /first/products/<int:id>/reviews/<int:number>
home.index           GET      /
static               GET      /static/<path:filename>

A coluna [Endpoint] lista o nome de cada rota: o nome do blueprint, um ponto e o nome da função. A última rota, [static], é criada pelo próprio [Flask] : ela serve os arquivos da pasta [static] da aplicação (veja o Exemplo 15).

2.3. Exemplo 03: respostas de uma action

O que uma action devolve determina a resposta HTTP. O Exemplo 03 passa em revista os principais casos. O arquivo [app.py]:

# app.py: a aplicação do exemplo 03
from flask import Flask

from controllers.responses import responses


def create_app():
    app = Flask(__name__)
    # o JSON produzido mantém os caracteres acentuados como estão ("é" e não
    # "é"), e as chaves em sua ordem original (sem ordenação)
    app.json.ensure_ascii = False
    app.json.sort_keys = False
    app.register_blueprint(responses)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linhas 11 e 12: dois ajustes do provedor JSON ([app.json]) da aplicação, o objeto que converte objetos [Python] em JSON. Por padrão, ele escreve os caracteres não ASCII como sequências de escape ([é] vira [\u00e9], o que é JSON válido, mas pouco legível) e ordena as chaves dos dicionários em ordem alfabética. Mantemos os caracteres como estão e as chaves na ordem em que a action as escreveu.

O arquivo [controllers/responses.py]:

# controllers/responses.py: as diferentes respostas de uma ação
import asyncio
import time
from dataclasses import dataclass

from flask import Blueprint, Response, abort, jsonify

responses = Blueprint("responses", __name__, url_prefix="/responses")


# uma string, anunciada como texto simples: o navegador a exibe como está.
# Response: a resposta completa, construída pela própria ação
@responses.get("/text")
def text():
    return Response("<h1>Action [text]</h1>", mimetype="text/plain")


# uma string sozinha: o Flask a envia com o tipo text/html; o navegador a interpreta
@responses.get("/html")
def html():
    return "<h1>Action [html]</h1>"


# uma dataclass: uma classe de dados (veja o exemplo 06), declarada aqui no módulo
@dataclass
class Person:
    last_name: str
    first_name: str
    age: int


# um objeto: jsonify o serializa em JSON, com o tipo [application/json]
@responses.get("/json")
def json():
    return jsonify(Person("Martin", "Jean", 42))


# um dicionário retornado como está: o próprio Flask o serializa em JSON
@responses.get("/dictionary")
def dictionary():
    return {"last_name": "Martin", "first_name": "Jean", "age": 42}


# uma lista: serializada como um array JSON
@responses.get("/list")
def list():
    return ["Mme", "Melle", "Mr"]


# uma tupla (conteúdo, código): o código 201 (Created) em vez de 200 (OK)
@responses.get("/created")
def created():
    return {"message": "resource created"}, 201


# sem resposta: o código 204 (No Content) significa "nada a exibir"
@responses.get("/empty")
def empty():
    return "", 204


# uma ação assíncrona (async def): o Flask espera o fim da corrotina.
# Ela precisa do extra [async] do Flask: pip install "flask[async]"
@responses.get("/task")
async def task():
    start = time.perf_counter()
    await asyncio.sleep(0.5)  # uma espera de 500 ms, sem bloquear o event loop
    return {"wait": f"{round((time.perf_counter() - start) * 1000)} ms"}


# um erro "esperado": a tupla (conteúdo, 404) produz uma resposta 404
@responses.get("/not-found")
def not_found():
    return {"message": "This resource does not exist"}, 404


# o mesmo, com abort: uma exceção HTTP, que o Flask transforma em uma resposta 404
@responses.get("/abort")
def abort_action():
    abort(404, "This resource does not exist either")


# um erro "inesperado": uma exceção não tratada produz uma resposta 500
@responses.get("/exception")
def exception():
    raise RuntimeError("An unexpected error")

Vamos comentar este código:

  • Linhas 13 a 15: a classe [Response] representa uma resposta HTTP completa. A action a constrói por conta própria: o corpo e o tipo ([mimetype]), neste caso [text/plain] (texto simples). O navegador não interpretará as tags;
  • linhas 19 a 21: a mesma string, devolvida diretamente: o [Flask] a envia com o tipo [text/html], e o navegador a interpreta;
  • linhas 25 a 29: uma dataclass, ou seja, uma classe em que apenas os campos e seus tipos são declarados; o decorador [@dataclass] escreve o construtor ([Person("Martin", "Jean", 42)]), a representação textual e a comparação de objetos. O Exemplo 06 voltará a esse assunto;
  • linhas 33 a 35: a função [jsonify] converte seu parâmetro em JSON e gera uma resposta do tipo [application/json]. O provedor JSON do [Flask] sabe converter dicionários, listas, strings, números, booleanos, [None] (que vira [null]), além de dataclasses, datas e números [Decimal] (veja o exemplo 06);
  • linhas 39 a 41: ainda mais simples: uma action que devolve um dicionário (ou uma lista, linhas 45 a 47) produz uma resposta JSON, sem chamar [jsonify]. Uma dataclass, por outro lado, precisa passar por [jsonify]: se fosse devolvida diretamente, causaria um erro (“The view function did not return a valid response”);
  • linhas 51 a 53: uma action pode devolver uma tupla [(content, code)]: o código de status 201 ([Created]) substitui o código de status 200. Uma tupla também pode conter cabeçalhos: [(content, code, {"X-Example": "03"})];
  • linhas 57 a 59: o código 204 ([No Content]) significa “nada a exibir”: a resposta não tem corpo;
  • linhas 64 a 68: uma action assíncrona, declarada com [async def]. A palavra-chave [await] suspende a corrotina durante a espera ([asyncio.sleep]), sem bloquear o programa. O [Flask] executa a action em um loop de eventos criado para a requisição e aguarda seu resultado: isso é útil para disparar várias esperas em paralelo (várias chamadas a serviços web, por exemplo), mas não torna o próprio [Flask] assíncrono. É preciso instalar o extra [[async]] do [Flask] (veja [requirements.txt]);
  • linhas 72 a 74: um erro “esperado”: a tupla [(content, 404)] devolve uma resposta 404 ([Not Found]), com um corpo (JSON) escolhido pela action;
  • linhas 78 a 80: o mesmo erro, gerado pela função [abort]. [abort] não devolve nada: ela lança uma exceção ([NotFound], para o código 404), que encerra a action; o [Flask] a converte em uma resposta de erro, com a mensagem fornecida como segundo parâmetro. Essa é a forma mais comum de encerrar uma action por causa de um erro, mesmo no fundo de uma função chamada pela action;
  • linhas 84 a 86: um erro “inesperado”, isto é, uma exceção que ninguém trata, produz uma resposta 500 ([Internal Server Error]).

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

Image

Image

Aqui estão as respostas das demais actions:

curl -i http://localhost:5000/responses/json
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 65

{
  "last_name": "Martin",
  "first_name": "Jean",
  "age": 42
}

A dataclass foi convertida em um objeto JSON, com um campo por atributo. No modo debug, o JSON é exibido em várias linhas, com indentação; sem o modo debug, ele cabe em uma única linha ([{"last_name":"Martin","first_name":"Jean","age":42}]). A action [/responses/dictionary] produz exatamente o mesmo resultado.

curl -i http://localhost:5000/responses/list
1
2
3
4
5
6
7
8
9
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 31

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

{
  "message": "resource created"
}
curl -i http://localhost:5000/responses/empty
HTTP/1.1 204 NO CONTENT
Content-Type: text/html; charset=utf-8
curl -i http://localhost:5000/responses/task
1
2
3
4
5
6
7
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 23

{
  "wait": "501 ms"
}
curl -i http://localhost:5000/responses/not-found
1
2
3
4
5
6
7
HTTP/1.1 404 NOT FOUND
Content-Type: application/json
Content-Length: 48

{
  "message": "This resource does not exist"
}
curl -i http://localhost:5000/responses/abort
1
2
3
4
5
6
7
8
9
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 122

<!doctype html>
<html lang=en>
<title>404 Not Found</title>
<h1>Not Found</h1>
<p>This resource does not exist either</p>

A resposta de [abort] é a página de erro padrão do [Werkzeug], com a nossa mensagem (inserida na página após o escape: um texto inserido em HTML não pode ter a possibilidade de introduzir tags nele; voltaremos a isso).

Resta a exceção não tratada. No modo debug, o navegador exibe a página do depurador do [Werkzeug] : o tipo e a mensagem da exceção, seguidos da pilha de chamadas (a lista das funções que estavam em execução no momento do erro), da mais antiga à mais recente, com a linha de código correspondente a cada uma:

Image

A última função da pilha é a nossa action, [exception], na linha 86 do arquivo [responses.py]. Ao clicar em uma das linhas da pilha, é possível até abrir um console [Python] no contexto dessa função, depois de informar o PIN exibido na inicialização: é por isso que o modo debug nunca deve ser ativado em um servidor acessível a outras pessoas. O console do servidor também exibe a pilha de chamadas (incluímos aqui apenas o final):

1
2
3
4
5
6
127.0.0.1 - - [26/Sep/2026 15:23:10] "GET /responses/exception HTTP/1.1" 500 -
Traceback (most recent call last):
  ...
  File ".../examples/03-responses/controllers/responses.py", line 86, in exception
    raise RuntimeError("An unexpected error")
RuntimeError: An unexpected error

Sem o modo debug ([app.run(port=5000)]), a mesma requisição produz uma breve página de erro 500 em inglês, que não revela nada sobre o código (“Internal Server Error. The server encountered an internal error and was unable to complete your request...”); a pilha de chamadas é escrita apenas no console do servidor. O Capítulo 7 mostrará como exibir uma página de erro própria da aplicação.

2.4. Exemplo 04: redirecionamentos

Um redirecionamento é uma resposta que instrui o navegador a buscar outra URL: um código 3xx e o cabeçalho [Location], que contém o novo endereço. O navegador envia imediatamente uma segunda requisição a esse endereço. O arquivo [controllers/redirects.py]:

# controllers/redirects.py: os redirecionamentos
from flask import Blueprint, redirect, url_for

redirects = Blueprint("redirects", __name__)


# redirecionamento permanente (301): a página mudou de endereço definitivamente
@redirects.get("/old")
def old_page():
    return redirect("/new", code=301)


@redirects.get("/new")
def new_page():
    return "You are on the [new] page"


# redirecionamento temporário (302, o código padrão), para um endereço calculado
# concatenando pedaços de texto
@redirects.get("/go/<destination>")
def go(destination):
    return redirect("/page/" + destination)


# url_for constrói o endereço de uma AÇÃO, designada por seu nome
# ("blueprint.função"): o parâmetro [name] é codificado corretamente para uma URL
@redirects.get("/to-template/<destination>")
def to_template(destination):
    return redirect(url_for("redirects.page", name=destination))


@redirects.get("/page/<name>")
def page(name):
    return f"You are on the [{name}] page"


# redirecionamento para outro site
@redirects.get("/documentation")
def documentation():
    return redirect("https://flask.palletsprojects.com/")
  • linhas 8 a 10: a função [redirect] gera uma resposta de redirecionamento para o endereço indicado. O código de status 301 ([Moved Permanently]) indica que a página mudou de endereço permanentemente: o navegador (e os mecanismos de busca) podem guardar o novo endereço em cache;
  • linhas 20 a 22: sem o parâmetro [code], [redirect] produz um redirecionamento temporário com o código de status 302 ([Found]). O endereço é calculado concatenando pedaços de texto, o que causa um problema que examinaremos;
  • Linhas 27 a 29: a função [url_for] gera a URL de uma action, identificada por seu nome (["redirects.page"]: o blueprint, um ponto, a função), e não por seu caminho. Seus parâmetros nomeados fornecem as variáveis de caminho (aqui, [name]), corretamente codificadas para uma URL. Se um dia o caminho da rota [page] for alterado, as chamadas a [url_for] o acompanharão automaticamente;
  • linhas 38 a 40: um redirecionamento para outro site.

As respostas, com o [curl] (que, sem nenhuma opção, não segue redirecionamentos):

curl -i http://localhost:5000/old
HTTP/1.1 301 MOVED PERMANENTLY
Content-Type: text/html; charset=utf-8
Content-Length: 195
Location: /new

<!doctype html>
<html lang=en>
<title>Redirecting...</title>
<h1>Redirecting...</h1>
<p>You should be redirected automatically to the target URL: <a href="/new">/new</a>. If not, click the link.

A resposta também inclui um pequeno corpo HTML, para um cliente que não siga redirecionamentos. A opção [-L] do [curl] segue o redirecionamento, exatamente como faria um navegador:

curl -L http://localhost:5000/old
You are on the [new] page

Vamos agora comparar os dois redirecionamentos calculados, com um destino que contém um ponto de interrogação, codificado como [%3F] na URL (um [?] não codificado iniciaria os parâmetros da URL):

curl -i http://localhost:5000/go/a%3Fb
1
2
3
4
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 205
Location: /page/a?b
curl -i http://localhost:5000/to-template/a%3Fb
1
2
3
4
HTTP/1.1 302 FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 209
Location: /page/a%3Fb

O [Flask] decodificou a variável de caminho antes de tratá-la: [destination] é igual a [a?b]. A primeira action a cola como está no endereço: [/page/a?b], que o navegador interpreta como o caminho [/page/a] seguido do parâmetro [b]. A segunda passa por [url_for], que a codifica novamente: [/page/a%3Fb]. Seguindo os redirecionamentos:

curl -L http://localhost:5000/go/a%3Fb
curl -L http://localhost:5000/to-template/a%3Fb
You are on the [a] page
You are on the [a?b] page

Somente a segunda leva à página correta. Daí a regra: um endereço que contém um valor variável é gerado com [url_for], nunca por concatenação de strings. No navegador, apenas a página final é visível; a barra de endereço exibe a nova URL:

Image

Existem outros dois códigos de redirecionamento: 303 ([See Other]) e 307 ([Temporary Redirect]), que se obtêm com [redirect(url, code=303)]. Após uma requisição POST, os códigos 302 e 303 fazem o navegador enviar uma requisição GET ao novo endereço, ao passo que o 307 (e o 308, sua versão permanente) o fazem repetir a requisição POST. O Exemplo 20 usará o redirecionamento após um POST.

2.5. Exemplo 05: os objetos de requisição e de resposta

Até agora, as actions só recebiam variáveis de caminho e devolviam um valor que o [Flask] convertia em resposta. Uma action também pode acessar a requisição atual e construir ela mesma a resposta. O arquivo [controllers/http.py]:

# controllers/http.py: os objetos de requisição e de resposta
import time

from flask import Blueprint, Response, make_response, request

http = Blueprint("http", __name__, url_prefix="/http")


# a requisição: método, caminho, parâmetros, cabeçalhos...
# [request] é um objeto global do Flask, que designa a requisição ATUAL
@http.get("/request")
def request_info():
    # um dicionário Python mantém a ordem de inserção de suas chaves
    return {
        "method": request.method,
        "path": request.path,
        # query_string: bytes, que decodificamos em texto
        "parameters": request.query_string.decode(),
        "browser": request.headers.get("User-Agent"),
        "ip": request.remote_addr,
    }


# a resposta: make_response constrói o objeto de resposta a partir do que a
# ação retornaria; adicionamos um cabeçalho a ele antes de retorná-lo
@http.get("/header")
def header():
    response = make_response("Response with an added header")
    response.headers["X-Example"] = "05-request-response"
    return response


# a resposta construída "à mão": corpo, código, tipo
@http.get("/response")
def response():
    return Response("Response built by [Response(...)]", status=200,
                    mimetype="text/plain")


# uma resposta enviada EM PARTES (chunks): o código e os cabeçalhos saem com a
# primeira parte, e não podem mais mudar depois
@http.get("/stream")
def stream():
    def chunks():
        yield "Start of the response... "
        time.sleep(1)
        # tarde demais para anunciar um erro: o código 200 já foi enviado
        raise RuntimeError("error in the middle of the response")

    return Response(chunks(), mimetype="text/plain")
  • Linha 4: importação do objeto [request]. No [Flask], a requisição atual não é um parâmetro da action: é um objeto global, [request], importado do pacote [flask]. Como um objeto global pode designar a requisição atual, se o servidor trata várias requisições simultaneamente em várias threads (fluxos de execução paralelos)? [request] funciona como um proxy: a cada uso, ele repassa a operação à requisição da thread atual. O [Flask] chama isso de contexto de requisição: enquanto uma requisição está sendo tratada, [request] designa essa requisição específica. Fora do tratamento de uma requisição, usá-lo causa um erro (“Working outside of request context”);
  • linhas 14 a 20: algumas propriedades da requisição: seu método HTTP, seu caminho, seus parâmetros brutos (a parte da URL que segue o [?], em forma de bytes, que [decode] converte em texto), seus cabeçalhos ([request.headers], um dicionário, cujo método [get] devolve [None] para um cabeçalho ausente), o endereço IP do cliente. Os parâmetros, um a um, serão tratados no próximo capítulo;
  • linhas 26 a 30: a função [make_response] constrói o objeto de resposta (um [Response]) a partir do que a action devolveria (aqui, uma string); a action pode então modificá-lo antes de devolvê-lo. Um cabeçalho [X-Example] é adicionado a ele (por convenção, os cabeçalhos específicos de uma aplicação costumam começar por [X-]);
  • linhas 34 a 37: a resposta “montada à mão”: o corpo, o código de status e o tipo;
  • linhas 42 a 50: uma resposta enviada em partes (*streaming*). A função [chunks] é um gerador: cada [yield] produz uma parte do corpo. Como a resposta é construída com um gerador, seu tamanho não é conhecido de antemão: o servidor envia o código de status e os cabeçalhos e, depois, cada parte assim que ela é produzida. Isso é útil para uma resposta muito longa, gerada aos poucos. Mas, depois que a primeira parte foi enviada, o código de status não pode mais mudar: aqui, o gerador lança uma exceção após a primeira parte. É o erro a evitar: uma resposta que já começou não pode se tornar uma resposta de erro.

Respostas:

curl -i "http://localhost:5000/http/request?name=martin&age=42"
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 135

{
  "method": "GET",
  "path": "/http/request",
  "parameters": "name=martin&age=42",
  "browser": "curl/8.5.0",
  "ip": "127.0.0.1"
}

(As aspas em torno de "URL" impedem que o terminal interprete o caractere "[&]".) Em um navegador, o cabeçalho [User-Agent] é o do navegador; o [Chrome] exibe o JSON bruto, com uma caixa de seleção que o indenta:

Image

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

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

Response built by [Response(...)]
curl -i http://localhost:5000/http/stream
1
2
3
4
5
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked

Start of the response...

O cabeçalho [Transfer-Encoding: chunked] substitui [Content-Length]: o corpo chega em partes, cada uma precedida de seu tamanho. Após um segundo, a resposta é interrompida: o [curl] recebeu um código de status 200 e um corpo truncado, sem nenhuma forma de saber que ocorreu um erro. Somente o console do servidor indica isso:

1
2
3
4
5
6
Error on request:
Traceback (most recent call last):
  ...
  File ".../examples/05-request-response/controllers/http.py", line 48, in chunks
    raise RuntimeError("error in the middle of the response")
RuntimeError: error in the middle of the response

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

Uma action não deve conter a lógica da aplicação em si; ela a delega a serviços, objetos que sabem executar uma tarefa específica (ler produtos, calcular um carrinho de compras etc.). Várias actions costumam usar o mesmo serviço. No [Spring] ou no [ASP.NET Core], um contêiner de injeção de dependência cria os serviços e os fornece automaticamente a quem precisa deles. O [Flask] não tem contêiner: a factory da aplicação cria os serviços, e as actions os solicitam à aplicação. O Exemplo 06 organiza seu código por domínio (produtos, clientes) e não por tipo (controllers, modelos):

06-services/
├── clients/
│   ├── __init__.py
│   └── controller.py
├── products/
│   ├── __init__.py
│   ├── controller.py
│   ├── in_memory_service.py
│   ├── product.py
│   └── service.py
└── app.py

2.6.1. O produto

# products/product.py: um produto
from dataclasses import dataclass
from decimal import Decimal


# uma dataclass: o Python escreve sozinho o construtor, __repr__, __eq__...
# frozen=True: o objeto é imutável (seus campos são definidos pelo construtor)
@dataclass(frozen=True)
class Product:
    id: int
    name: str
    price: Decimal  # Decimal: um número decimal exato (sem arredondamento binário)
  • Linha 8: uma dataclass (veja o Exemplo 03). Com [frozen=True], o objeto é imutável: seus campos são definidos pelo construtor, e qualquer tentativa de modificá-los ([p.price = 2]) lança uma exceção. Um objeto imutável pode ser compartilhado com segurança entre várias requisições;
  • Linhas 10 a 12: os campos, com seus tipos. Os tipos não são verificados pelo [Python] em tempo de execução: são anotações lidas por ferramentas de análise (como a do [Visual Studio Code]) e por certas bibliotecas ([Pydantic], tratado no próximo capítulo). O preço é um [Decimal], um número decimal exato: um [float] não consegue representar com exatidão 0,1 ou 3,2 (em binário, esses números têm infinitos dígitos), e uma soma de preços em [float] pode resultar em 5.500000000000001.

2.6.2. O contrato do serviço: service.py

# products/service.py: o CONTRATO do serviço, o que ele pode fazer, sem dizer como
from abc import ABC, abstractmethod

from flask import current_app

from products.product import Product


# uma classe abstrata (ABC): nenhum objeto pode ser criado a partir dela; uma classe
# filha deve escrever (sobrescrever) todos os métodos marcados com @abstractmethod
class ProductsService(ABC):

    @abstractmethod
    def find_all(self) -> list[Product]: ...

    # Product | None: um produto, ou None se ele não existir
    @abstractmethod
    def find_by_id(self, id: int) -> Product | None: ...


# o serviço da aplicação atual (veja app.py). current_app designa
# a aplicação que trata a requisição atual
def products_service() -> ProductsService:
    return current_app.extensions["products_service"]
  • Linhas 11 a 18: o contrato do serviço, isto é, o que ele sabe fazer, sem dizer como. Em [Python], um contrato é definido por uma classe abstrata: uma classe que herda de [ABC] ([Abstract Base Class]) e cujos métodos marcados com [@abstractmethod] não têm corpo (as reticências [...] servem de corpo vazio). Não é possível criar um objeto dessa classe; uma subclasse deve sobrescrever todos os seus métodos abstratos. Isso equivale às interfaces do [Java] e do [C#];
  • linha 14: a anotação do tipo devolvido pelo método (após [->]): uma lista de produtos. [self] é o objeto sobre o qual o método é chamado (o equivalente de [this] em [Java]), sempre listado como primeiro parâmetro;
  • linha 18: [Product | None]: um produto, ou [None] se ele não existir;
  • Linhas 23 e 24: a função que fornece o serviço às actions. [current_app] é, como [request], um proxy: ele designa a aplicação que trata a requisição atual. [app.extensions] é um dicionário que o [Flask] disponibiliza às extensões (as bibliotecas que se acrescentam ao [Flask]) para que guardem ali seus objetos; nós o usamos para nossos próprios serviços. A função também declara o tipo do serviço ([-> ProductsService]): o [Visual Studio Code] pode então sugerir seus métodos.

2.6.3. A implementação: in_memory_service.py

# products/in_memory_service.py: uma IMPLEMENTAÇÃO do contrato, com dados em memória
from decimal import Decimal

from products.product import Product
from products.service import ProductsService


class InMemoryProductsService(ProductsService):

    def __init__(self):
        # uma tupla: uma lista que não pode ser modificada
        self._products = (
            Product(1, "pen", Decimal("1.5")),
            Product(2, "notebook", Decimal("3.2")),
            Product(3, "eraser", Decimal("0.8")),
        )

    def find_all(self) -> list[Product]:
        return list(self._products)

    def find_by_id(self, id: int) -> Product | None:
        # next(generator, None): o primeiro produto correspondente, ou None
        return next((p for p in self._products if p.id == id), None)
  • linha 8: a classe herda o contrato e redefine seus dois métodos;
  • linhas 10 a 15: [__init__] é o construtor da classe. Ele guarda os produtos no atributo [_products] do objeto; o sublinhado inicial indica, por convenção, um atributo privado que o código externo à classe não deve usar. Os produtos estão em uma tupla (entre parênteses): uma sequência imutável. O preço é construído a partir de uma string ([Decimal("1.5")]): construído a partir do [float] 1.5, ele herdaria suas imprecisões;
  • linhas 18 e 19: o método devolve uma nova lista, uma cópia da tupla: quem a chama pode modificá-la sem afetar os dados do serviço;
  • linhas 21 a 23: [(p for p in self._products if p.id == id)] é uma expressão geradora: ela produz, um a um, os produtos cujo id corresponde ao solicitado. [next] devolve o primeiro elemento produzido ou o valor padrão, [None], se não houver nenhum.

2.6.4. O blueprint de produtos: controller.py

# products/controller.py: as ações de /products
from flask import Blueprint, jsonify

from products.service import products_service

products = Blueprint("products", __name__, url_prefix="/products")


@products.get("")
def list_all():
    # o serviço é obtido da aplicação, a cada requisição
    return jsonify(products_service().find_all())


@products.get("/<int:id>")
def one_product(id):
    product = products_service().find_by_id(id)
    if product is None:
        return {"message": f"Product no. {id} not found"}, 404
    return jsonify(product)
  • Linha 4: o blueprint conhece apenas o contrato do serviço (o módulo [service]), e não sua implementação: ele ignora que os produtos estão na memória;
  • Linhas 10 a 12: a action solicita o serviço à aplicação e depois lhe delega o trabalho. [jsonify] converte a lista de dataclasses em um array JSON;
  • linhas 16 a 20: um produto desconhecido devolve uma resposta 404, com uma mensagem em JSON.

2.6.5. O blueprint de clientes: controller.py

# clients/controller.py: um segundo blueprint, que usa o MESMO serviço
from dataclasses import dataclass
from decimal import Decimal

from flask import Blueprint, jsonify

from products.service import products_service

clients = Blueprint("clients", __name__, url_prefix="/clients")


# o conteúdo do carrinho, retornado como JSON
@dataclass
class Cart:
    client: str
    items: int
    total: Decimal


@clients.get("/cart")
def cart():
    products = products_service().find_all()
    # a soma dos preços; start=Decimal(0): somamos valores Decimal
    total = sum((p.price for p in products), start=Decimal(0))
    return jsonify(Cart("Jean Martin", len(products), total))
  • linhas 14 a 17: o conteúdo do carrinho de compras, devolvido em JSON;
  • linha 22: esse blueprint usa o mesmo serviço que o blueprint de produtos: um único objeto, compartilhado;
  • linha 24: [sum] soma os elementos de um iterável; seu parâmetro [start] é o valor inicial da soma (0 por padrão). Começar com [Decimal(0)] em vez do inteiro 0 não é essencial (um inteiro e um [Decimal] se somam), mas garante um resultado do tipo [Decimal] mesmo para um carrinho de compras vazio.

2.6.6. A declaração do serviço: app.py

# app.py: a aplicação do exemplo 06
from flask import Flask

from clients.controller import clients
from products.controller import products
from products.in_memory_service import InMemoryProductsService


def create_app():
    app = Flask(__name__)
    # JSON: acentos mantidos, chaves em sua ordem original (veja o exemplo 03)
    app.json.ensure_ascii = False
    app.json.sort_keys = False
    # o SERVIÇO: um único objeto, criado uma vez, na inicialização, e compartilhado por
    # todas as requisições. Nós o guardamos em app.extensions, um dicionário que
    # o Flask disponibiliza para as extensões... e para os nossos serviços
    app.extensions["products_service"] = InMemoryProductsService()
    app.register_blueprint(products)
    app.register_blueprint(clients)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linha 17: é aqui, e somente aqui, que a implementação do serviço é escolhida. O serviço é criado uma única vez, na inicialização, e o mesmo objeto atende a todas as requisições de todos os usuários: é um singleton (o escopo padrão dos beans do [Spring]). Para passar a uma implementação que lê de um banco de dados, bastaria mudar esta linha: os blueprints, que só conhecem o contrato, permaneceriam inalterados. Esse é todo o objetivo da injeção de dependência, mesmo implementada “à mão”: cada parte da aplicação depende de contratos, e um único lugar determina as implementações.

Um serviço compartilhado por todas as requisições precisa ser capaz de ser usado simultaneamente por várias requisições: o servidor de desenvolvimento trata cada requisição em sua própria thread. Isso não causa problema aqui: o serviço apenas lê dados que nunca mudam. O Exemplo 20 mostrará um serviço cujos dados mudam e as precauções que isso exige.

2.6.7. Execução

curl -i http://localhost:5000/products
HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 191

[
  {
    "id": 1,
    "name": "pen",
    "price": "1.5"
  },
  {
    "id": 2,
    "name": "notebook",
    "price": "3.2"
  },
  {
    "id": 3,
    "name": "eraser",
    "price": "0.8"
  }
]

Os preços se tornaram strings (["1.5"]): o JSON tem apenas um tipo numérico, que a maioria dos programas interpreta como número de ponto flutuante; por isso o provedor JSON do [Flask] converte um [Decimal] em string para preservar sua precisão.

curl -i http://localhost:5000/products/9
1
2
3
4
5
6
7
HTTP/1.1 404 NOT FOUND
Content-Type: application/json
Content-Length: 43

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

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