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
Foto do palestrante
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
Hexágono do domínio
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.
Árvore de decisão: das perguntas sobre cada parte do sistema ao padrão de lógica de negócio, ao padrão arquitetural e à estratégia de testes
A heurística
A árvore de decisão
Das perguntas sobre cada parte do sistema à lógica, à arquitetura e aos testes.
Capa do livro Aprenda Domain-Driven Design, de Vlad Khononov
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