Referência dos middlewares embutidos

Este documento detalha todos os componentes middleware que acompanham o Django. Para informações de como usá-los e de como escrever o seu próprio middleware, veja o guia de uso de middleware.

Middlewares disponíveis

Middleware de cache

class django.middleware.cache.UpdateCacheMiddleware

class django.middleware.cache.FetchFromCacheMiddleware

Habilita o cache em todo o site. Se este estiver habilitado, cada página construída pelo Django será cacheada durante o tempo definido em CACHE_MIDDLEWARE_SECONDS. Veja a documentação do cache.

Middleware “Common”

class django.middleware.common.CommonMiddleware

Adiciona algumas conveniências para perfeccionistas:

• Proíbe o acesso de “user agents” especificados em DISALLOWED_USER_AGENTS, o qual deve ser uma lista de strings.

• Executa uma reescrita de URL baseada nas configurações APPEND_SLASH e PREPEND_WWW.

  Se o APPEND_SLASH for True e a URL inicial não terminar com uma barra, e ela não for encontrada no URLconf, então uma nova URL é formada, adicionando uma barra no final. Se esta nova URL é encontrada no URLconf, o Django redireciona a requisição para esta nova URL. Por outro lado, a URL inicial é processada habitualmente.

  Por exemplo, foo.com/bar será redirecionado para foo.com/bar/ se você não tiver um padrão de URL válido para foo.com/bar mas tem um padrão válido para foo.com/bar/.

  O comportamento do APPEND_SLASH mudou ligeiramente nesta versão. Ele não é utilizado para verificar se o padrão confere na URLconf.

  Se o PREPEND_WWW é True, as URLs que faltam um “www.” na frente serão redirecionadas para a mesma URL com o “www.” na frente.

  Estes dois tipos de opções são destinadas a normalizar URLs. A filosofia é que cada URL deve existir em um, e somente um, lugar. Tecnicamente uma URL foo.com/bar é diferente de foo.com/bar/ – um indexador de motor de busca tratará elas como URLs separadas – então esta é a melhor prática para normalizar URLs.

• Manipula ETags baseado na configuração USE_ETAGS. Se o USE_ETAGS é definido como True, o Django calculará um ETag para cada requisição usando um hash MD5 do conteúdo da página, e irá se responsabilizar por enviar repostas Not Modified (não modificado), se apropriado.

Middleware view metadata

class django.middleware.doc.XViewMiddleware

Envia cabeçalhos HTTP X-View personalizados para requisições HEAD oriundas de endereços IP definidos na configuração INTERNAL_IPS. Isso é utilizado pelo sistema de documentação automática do Django.

Middleware GZIP

class django.middleware.gzip.GZipMiddleware

Comprime conteúdos para navegadores que entendem compressão gzip (todos os navegadores modernos).

É sugerido colocá-lo em primeiro na lista de middlewares, desta forma a compressão do conteúdo de resposta será a última coisa a ser feita. Não serão comprimidos conteúdos menores que 200 bytes, quando o código de resposta for diferente de 200, quando arquivos JavaScript (para compatibilidade com IE), ou quando as respostas possuem o cabeçalho Content-Encoding já especificado.

Middleware GET condicional

class django.middleware.http.ConditionalGetMiddleware

Manipula operações condicionais do GET. Se a resposta tem um cabeçalho ETag ou Last-Modified, e a requisição possui If-None-Match ou If-Modified-Since, a resposta é substituída por um HttpNotModified`.

Também define os cabeçalhos de resposta Date e Content-Length.

Middleware para proxy reverso

class django.middleware.http.SetRemoteAddrFromForwardedFor

Define o request.META['REMOTE_ADDR'] baseado no request.META['HTTP_X_FORWARDED_FOR'], se o último estiver definido. Isso é útil se você estiver por trás de um proxy reverso que faz com que cada REMOTE_ADDR seja definido como 127.0.0.1.

Nota importante: Isso NÃO valida o HTTP_X_FORWARDED_FOR. Se você não está atrás de um proxy reverso que define o HTTP_X_FORWARDED_FOR automaticamente, não utilize este middleware. Ninguém pode burlar o valor do HTTP_X_FORWARDED_FOR, e por causa disso defina REMOTE_ADDR baseado no HTTP_X_FORWARDED_FOR, o que significa que ninguém pode “falsificar” seus endereços de IP. Somente use isto quando você confia absolutamente no valor do HTTP_X_FORWARDED_FOR.

Middleware Locale

class django.middleware.locale.LocaleMiddleware

Habilita a seleção de idioma baseado em dados vindos da requisição. Ele personaliza o conteúdo para cada usuário. Veja a documentação de internacionalização.

Middleware Session

class django.contrib.sessions.middleware.SessionMiddleware

Habilita o suporte a sessões. Veja a documentação de sessões.

Middleware Authentication

class django.contrib.auth.middleware.AuthenticationMiddleware

Adiciona o atributo user, representando o usuário atualmente logado, para todo objeto HttpRequest que chega. Veja Autenticação em requisições Web.

Middleware de proteção CSRF

class django.contrib.csrf.middleware.CsrfMiddleware

Please, see the release notes

Adiciona proteção contra Cross Site Request Forgeries adicionando campos invisíveis de formulários aos formulários POST e checando suas requisições pelos valores corretos. Veja a documentação da proteção de Cross Site Request Forgeries.

Middleware Transaction

class django.middleware.transaction.TransactionMiddleware

Vincula commit e rollback às fases request/response. Se uma função view é executada com sucesso, um commit é feito. Se ela falhar com uma exceção, um rollback é realizado.

A ordem deste middleware na pilha é importante: módulos middleware rodando fora dele rodam com commit-on-save - o comportamento padrão do Django. Módulos middleware rodando dentro dele (vêm depois na pilha) estarão abaixo do mesmo controle de transações como nas funções view.

Veja a documentação de gerenciamento de transações.