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:

- 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
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
- 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
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:
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
- 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
- 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
- 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.
A página de erro recebe o código de erro e exibe uma mensagem apropriada.
7.1.7. Configuração: app.py
- 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]:

O console do servidor exibe as oito etapas, em ordem:
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]:

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]:

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

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]:
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:
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.