Skip to content

7. O ciclo de vida de uma requisição

Entre a chegada de uma requisição e o envio de sua resposta, o [Flask] passa por várias etapas, e a aplicação pode intervir em cada uma delas. Já encontramos várias delas: os conversores de variáveis de caminho (exemplos 02 e 12), as funções [before_request] (exemplos 16, 22 e 23) e os tratadores de erro (exemplos 08 e 12). Este capítulo as reúne em um único exemplo, que exibe uma mensagem no console a cada etapa para que você possa observar a ordem:

Image

  • 1 e 8. O middleware WSGI. [WSGI] (*Web Server Gateway Interface*) é o padrão que conecta um servidor web escrito em [Python] a uma aplicação. Do ponto de vista do servidor, uma aplicação [Flask] é simplesmente um objeto chamável que recebe a descrição da requisição e gera a resposta. Um middleware é um objeto do mesmo tipo que envolve a aplicação: ele intercepta a requisição antes que chegue ao [Flask] e a resposta depois dele. É o equivalente dos filtros de servlet do [Java];
  • 2. O roteamento. [Flask] procura a rota que corresponde à URL, e os conversores de rota transformam as variáveis de caminho;
  • 3 e 4. As funções [before_request] , executadas na ordem em que foram registradas. Se alguma delas retornar uma resposta (ou lançar uma exceção), o processamento para ali: a ação não é chamada. É aqui que verificamos se um usuário está logado (próximo capítulo);
  • 5. A ação, e a view que ela gera;
  • 6. As funções [after_request] , que recebem a resposta, podem modificá-la (adicionar um cabeçalho ou um cookie) e devem retorná-la. São executadas na ordem inversa de seu registro;
  • 7. As funções [teardown_request] , que são sempre executadas bem no final, mesmo que uma exceção tenha interrompido o processamento. Elas não podem mais modificar a resposta; sua finalidade é liberar recursos (como fechar uma conexão com o banco de dados);
  • x. Tratadores de erro ([errorhandler]): uma exceção lançada por uma função [before_request], por uma ação ou por uma view é entregue ao tratador registrado para sua classe, que gera uma resposta de erro. Essa resposta passa então pelas funções [after_request], como uma resposta comum.

São os equivalentes dos interceptors do [Spring MVC] e dos filtros de ação do [ASP.NET Core MVC]. As funções [before_request], [after_request], e [teardown_request] costumam ser chamadas de hooks.

7.1. Exemplo 24: As etapas do processamento de uma requisição

24-lifecycle/
├── app.py
├── controllers/
│   └── calc.py
├── filters/
│   ├── errors.py
│   ├── hooks.py
│   ├── integer.py
│   ├── logger.py
│   └── marks.py
└── templates/
    ├── calc/
    │   └── result.html
    ├── error.html
    └── layout.html

A aplicação tem apenas uma ação, que calcula o quadrado de um inteiro: [/square/7]. Dependendo da URL, ela é bem-sucedida ou falha de várias maneiras.

7.1.1. O middleware WSGI: filters/logger.py

# filters/logger.py: um MIDDLEWARE WSGI. WSGI é o padrão que conecta um
# servidor web Python a uma aplicação: a aplicação é um objeto chamável
# app(environ, start_response). Um middleware é um objeto desse tipo, que ENVOLVE
# a aplicação: ele vê cada requisição passar ANTES do Flask, e a resposta DEPOIS
class LoggerMiddleware:

    def __init__(self, application):
        self.application = application  # a aplicação envolvida (Flask)

    def __call__(self, environ, start_response):
        # environ: um dicionário que descreve a requisição (método, caminho...)
        request = environ["REQUEST_METHOD"] + " " + environ["PATH_INFO"]
        if environ.get("QUERY_STRING"):
            request += "?" + environ["QUERY_STRING"]
        print()
        print("---", request)
        print("1. middleware (before)")
        status = []

        # start_response: a função pela qual o Flask anuncia o código e os
        # cabeçalhos da resposta; nós a envolvemos para anotar o código na passagem
        def spy_start_response(status_line, headers, exc_info=None):
            status.append(status_line)
            return start_response(status_line, headers, exc_info)

        # todo o resto: o Flask, a ação, a view
        response = self.application(environ, spy_start_response)
        print(f"8. middleware (after: code {status[0] if status else '?'})")
        return response
  • Linha 7: o middleware recebe a aplicação que ele envolve;
  • linha 10: o método especial [__call__] torna o objeto chamável: [middleware(environ, start_response)] executa esse método. Essa é a assinatura imposta pelo [WSGI]: [environ] é um dicionário que descreve a requisição (o método em [REQUEST_METHOD], o caminho em [PATH_INFO], os parâmetros em [QUERY_STRING], os cabeçalhos etc.); [start_response] é uma função fornecida pelo servidor, que a aplicação chama para informar o código e os cabeçalhos da resposta;
  • linhas 12–17: o middleware exibe a requisição. É a mensagem nº 1: nada aconteceu ainda no [Flask];
  • linhas 22–24: para determinar o código da resposta, o middleware passa à aplicação uma função própria — no lugar de [start_response] — que registra o código à medida que ele passa e depois chama a função verdadeira. É uma função interna (definida dentro de outra função): ela tem acesso às variáveis da função que a contém, neste caso a lista [status];
  • linha 27: a chamada da aplicação envolvida: o restante do processamento ocorre dentro dessa chamada;
  • linha 28: mensagem nº 8, quando o [Flask] terminou.

Um middleware atua no nível do [WSGI]: ele desconhece [request], [g] e as rotas do [Flask]. Ele é usado para processamentos que se aplicam a todas as requisições, independentemente da aplicação: registro em log, compressão, tratamento de um proxy etc. [Werkzeug] fornece alguns deles, como o [ProxyFix], que corrige o endereço do cliente quando a aplicação está atrás de um servidor proxy (o estudo de caso aborda isso em relação ao endereço IP dos clientes).

7.1.2. O conversor: filters/integer.py

# filters/integer.py: a variável de caminho <integer:n>, convertida em inteiro, ou
# None se não for um inteiro (cabe então à ação decidir)
from werkzeug.routing import BaseConverter


class IntegerConverter(BaseConverter):
    # qualquer pedaço de caminho (sem barra)
    regex = r"[^/]+"

    def to_python(self, value: str) -> int | None:
        print(f'2. conversion of the parameter (received value: "{value}")')
        try:
            return int(value)
        except ValueError:
            return None

Um conversor (exemplo 12) que aceita qualquer trecho de um caminho ([[^/]+]: um ou mais caracteres diferentes de [/]) e o converte por inteiro, ou para [None] se não for um valor válido. Diferentemente de [<int:n>], que retornaria uma página 404 para [/square/abc], aqui é a ação que determinará o resultado. Ele exibe a mensagem nº 2.

7.1.3. Ações marcadas: filters/marks.py

As funções [before_request] são executadas antes de todas as ações. Muitas vezes, um processamento se aplica apenas a certas ações. Uma maneira simples de especificá-las é marcá-las:

# filters/marks.py: dois decoradores que MARCAM uma ação, sem alterar
# nada em sua execução: eles adicionam a ela um atributo, que as funções
# de filters/hooks.py procuram


def block(action):
    action.block = True
    return action


def timing(action):
    action.timing = True
    return action

Esses dois decoradores não alteram a ação em si: eles adicionam um atributo a ela (em [Python], uma função é um objeto ao qual se podem adicionar atributos) e a deixam inalterada. As funções [before_request] procurarão essas marcas na ação visada pela requisição.

7.1.4. Hooks: filters/hooks.py

# filters/hooks.py: funções executadas ANTES e DEPOIS de cada ação
import time

from flask import abort, current_app, g, request


# a ação que tratará a requisição atual (None se nenhuma rota corresponder).
# request.endpoint: o nome da ação ("calc.square"); view_functions:
# o dicionário nome -> função da aplicação
def targeted_action():
    return current_app.view_functions.get(request.endpoint)


# a marca [name] (veja marks.py) está colocada na ação visada?
def marked(name: str) -> bool:
    return getattr(targeted_action(), name, False)


def register(app):

    # before_request: antes da ação. Se a função retornar uma resposta (ou lançar
    # uma exceção), o processamento para aí: a ação não é chamada
    @app.before_request
    def block():
        if marked("block"):
            print(f"3. before_request Block (targeted action: {request.endpoint})")
            if "block" in request.args:
                abort(403)  # uma resposta de erro 403 (acesso negado)

    @app.before_request
    def timing_start():
        if marked("timing"):
            print("4. before_request Timing (before)")
            # a hora de início, guardada em g (escopo de requisição)
            g.start = time.perf_counter()

    # after_request: depois da ação (e da view que ela construiu), com a
    # resposta, que a função pode modificar; ela deve retorná-la
    @app.after_request
    def timing_after(response):
        if marked("timing"):
            print(f"6. after_request Timing (code {response.status_code})")
        return response

    # teardown_request: bem no final, sempre chamado, com a possível
    # exceção (não tratada); ele não pode mais alterar a resposta
    @app.teardown_request
    def timing_end(exception):
        if "start" in g:
            ms = round((time.perf_counter() - g.start) * 1000)
            outcome = "" if exception is None else f", exception {type(exception).__name__}"
            print(f"7. teardown_request Timing (end, {ms} ms{outcome})")
  • Linhas 10–11: a ação que tratará a requisição. Após o roteamento, [request.endpoint] contém o nome da rota selecionada ([calc.square]: o nome do blueprint, um ponto e o nome da função); [current_app.view_functions] é o dicionário que associa cada nome à sua função correspondente. Se nenhuma rota corresponder, [request.endpoint] é definido como [None], e a função retorna [None];
  • linhas 15–16: a marca está definida? [getattr(object, name, default)] retorna o atributo com o nome indicado, ou o valor padrão se ele não existir (ou se o objeto for [None]);
  • linha 19: os callbacks são registrados por uma função chamada por [app.py];
  • linhas 24–28: o primeiro hook, mensagem nº 3: para uma ação marcada com [block], o parâmetro [?block] da URL provoca um erro 403 (*Forbidden*, acesso negado): [abort] lança uma exceção, que interrompe o processamento;
  • linhas 31–35: o segundo hook, mensagem nº 4: para uma ação marcada com [timing], a hora de início é armazenada em [g]. [time.perf_counter()] é um relógio preciso, projetado para medir durações;
  • linhas 39–43: mensagem nº 6. A função recebe a resposta e deve retorná-la (possivelmente modificada). [response.status_code] é o código da resposta;
  • linhas 47–52: mensagem nº 7, contendo o tempo decorrido desde o hook nº 4. O teste ["start" in g] verifica se a medição foi iniciada. A função recebe a exceção que interrompeu o processamento, se houver alguma que não tenha sido tratada, e [None] caso contrário.

7.1.5. Tratamento de erros: filters/errors.py

# filters/errors.py: os tratadores de erro da aplicação
from flask import render_template
from werkzeug.exceptions import HTTPException


def register(app):

    # uma exceção "inesperada" de um dado tipo: ValueError e suas subclasses
    @app.errorhandler(ValueError)
    def value_error(e: ValueError):
        print(f"x. errorhandler ValueError ({e})")
        # em vez da página de erro padrão, nossa view [error], com o código 500
        return render_template("error.html", code=500), 500

    # os erros HTTP (abort(400), abort(403), página desconhecida -> 404...):
    # HTTPException é a classe pai de todas as exceções HTTP do Werkzeug
    @app.errorhandler(HTTPException)
    def http_error(e: HTTPException):
        print(f"e. errorhandler HTTPException (code {e.code})")
        return render_template("error.html", code=e.code), e.code
  • Linhas 9–13: um tratador de exceção para a classe [ValueError] (e suas subclasses): um erro “inesperado”, convertido em uma página de erro “personalizada” com código de status 500 (*Internal Server Error*). A mensagem da exceção é exibida no console, mas não na página: ela pode conter detalhes internos que não interessam ao usuário;
  • Linhas 17–20: um tratador para todos os erros HTTP. [abort(400)], [abort(403)], uma URL de rota inexistente (404), um método proibido (405): todos lançam uma exceção de uma subclasse de [HTTPException] ([BadRequest], [Forbidden], [NotFound]...), que carrega seu código no atributo [code]. Esse único tratador substitui, portanto, todas as páginas de erro em inglês do [Werkzeug] pelas nossas.

Para uma exceção, o [Flask] seleciona o tratador registrado para a classe mais próxima da dela. Também é possível registrar um tratador para um código específico: [@app.errorhandler(404)]. Uma exceção que não tem tratador se torna um erro 500: no modo de depuração, é a página de depuração (exemplo 03); sem o modo de depuração, é a página de erro 500 padrão ou a página do tratador registrado para o código 500.

7.1.6. O controller e a página de erro

# controllers/calc.py: uma ação marcada por dois decoradores
from flask import Blueprint, abort, render_template

from filters.marks import block, timing

calc = Blueprint("calc", __name__)


@calc.get("/square/<integer:n>")
@block
@timing
def square(n: int | None):
    print(f"5. action square({n})")
    if n is None:
        abort(400)  # um erro 400: veja filters/errors.py
    if n == 13:
        raise ValueError("13 brings bad luck")  # um erro "inesperado"
    return render_template("calc/result.html", n=n, square=n * n)
  • linhas 9–11: a rota usa o conversor [integer]; a ação traz os dois decoradores. A ordem também importa aqui (exemplo 12): os decoradores são aplicados de baixo para cima, e o decorador de rota deve ser o último a ser aplicado (o primeiro escrito) para registrar a função decorada;
  • linha 15: um parâmetro que não é um inteiro: erro 400;
  • linha 17: o número 13 provoca um erro “inesperado”;
  • linha 18: o caso normal.
{% extends "layout.html" %}
{# a página de erro; seu modelo: o código do erro #}

{% block content %}
  <div class="alert alert-danger">
    <h1 class="h4">Error {{ code }}</h1>
    <p class="mb-0">
      {% if code == 400 %}Bad request.
      {% elif code == 403 %}Access denied.
      {% elif code == 404 %}Page not found.
      {% else %}Internal server error.
      {% endif %}
    </p>
  </div>
{% endblock %}

A página de erro recebe o código de erro e exibe uma mensagem apropriada.

7.1.7. Configuração: app.py

# app.py: a aplicação do exemplo 24
from pathlib import Path

from flask import Blueprint, Flask

from controllers.calc import calc
from filters import hooks, errors
from filters.integer import IntegerConverter
from filters.logger import LoggerMiddleware

BOOTSTRAP = Path(__file__).resolve().parent.parent / "common" / "bootstrap"


def create_app():
    app = Flask(__name__)
    app.jinja_env.trim_blocks = True
    app.jinja_env.lstrip_blocks = True
    app.register_blueprint(Blueprint("bootstrap", __name__, static_folder=BOOTSTRAP,
                                     static_url_path="/bootstrap"))
    # o conversor das variáveis <integer:...>
    app.url_map.converters["integer"] = IntegerConverter
    app.register_blueprint(calc)
    # as funções executadas antes e depois de cada ação, na ordem
    # em que são registradas
    hooks.register(app)
    # os tratadores de erro
    errors.register(app)
    # o middleware WSGI: ele ENVOLVE toda a aplicação Flask
    app.wsgi_app = LoggerMiddleware(app.wsgi_app)
    return app


if __name__ == "__main__":
    create_app().run(port=5000, debug=True)
  • Linha 21: o conversor;
  • Linhas 25–27: os callbacks e os tratadores de erro;
  • linha 29: o middleware. [app.wsgi_app] é o método pelo qual o servidor chama a aplicação [Flask]; ele é substituído pelo middleware, que chamará o antigo. Envolvemos [app.wsgi_app] em vez de [app] propriamente dito, para que a variável [app] continue sendo o objeto [Flask], com seus métodos ([run], [route]...).

7.1.8. Execução

O caso normal, [/square/7]:

Image

O console do servidor exibe as oito etapas, em ordem:

--- GET /square/7
1. middleware (before)
2. conversion of the parameter (received value: "7")
3. before_request Block (targeted action: calc.square)
4. before_request Timing (before)
5. action square(7)
6. after_request Timing (code 200)
7. teardown_request Timing (end, 1 ms)
8. middleware (after: code 200 OK)
127.0.0.1 - - [26/Sep/2026 15:39:00] "GET /square/7 HTTP/1.1" 200 -

A última linha é a entrada de log do servidor de desenvolvimento do [Werkzeug], escrita após o envio da resposta. Um acesso bloqueado, [/square/7?block]:

Image

1
2
3
4
5
6
7
--- GET /square/7?block
1. middleware (before)
2. conversion of the parameter (received value: "7")
3. before_request Block (targeted action: calc.square)
e. errorhandler HTTPException (code 403)
6. after_request Timing (code 403)
8. middleware (after: code 403 FORBIDDEN)

A primeira chamada lançou uma exceção: a segunda chamada e a ação não foram executadas. A resposta de erro, gerada pelo tratador, passa por [after_request]; [teardown_request] foi chamada, mas não exibiu nada, pois a operação não chegou a começar. Um parâmetro que não é um inteiro, [/square/abc]:

Image

--- GET /square/abc
1. middleware (before)
2. conversion of the parameter (received value: "abc")
3. before_request Block (targeted action: calc.square)
4. before_request Timing (before)
5. action square(None)
e. errorhandler HTTPException (code 400)
6. after_request Timing (code 400)
7. teardown_request Timing (end, 0 ms)
8. middleware (after: code 400 BAD REQUEST)

Desta vez, a ação foi chamada — [None] — e lançou o erro 400. Um erro “inesperado”, [/square/13]:

Image

--- GET /square/13
1. middleware (before)
2. conversion of the parameter (received value: "13")
3. before_request Block (targeted action: calc.square)
4. before_request Timing (before)
5. action square(13)
x. errorhandler ValueError (13 brings bad luck)
6. after_request Timing (code 500)
7. teardown_request Timing (end, 0 ms)
8. middleware (after: code 500 INTERNAL SERVER ERROR)

A exceção foi tratada por seu tratador: o usuário vê a página de erro “personalizada”, e não a página de depuração, embora o modo de depuração esteja ativado. Por fim, uma URL que não corresponde a nenhuma rota, [/unknown]:

1
2
3
4
--- GET /unknown
1. middleware (before)
e. errorhandler HTTPException (code 404)
8. middleware (after: code 404 NOT FOUND)

O roteamento falhou: nenhuma rota, nenhum conversor, nenhuma ação. Os callbacks foram executados, mas nada foi exibido porque não encontraram uma ação de destino. A página 404 é a nossa:

curl -i http://localhost:5000/unknown
HTTP/1.1 404 NOT FOUND
Content-Type: text/html; charset=utf-8
Content-Length: 375
...
  <div class="alert alert-danger">
    <h1 class="h4">Error 404</h1>
    <p class="mb-0">
Page not found.
    </p>
  </div>
...

Vamos nos concentrar no essencial. As funções [before_request] são o lugar certo para as verificações comuns a muitas ações (o usuário está logado? Ele tem permissão para acessar esta ação?): o próximo capítulo as usa para a autenticação. Os tratadores de erro garantem que o usuário nunca veja uma página técnica, seja qual for o erro: o estudo de caso inclui um para cada tipo de erro.