Em projetos com Django, grande parte da dificuldade não nasce nos models (modelos) ou nas views (camadas que recebem a requisição e devolvem a resposta), mas nos pequenos trechos de lógica repetidos em muitos pontos. São detalhes como capturar o IP real, ler parâmetros de consulta com segurança, identificar o dispositivo, criar tokens curtos e padronizar logs. Quando cada tela, API ou middleware (componente que intercepta requisições e respostas) resolve isso “do seu jeito”, a manutenção se torna lenta e arriscada.
Uma abordagem centrada em utils (funções utilitárias) organiza essas rotinas em um lugar único, com comportamento previsível e fácil de testar. O resultado costuma ser código mais limpo, menos duplicação, menos bugs por interpretação diferente e mais consistência entre apps do mesmo projeto. A seguir estão 10 utilitários práticos para Django, com funções completas e exemplos reais de uso em views, sem dependências externas e com foco em cenários comuns de produção.
Estrutura recomendada para utilitários no projeto
Uma base sólida começa com uma organização simples para concentrar funções reutilizáveis. Um padrão comum é criar uma pasta utils dentro do projeto (ou dentro de um app “core”) e separar por assunto, como utils/request.py, utils/pagination.py e utils/security.py. Essa separação evita arquivos gigantes e mantém cada módulo com responsabilidade clara. Também facilita importações consistentes e reduz o risco de ciclos de importação. A estrutura abaixo exemplifica uma forma prática de começar.
O exemplo a seguir mostra uma estrutura típica de diretórios para acomodar os utilitários descritos. A ideia central é manter funções pequenas, com nomes diretos e comportamento estável. Em Django, utilitários tendem a ser usados em views, services e tasks, então um local previsível ajuda bastante. Também é útil manter testes próximos, mas o foco aqui é o código pronto para uso. A organização sugerida pode ser adaptada conforme o tamanho do projeto.
# Estrutura sugerida (exemplo)
# projeto/
# core/
# utils/
# __init__.py
# request.py
# pagination.py
# security.py
# serialization.py
# logging_utils.py
# views.py
# models.py1) Obter o IP real do cliente a partir da requisição
Capturar o IP do cliente parece simples, mas muda bastante em produção. Em ambientes com proxy reverso, CDN ou balanceador de carga, o REMOTE_ADDR pode representar o IP do proxy, não o IP do usuário. O cabeçalho X-Forwarded-For costuma carregar uma lista de IPs, onde o primeiro geralmente é o IP original. O utilitário abaixo busca esse valor e faz um fallback seguro para REMOTE_ADDR. Esse padrão reduz repetição e inconsistência entre endpoints.
A função a seguir mostra como extrair o IP considerando os cenários mais comuns. Em alguns ambientes, o cabeçalho pode estar ausente, vazio ou conter múltiplos valores separados por vírgula. Por esse motivo, o código normaliza com strip() e seleciona o primeiro item. A função não tenta “validar” profundamente o formato do IP para manter simplicidade, mas entrega uma base consistente. Em necessidades mais rígidas, a validação pode ser adicionada no mesmo ponto central.
def get_client_ip(request):
# Tenta pegar o IP real quando há proxy/balanceador
x_forwarded_for = request.META.get("HTTP_X_FORWARDED_FOR")
if x_forwarded_for:
# Pode vir uma lista: "ip1, ip2, ip3"
ip = x_forwarded_for.split(",")[0].strip()
return ip
# Fallback para o endereço visto diretamente pelo servidor
return request.META.get("REMOTE_ADDR", "")O exemplo abaixo mostra o uso em uma view simples retornando JSON. Esse padrão é útil para auditoria, rate limiting e logs. Centralizar a extração evita versões diferentes da mesma lógica em diferentes partes do projeto. O retorno vazio é intencional quando não há valor, evitando exceções. Isso mantém o endpoint previsível mesmo em ambientes incomuns.
from django.http import JsonResponse
from core.utils.request import get_client_ip
def sample_view(request):
client_ip = get_client_ip(request)
return JsonResponse({"ip": client_ip})2) Obter o User-Agent da requisição
User-Agent é uma string enviada pelo cliente que identifica navegador, sistema e, às vezes, o tipo de dispositivo. Essa informação é útil para logging, análise de erros e diagnóstico de comportamentos específicos. Como o cabeçalho pode estar ausente, é melhor ter um acesso padronizado com valor default. Isso evita checks repetidos e reduz chance de KeyError. O utilitário abaixo retorna uma string sempre.
A função usa request.META, que é o dicionário de variáveis CGI e cabeçalhos normalizados pelo Django. Quando o cabeçalho não existe, o retorno padrão é uma string vazia. Esse detalhe simplifica a chamada, pois o restante do código trata sempre uma string. Além disso, a centralização permite filtrar ou truncar valores futuramente sem modificar cada endpoint. Esse tipo de utilitário costuma aparecer em logs e auditorias.
def get_user_agent(request):
return request.META.get("HTTP_USER_AGENT", "")O exemplo a seguir mostra como esse dado pode ser devolvido por uma API de diagnóstico. Em aplicações reais, essa informação costuma ser logada e não necessariamente exposta. Ainda assim, a utilidade é a mesma: obter o valor com segurança e sem repetição. Essa padronização também ajuda quando diferentes serviços precisam do mesmo dado. Com a função única, a manutenção fica concentrada.
from django.http import JsonResponse
from core.utils.request import get_user_agent
def sample_view(request):
user_agent = get_user_agent(request)
return JsonResponse({"user_agent": user_agent})3) Detectar requisição de dispositivo móvel (mobile) ou desktop
Detecção simples de dispositivo costuma ser suficiente para ajustes leves, como variantes de template ou pequenos recursos condicionais. Sem bibliotecas externas, uma abordagem prática é procurar palavras-chave no User-Agent. Essa técnica não é perfeita, mas atende muitos casos com custo baixo. O utilitário abaixo retorna um booleano e mantém a regra em um único lugar. Em projetos maiores, a lista pode ser ajustada conforme o público real.
A função normaliza o texto para minúsculas e procura termos comuns como “iphone”, “android” e “ipad”. O uso de any() torna o código curto e fácil de expandir. Quando não existe User-Agent, o padrão é string vazia, resultando em False. O ponto mais importante é ter uma regra única e conhecida. Isso evita que cada endpoint use listas diferentes e chegue a resultados inconsistentes.
def is_mobile_request(request):
user_agent = request.META.get("HTTP_USER_AGENT", "").lower()
palavras_chave_mobile = ["iphone", "android", "mobile", "ipad"]
return any(palavra in user_agent for palavra in palavras_chave_mobile)O exemplo abaixo ilustra a resposta em JSON com a decisão tomada. Em cenários práticos, essa informação pode controlar a escolha de um template ou um conjunto de campos retornados. A função também é útil em logs, permitindo segmentar problemas por tipo de dispositivo. A regra pode evoluir sem alterar a interface da função. Assim, o restante do sistema não precisa ser refeito.
from django.http import JsonResponse
from core.utils.request import is_mobile_request
def sample_view(request):
mobile = is_mobile_request(request)
return JsonResponse({"is_mobile": mobile})4) Gerar tokens aleatórios curtos para códigos e referências
Tokens curtos aparecem em convites, identificadores amigáveis e referências internas. Uma implementação ingênua pode repetir lógica, usar conjuntos de caracteres inconsistentes ou gerar tokens muito previsíveis. O utilitário abaixo cria um token com letras e dígitos, permitindo controlar o tamanho. Para usos de segurança forte, o ideal é usar geradores criptograficamente seguros, mas para referências internas e códigos simples esta abordagem é comum. Centralizar a geração evita que cada módulo escolha um padrão diferente.
O exemplo usa random e string para compor o conjunto de caracteres. O parâmetro length permite adequar o tamanho do token ao caso de uso. Em fluxos como “código de convite”, um tamanho entre 8 e 12 costuma equilibrar praticidade e baixa chance de colisão. Se o token precisar ser resistente a ataques, a implementação pode migrar para secrets sem alterar chamadas externas. O objetivo aqui é manter uma função única e reutilizável.
import random
import string
def generate_random_token(length=8):
caracteres = string.ascii_letters + string.digits
return "".join(random.choice(caracteres) for _ in range(length))O uso em view segue o mesmo padrão de reutilização. Esse exemplo retorna o token em JSON apenas para demonstrar a geração. Em produção, o token normalmente é persistido em um model ou enviado por e-mail. Manter a geração em utilitário facilita padronizar tamanho e conjunto de caracteres. Isso também torna testes mais diretos, pois a função pode ser testada isoladamente.
from django.http import JsonResponse
from core.utils.security import generate_random_token
def sample_view(request):
token = generate_random_token(10)
return JsonResponse({"token": token})5) Ler parâmetros booleanos de query string com segurança
Parâmetros de consulta (query params) chegam sempre como texto em Django, mesmo quando representam booleanos. Isso causa bugs quando se testa diretamente a string, pois “false” não é falso em Python, e “0” também é uma string não vazia. Um utilitário pequeno resolve a conversão com regras explícitas e consistentes. O objetivo é reduzir interpretações diferentes em diferentes endpoints. O padrão abaixo trata ausências e valores comuns de “verdadeiro”.
A função recebe a chave e um padrão default para quando o parâmetro não existe. Ao encontrar um valor, normaliza para minúsculas e verifica se está em uma lista permitida. Essa lista pode ser ajustada conforme convenções do sistema, como incluir “on” ou “t”. O ponto principal é tornar a decisão previsível e centralizada. Assim, um endpoint não interpreta “yes” como verdadeiro enquanto outro ignora.
def get_bool_query_param(request, key, default=False):
valor = request.GET.get(key)
if valor is None:
return default
return valor.lower() in ["true", "1", "yes"]O exemplo abaixo considera a URL com algo como ?active=true ou ?active=0. O retorno em JSON mostra o resultado já convertido para booleano real. Essa conversão é especialmente útil em filtros, paginações e flags de comportamento. Com a função, a lógica de conversão não se espalha pelo projeto. Isso reduz risco de regressão quando regras mudam.
from django.http import JsonResponse
from core.utils.request import get_bool_query_param
def sample_view(request):
active = get_bool_query_param(request, "active", default=False)
return JsonResponse({"active": active})6) Montar domínio atual e URL base (scheme + host)
Montar links absolutos é comum em e-mails, callbacks e webhooks. O Django fornece peças como request.is_secure() e request.get_host(), mas muitos projetos repetem essa montagem em vários lugares. O utilitário centraliza a decisão de http vs https e garante consistência. Isso evita links quebrados por esquemas errados quando o sistema roda atrás de proxy. A função abaixo retorna a URL base no formato “https://dominio”.
A implementação escolhe o scheme com base em is_secure(), que indica se a requisição foi feita via HTTPS do ponto de vista do Django. Em ambientes com proxy, esse comportamento depende de configuração correta de headers confiáveis, mas a função continua sendo o lugar certo para concentrar ajustes. O método get_host() inclui domínio e porta quando aplicável. A saída padronizada facilita concatenar caminhos, como “/reset/…”. Assim, uma mudança futura no modo de detectar HTTPS afeta apenas esse ponto.
def get_current_domain(request):
scheme = "https" if request.is_secure() else "http"
return f"{scheme}://{request.get_host()}"O exemplo demonstra um endpoint que retorna a base URL detectada. Em usos reais, esse valor pode compor links em notificações e integrações. Manter a montagem em uma função reduz risco de inconsistência entre apps. Também facilita escrever testes que simulam HTTP e HTTPS. O mesmo utilitário funciona em views tradicionais e em APIs.
from django.http import JsonResponse
from core.utils.request import get_current_domain
def sample_view(request):
domain = get_current_domain(request)
return JsonResponse({"domain": domain})7) Paginar qualquer QuerySet ou lista de forma reutilizável
Paginação aparece em listagens de painel, feeds e endpoints de API. O Django oferece o Paginator, mas é comum repetir o mesmo padrão: ler “page”, criar paginador e tratar valores inválidos. Um utilitário encapsula isso e entrega uma página pronta, com metadados como total e número de páginas. Isso mantém views menores e consistentes. O exemplo abaixo funciona tanto para QuerySet (consulta ao banco) quanto para listas Python.
A função lê o parâmetro “page” e cria um Paginator com per_page configurável. Em vez de chamar métodos que lançam exceção, o uso de get_page() é prático, pois lida com páginas inválidas retornando a página mais próxima. Essa escolha simplifica a camada de view e evita blocos repetidos de try/except. O resultado é um objeto de página com itens iteráveis e acesso ao paginador. Esse objeto pode alimentar tanto templates quanto JSON.
from django.core.paginator import Paginator
def paginate_queryset(queryset, request, per_page=10):
page_number = request.GET.get("page", 1)
paginator = Paginator(queryset, per_page)
return paginator.get_page(page_number)O exemplo abaixo retorna IDs para simplificar a visualização do resultado. Em uma API real, normalmente há serialização de campos e metadados adicionais. Ainda assim, o foco é o padrão: uma função única para paginar e uma view limpa. O retorno inclui o total e os resultados da página atual. Essa abordagem evita divergência de paginação entre endpoints diferentes.
from django.http import JsonResponse
from core.utils.pagination import paginate_queryset
from .models import Article
def sample_view(request):
page = paginate_queryset(Article.objects.all(), request, per_page=10)
return JsonResponse({
"count": page.paginator.count,
"page": page.number,
"num_pages": page.paginator.num_pages,
"results": [obj.id for obj in page],
})8) Ler cabeçalhos (headers) de forma segura e padronizada
Cabeçalhos podem estar ausentes e seus nomes chegam ao Django transformados em chaves no META. Por exemplo, “Referer” vira “HTTP_REFERER”, e hífens viram underscore. Para evitar repetição de conversões e checks, um utilitário pode transformar o nome e buscar com default. Isso torna o código mais legível e reduz erro de digitação. O padrão abaixo aceita nomes com hífen e qualquer capitalização.
A função recebe um nome como “X-Request-Id” e monta a chave do Django no formato “HTTP_X_REQUEST_ID”. Quando não encontra, retorna o valor padrão indicado, como None. Isso evita exceções e elimina condicionais repetidos em cada view. Esse utilitário é especialmente útil para correlação de logs, autenticações por header e rastreamento de requisições. Ao centralizar, qualquer ajuste de normalização ocorre em um ponto único.
def get_header(request, name, default=None):
chave = f"HTTP_{name.upper().replace('-', '_')}"
return request.META.get(chave, default)O exemplo demonstra a leitura de “Referer”, que é comum em diagnósticos e auditorias. Mesmo quando o navegador não envia, a função devolve None sem quebrar o fluxo. Esse padrão também funciona para headers personalizados, como “X-App-Version”. Assim, a view fica focada no comportamento do endpoint e não em detalhes de normalização. A padronização reduz a chance de bugs silenciosos por nomes incorretos.
from django.http import JsonResponse
from core.utils.request import get_header
def sample_view(request):
referer = get_header(request, "Referer")
return JsonResponse({"referer": referer})9) Converter instância de model para dicionário de forma segura
Converter um objeto de model em dicionário é útil em integrações internas, jobs e respostas simples. O Django oferece model_to_dict, mas é comum precisar lidar com instâncias nulas ou selecionar campos. Um utilitário pequeno resolve o caso de “objeto inexistente” retornando um dicionário vazio. Também padroniza a lista de campos para reduzir exposição acidental. Esse padrão é útil quando se quer uma conversão rápida e controlada.
A função abaixo recebe uma instância e uma lista opcional de campos. Se a instância for falsa (por exemplo, None), retorna {} em vez de gerar erro. Isso ajuda em fluxos onde a busca pode falhar e o chamador decide o que fazer. O uso de “fields” limita a saída ao necessário, evitando vazamento de dados sensíveis por descuido. A centralização reduz variações de serialização entre módulos.
from django.forms.models import model_to_dict
def model_to_dict_safe(instance, fields=None):
if not instance:
return {}
return model_to_dict(instance, fields=fields)O exemplo abaixo busca um artigo por chave primária e retorna apenas “id” e “title”. Em sistemas reais, é comum validar permissões e tratar ausência com 404, mas o foco aqui é a conversão controlada. A função facilita manter consistência nos campos retornados. Ao crescer o projeto, esse utilitário pode ser usado em tarefas assíncronas e relatórios. Assim, o padrão de serialização simples fica uniforme.
from django.http import JsonResponse
from core.utils.serialization import model_to_dict_safe
from .models import Article
def sample_view(request, pk):
article = Article.objects.get(pk=pk)
return JsonResponse(model_to_dict_safe(article, fields=["id", "title"]))10) Logger simples de requisições sem depender de middleware
Logging de requisições ajuda a entender incidentes, mapear uso e investigar falhas. Uma abordagem comum é colocar logs em middleware, mas nem sempre isso é desejado, principalmente quando apenas alguns endpoints precisam de registro detalhado. Um utilitário centraliza o formato do log e evita duplicação de mensagens. O padrão abaixo registra método, caminho e IP. Esse formato consistente facilita filtrar e correlacionar eventos.
A função usa o módulo padrão logging, que se integra ao sistema de logs do Django. O logger é criado por módulo, permitindo controle por configuração de logging. A mensagem é parametrizada, o que é melhor do que interpolar string diretamente, pois muitos handlers fazem otimizações. O IP usado no exemplo é REMOTE_ADDR, mas pode ser trocado pelo utilitário de IP real quando necessário. O importante é que o padrão fique em um único lugar.
import logging
logger = logging.getLogger(__name__)
def log_request(request):
logger.info(
"method=%s path=%s ip=%s",
request.method,
request.path,
request.META.get("REMOTE_ADDR", "")
)O exemplo mostra como registrar o log e responder normalmente. Em cenários reais, esse utilitário pode ser chamado no início de views críticas ou em pontos específicos do fluxo. Essa abordagem também evita que cada endpoint invente um formato de log diferente. Quando o formato é padronizado, a leitura e a busca por eventos ficam mais rápidas. O resultado é um histórico mais coerente em produção.
from django.http import JsonResponse
from core.utils.logging_utils import log_request
def sample_view(request):
log_request(request)
return JsonResponse({"status": "logged"})Como esses utilitários reduzem repetição e melhoram a manutenção
Antes de centralizar, o padrão comum é resolver cada detalhe “inline” em views, services e middlewares. Isso produz múltiplas versões de regras pequenas, como “o que é verdadeiro na query”, “qual header ler” e “qual IP usar”. Com o tempo, inconsistências se acumulam e bugs aparecem em bordas difíceis de rastrear. Ao reunir essas regras em utils, o sistema passa a ter um único lugar para evoluir comportamento. Isso torna mudanças mais seguras, pois corrigir um detalhe não exige procurar dezenas de arquivos.
Depois de adotar utilitários, as views tendem a ficar focadas no domínio do problema e menos em plumbing. Testes unitários ficam mais simples, porque funções puras podem ser testadas sem instanciar toda a view. O reaproveitamento entre apps cresce naturalmente, evitando que cada app crie “seus próprios helpers”. Em produção, o ganho aparece em estabilidade, já que as regras de borda ficam padronizadas e revisadas. O projeto se torna mais previsível e menos sujeito a regressões silenciosas.
Conclusão
Funções utilitárias podem parecer pequenas, mas acumulam impacto grande quando um projeto cresce. Elas reduzem duplicação, fixam padrões e deixam o código mais legível em pontos onde antes existia lógica repetida. Ao centralizar decisões como IP real, leitura segura de headers, conversão de parâmetros e paginação, a manutenção fica mais rápida e menos arriscada. O resultado é um Django mais consistente, com menos variações ocultas entre endpoints. Esse tipo de base tende a melhorar a qualidade do projeto de forma contínua ao longo do tempo.