Meetup Django SP · 25 de novembro
Django além do MTV
quando (não) complicar a arquitetura
Cássio Botaro · @cassiobotaro
Quem sou eu
Minha história com o Django
Cássio Botaro
Staff Software Engineer na Época Cosméticos
2011 / 2012 · Django 1.3 / 1.4
Primeira tentativa de aprender: muitas mudanças de uma versão para outra.
2013 / 2014 · Django 1.6 / 1.7
Migrações com South e, depois, a mudança para as migrations nativas.
2019 / 2020 · Django 3.0
Carta: módulo core de um projeto Django complexo, em processo de decomposição de domínios.
2024 · Django 5.1
Magalu Cloud: sistema de gerenciamento de clientes em Django.
O slogan do Django
“O framework web para perfeccionistas com prazos.”
The web framework for perfectionists with deadlines.
O problema
Vender ingressos parece simples
… até surgirem as demandas de negócio. Cada uma vira uma app Django.
MVP
Cadastrar eventos e palestrantes
Eventos
eventos/
Regras de negócio
Limitar vagas por lote e aceitar cupom de desconto
Inscrições
inscricoes/
Integrações
Cobrar no cartão e enviar o ingresso por e-mail
Checkout
checkout/
Dinheiro
Reembolsar todo mundo quando o evento for cancelado
Auditoria
Mostrar quanto cada organizador tem a receber, e quem mudou cada valor
Financeiro
financeiro/
Antes do código
Você conhece as partes do seu sistema?
A resposta muda quanto vale a pena investir em cada parte.
É o que faz o cliente escolher a sua empresa?
É necessário, mas não é o que diferencia o negócio?
Já existe uma solução pronta no mercado para isso?
A pergunta da palestra
Quanta arquitetura esta parte do sistema precisa?
Onde tudo começa
O MTV do Django
Model
Os dados e como eles são salvos.
class Evento(models.Model):
nome = models.CharField(max_length=200)
data = models.DateField()
Template
Como os dados aparecem para quem usa.
<h1>{{ evento.nome }}</h1>
<p>{{ evento.data|date:"d/m/Y" }}</p>
View
Recebe a requisição e liga os dois.
def detalhe(request, pk):
evento = get_object_or_404(Evento, pk=pk)
return render(request, "detalhe.html", {"evento": evento})
Eventos
É o diferencial do negócio?
Não: necessário, mas comum
Tem regras ou dados complexos?
Não: valida, salva e pronto
Mais de um modelo de persistência?
Não
Caminho
Lógica: Transaction script
Arquitetura: 3 camadas
Testes: pirâmide invertida
Eventos
Transaction script
“Organiza a lógica de negócio em procedimentos, em que cada procedimento trata uma única requisição vinda da apresentação.”
— Martin Fowler, Patterns of Enterprise Application Architecture (2002)
O que é
Cada operação é uma função que roda do início ao fim, dentro de uma transação.
Por que aqui
Eventos é necessário, mas comum: não há regra de negócio para proteger.
3 camadas
Um só modelo de persistência: Model, Template e View bastam.
Eventos
Cadastro de eventos: um script só
Sem regra de negócio: valida, salva e redireciona.
# eventos/views.py
@require_POST
@transaction.atomic
def criar_evento(request):
form = EventoForm(request.POST)
if not form.is_valid():
return render(request, "eventos/novo.html", {"form": form})
evento = form.save()
for nome in request.POST.getlist("palestrantes"):
Palestrante.objects.create(evento=evento, nome=nome)
return redirect("eventos:detalhe", pk=evento.pk)
Por padrão, cada save do Django é gravado na hora: o @transaction.atomic torna o script tudo ou nada.
Eventos
Testes: pirâmide invertida
Pouca lógica para isolar: o teste que vale é o de ponta a ponta.
@pytest.mark.django_db
def test_cria_evento_com_palestrantes(client):
palestrantes = ["Ana", "Bruno"]
resp = client.post(reverse("eventos:novo"), {
"nome": "Meetup Django",
"data": "2026-12-05",
"palestrantes": palestrantes,
})
assert resp.status_code == HTTPStatus.FOUND
assert Palestrante.objects.filter(
evento__nome="Meetup Django").count() == len(palestrantes)
Hora de sair daqui: a mesma regra começa a aparecer em várias views.
Inscrições
É o diferencial do negócio?
Não: necessário, mas comum
Tem regras ou dados complexos?
Sim: lotes, cupons e vagas
Mais de um modelo de persistência?
Não
Caminho
Lógica: Active Record
Arquitetura: 4 camadas
Testes: diamante
Inscrições
O Django já é Active Record
“Um objeto que envolve uma linha de uma tabela ou view do banco, encapsula o acesso ao banco e adiciona lógica de domínio sobre esses dados.”
— Martin Fowler, Patterns of Enterprise Application Architecture (2002)
Envolve uma linha
Lote.objects.get(pk=1)
Cada objeto Lote é uma linha da tabela.
Encapsula o banco
lote.save()
O próprio objeto sabe se buscar e se salvar.
Adiciona lógica
lote.tem_vaga()
A regra mora junto dos dados: é aí que nascem os fat models.
Inscrições
Fat models: a regra mora no model
Com as primeiras regras de negócio, os models engordam.
# inscricoes/models.py
class Lote(models.Model):
evento = models.ForeignKey(Evento, on_delete=models.CASCADE)
preco = models.DecimalField(max_digits=8, decimal_places=2)
vagas = models.PositiveIntegerField()
vendidos = models.PositiveIntegerField(default=0)
def tem_vaga(self) -> bool:
return self.vendidos < self.vagas
def preco_com(self, cupom) -> Decimal:
if cupom and cupom.vale_para(self.evento):
return self.preco * (1 - cupom.desconto)
return self.preco
Inscrições
Services: regras que coordenam models
Para orquestrar as regras de vários models, entram os services.
# inscricoes/services.py
@transaction.atomic
def inscrever(participante, lote_id, cupom=None):
lote = Lote.objects.select_for_update().get(pk=lote_id)
if not lote.tem_vaga():
raise LoteEsgotado(lote)
lote.vendidos += 1
lote.save(update_fields=["vendidos"])
return Inscricao.objects.create(
participante=participante,
lote=lote,
valor=lote.preco_com(cupom),
)
Inscrições
Agora são 4 camadas
Apresentação
Views, templates e forms
Serviço
services.py orquestra cada operação (nova)
Lógica de negócio
Models com regras: os fat models
Acesso a dados
ORM do Django
Inscrições
Testes: diamante
A maioria dos testes é de integração: a regra depende do ORM e do banco.
@pytest.mark.django_db
def test_nao_vende_alem_das_vagas(evento, participante):
lote = Lote.objects.create(evento=evento, preco=100, vagas=1, vendidos=1)
with pytest.raises(LoteEsgotado):
inscrever(participante, lote.id)
@pytest.mark.django_db
def test_cupom_reduz_o_valor(evento, participante, cupom_10):
lote = Lote.objects.create(evento=evento, preco=100, vagas=10)
inscricao = inscrever(participante, lote.id, cupom=cupom_10)
assert inscricao.valor == 90
Hora de sair daqui: muitos models, integrações e testes que dependem do banco.
Checkout
É o diferencial do negócio?
Sim: é onde a venda acontece
Envolve dinheiro ou auditoria?
Não aqui: a cobrança é do gateway
Mais de um modelo de persistência?
Não
Caminho
Lógica: Domain model
Arquitetura: portas e adaptadores
Testes: pirâmide
Checkout
Domain model
“Um modelo de objetos do domínio que incorpora tanto comportamento quanto dados.”
— Martin Fowler, Patterns of Enterprise Application Architecture (2002)
O que é
As regras vivem em objetos do domínio, junto dos dados que elas protegem.
No checkout
O próprio Pedido valida se pode ser pago e confirma o pagamento.
Portas e adaptadores
O domínio é Python puro; o Django fica na borda, nos adaptadores.
Checkout
Por que portas e adaptadores aqui?
“Permitir que uma aplicação seja conduzida igualmente por usuários, programas, testes automatizados ou scripts…”
— Alistair Cockburn, “Hexagonal Architecture” (2005)
É o diferencial
As regras do checkout são as que mais importam e as que mais mudam.
Depende de fora
Gateway e e-mail são fornecedores que podem ser trocados.
Teste isolado
A regra precisa rodar sem banco, sem gateway e sem o Django.
Por isso separamos a regra de tudo o que é externo, inclusive do Django.
Checkout
O domínio no centro, o Django na borda
Entrada
View Django
Comando de management
Domínio
Pedido e regras de checkout, em Python puro.
RepositorioPedidos
GatewayPagamento
Notificador
Saída
ORM: PedidoModel
Gateway de pagamento
E-mail
Portas são interfaces do domínio. Adaptadores são as implementações com Django e serviços externos.
Checkout
O domínio é Python puro
Nenhum import de Django: as regras rodam e são testadas sem banco.
# checkout/dominio.py
@dataclass
class Pedido:
id: UUID
total: Decimal
status: str = "aberto"
transacao: str | None = None
def garantir_que_pode_pagar(self) -> None:
if self.status != "aberto":
raise PedidoJaProcessado(self.id)
def confirmar_pagamento(self, transacao: str) -> None:
self.garantir_que_pode_pagar()
self.status, self.transacao = "pago", transacao
Checkout
Portas e caso de uso
# checkout/portas.py
class RepositorioPedidos(Protocol):
def obter(self, pedido_id: UUID) -> Pedido: ...
def salvar(self, pedido: Pedido) -> None: ...
class GatewayPagamento(Protocol):
def cobrar(self, valor: Decimal, token: str) -> str: ...
# checkout/casos_de_uso.py
def pagar(pedido_id, token, pedidos: RepositorioPedidos,
gateway: GatewayPagamento) -> Pedido:
pedido = pedidos.obter(pedido_id)
pedido.garantir_que_pode_pagar() # falha antes de cobrar
transacao = gateway.cobrar(pedido.total, token)
pedido.confirmar_pagamento(transacao)
pedidos.salvar(pedido)
return pedido
Checkout
Adaptadores implementam as portas
# checkout/adaptadores/orm.py
class PedidosDjango:
def obter(self, pedido_id):
try:
m = PedidoModel.objects.get(pk=pedido_id)
except PedidoModel.DoesNotExist:
raise PedidoNaoEncontrado(pedido_id)
return Pedido(id=m.pk, total=m.total, status=m.status, transacao=m.transacao)
def salvar(self, pedido):
PedidoModel.objects.filter(pk=pedido.id).update(
status=pedido.status, transacao=pedido.transacao)
# checkout/views.py
@require_POST
def pagar_view(request, pedido_id):
try:
pagar(pedido_id, request.POST["token"], PedidosDjango(), GatewayHttp())
except PedidoJaProcessado:
messages.info(request, "Este pedido já estava pago.")
return redirect("checkout:obrigado", pedido_id=pedido_id)
Checkout
O Django vira detalhe
Trocando o adaptador de cada porta, a mesma regra roda em outro lugar.
# hoje: ORM do Django e o gateway atual
pagar(pedido_id, token, PedidosDjango(), GatewayHttp())
# outro provedor de pagamento: só um adaptador novo
pagar(pedido_id, token, PedidosDjango(), OutroGateway())
# outro serviço, sem Django: a regra vai junto
pagar(pedido_id, token, PedidosSQL(), GatewayHttp())
Checkout
Pirâmide: fakes na base dos testes
Com mais regras, testes rápidos com fakes viram a base.
class GatewayFake:
def cobrar(self, valor, token):
return "tx-fake"
class PedidosEmMemoria(dict):
def obter(self, pedido_id): return self[pedido_id]
def salvar(self, pedido): self[pedido.id] = pedido
def test_pagamento_confirma_pedido():
pedido = Pedido(id=uuid4(), total=Decimal("100"))
pedidos = PedidosEmMemoria({pedido.id: pedido})
pagar(pedido.id, "tok", pedidos, GatewayFake())
assert pedido.status == "pago"
Financeiro
É o diferencial do negócio?
Sim
Envolve dinheiro ou auditoria?
Sim: reembolsos, repasses e extrato
Caminho
Lógica: Event sourcing
Arquitetura: CQRS
Testes: pirâmide
Financeiro
Event sourcing
“Capturar todas as mudanças no estado de uma aplicação como uma sequência de eventos.”
— Martin Fowler, “Event Sourcing” (2005)
O que é
Em vez de só o estado atual, guardamos cada fato que aconteceu, em ordem.
Por que aqui
Dinheiro e auditoria: precisamos saber quem mudou o quê, e quando.
Com CQRS
Os eventos são a escrita; as tabelas de leitura são montadas a partir deles.
Financeiro
CQRS: escrita e leitura separadas
“…dividir esse modelo conceitual em modelos separados para atualização e exibição…”
— Martin Fowler, “CQRS” (2011)
Lado da escrita
Lado da leitura
Comando
solicitar_reembolso()
Valida a regra e gera o evento.
Eventos
EventoFinanceiro
Fatos imutáveis, em ordem.
Projeção
projetar()
Transforma fatos em tabelas.
Leitura
SaldoOrganizador
Pronta para extrato e dashboards.
As tabelas de leitura podem ser apagadas e recriadas a partir dos eventos.
Financeiro
Como o SaldoOrganizador é construído
Eventos gravados · escrita
#1 PagamentoAprovado
org-1 · 100,00
#2 PagamentoAprovado
org-1 · 150,00
#3 PagamentoAprovado
org-2 · 80,00
#4 ReembolsoEmitido
org-1 · 100,00
projetar()
pagamento soma
reembolso subtrai
SaldoOrganizador · leitura
org-1
100,00
→ 250,00
→ 150,00
org-2
80,00
O extrato lê só o último valor de cada organizador, em verde: nada é recalculado na consulta.
Financeiro
Eventos: o estado é a soma dos fatos
Nada é apagado ou sobrescrito. O histórico é a auditoria.
# financeiro/dominio.py (Python puro)
class TipoEvento(StrEnum):
PAGAMENTO_APROVADO = "PagamentoAprovado"
REEMBOLSO_EMITIDO = "ReembolsoEmitido"
# financeiro/models.py
class EventoFinanceiro(models.Model):
pedido_id = models.UUIDField(db_index=True)
tipo = models.CharField(max_length=40, choices=[(t.value, t.name) for t in TipoEvento])
dados = models.JSONField()
ocorrido_em = models.DateTimeField(auto_now_add=True)
def save(self, *args, **kwargs):
if not self._state.adding:
raise ValueError("Eventos não são alterados")
super().save(*args, **kwargs)
Financeiro
A regra decide a partir do histórico
# financeiro/casos_de_uso.py
@transaction.atomic
def solicitar_reembolso(pedido_id, motivo):
historico = EventoFinanceiro.objects.filter(pedido_id=pedido_id).order_by("id")
pedido = Pedido.a_partir_de(historico) # reconstrói o estado
novo = pedido.reembolsar(motivo) # valida e devolve o evento
evento = EventoFinanceiro.objects.create(pedido_id=pedido_id, **novo)
projetar(evento) # atualiza a leitura
# financeiro/dominio.py
class Pedido:
def reembolsar(self, motivo):
if self.reembolsado:
raise JaReembolsado(self.id)
return {"tipo": TipoEvento.REEMBOLSO_EMITIDO,
"dados": {"valor": str(self.pago), "motivo": motivo,
"organizador_id": str(self.organizador_id)}}
Financeiro
A projeção alimenta a leitura
Roda após gravar cada evento: na mesma transação ou de forma assíncrona.
# financeiro/projecoes.py
def projetar(evento):
saldo, _ = SaldoOrganizador.objects.select_for_update().get_or_create(
organizador_id=evento.dados["organizador_id"])
valor = Decimal(evento.dados["valor"])
if evento.tipo == TipoEvento.PAGAMENTO_APROVADO:
saldo.valor += valor
elif evento.tipo == TipoEvento.REEMBOLSO_EMITIDO:
saldo.valor -= valor
saldo.save(update_fields=["valor"])
# extrato: só leitura, sem regra
SaldoOrganizador.objects.filter(organizador_id=org_id)
Financeiro
Testes: dado, quando, então
Dado um histórico, quando chega um comando, então: novo evento ou erro.
def test_nao_reembolsa_duas_vezes():
# dado
pedido = Pedido.a_partir_de([
pagamento_aprovado(valor="100.00"),
reembolso_emitido(valor="100.00"),
])
# quando / então
with pytest.raises(JaReembolsado):
pedido.reembolsar("pedido duplicado")
def test_reembolso_gera_evento():
pedido = Pedido.a_partir_de([pagamento_aprovado(valor="100.00")])
evento = pedido.reembolsar("evento cancelado")
assert evento["tipo"] == TipoEvento.REEMBOLSO_EMITIDO
Fechamento
Juntando as peças
Quatro módulos, quatro arquiteturas, um mesmo projeto Django.
Resumo
Uma arquitetura por módulo
Módulo
Resposta
Lógica
Arquitetura
Testes
Eventos
Comum, sem regras complexas
Transaction script
3 camadas
Pirâmide invertida
Inscrições
Comum, com regras complexas
Active Record
4 camadas
Diamante
Checkout
Diferencial, sem dinheiro
Domain model
Portas e adaptadores
Pirâmide
Financeiro
Diferencial, com dinheiro
Event sourcing
CQRS
Pirâmide
Resumo
Três formas de distribuir os testes
Ponta a ponta
Integração
Unitário
Pirâmide invertida
Eventos
Pouca lógica: o que vale é testar de ponta a ponta.
Diamante
Inscrições
A regra depende do ORM: a maioria é de integração.
Pirâmide
Checkout e Financeiro
Domínio isolado: muitos testes unitários rápidos.
A heurística
A árvore de decisão
Das perguntas sobre cada parte do sistema à lógica, à arquitetura e aos testes.
Aprenda Domain-Driven Design
Vlad Khononov · Alta Books
Original: “Learning Domain-Driven Design” (O’Reilly, 2021).
Simples onde dá,
sofisticado onde importa.
Perfeccionistas, mas com prazo.
Obrigado! Perguntas?
Cássio Botaro · @cassiobotaro