Skip to content

9. Arquitetura em camadas e acesso a dados

Os exemplos anteriores mantinham seus dados na memória. Uma aplicação real os guarda em um banco de dados e se organiza em camadas (veja o diagrama na introdução):

  • a camada web (views, formulários, templates): lê a requisição, chama a camada de negócio, escolhe o template;
  • a camada de negócio: as regras de negócio;
  • a camada DAO (Data Access Object): as consultas ao banco de dados.

Cada camada conhece apenas a camada imediatamente abaixo e o mínimo possível de detalhes dela: a camada web desconhece as consultas, e a camada de negócio desconhece o HTML. Essa separação torna cada camada mais fácil de entender, testar e evoluir. O Exemplo 28 aplica isso ao gerenciamento de uma lista de pessoas: é, em menor escala, o gerenciamento de médicos e clientes do estudo de caso.

Em [Python], o acesso ao banco de dados se organiza em várias camadas:

  • o padrão DB-API 2.0 (PEP 249) do [Python] define uma interface comum para todos os SGBDs: abrir uma conexão, obter um cursor, executar um comando SQL e ler as linhas. Cada SGBD tem seu próprio driver: para o [MySQL] (e o [MariaDB]), o [Django] recomenda o [mysqlclient], uma biblioteca escrita em C, instalada pelo arquivo de exemplo [requirements.txt] ;
  • o ORM (Object-Relational Mapper) do [Django] mapeia classes (modelos) para tabelas do banco de dados e converte as linhas lidas em objetos. Ele gerencia conexões e transações, gera ele mesmo os comandos SQL — adaptados a cada SGBD — e traduz os erros de cada driver em exceções comuns (uma violação de restrição de unicidade se torna uma [IntegrityError], qualquer que seja o SGBD). Ele segue o padrão chamado Active Record: cada objeto sabe como se salvar ([person.save()]) e se excluir ([person.delete()]), e cada classe tem um manager ([Person.objects]) a partir do qual as consultas são feitas. Esse é o modelo do [Eloquent], o ORM do [Laravel]; o [Doctrine], o ORM derivado do [Symfony], por outro lado, seguiu o padrão Data Mapper, em que um objeto separado lê e salva as entidades.

O ORM, derivado do [Django], faz parte do [Django] e é um de seus componentes essenciais: a interface de administração, a aplicação de autenticação, as sessões em banco de dados e as views genéricas dependem dele. Ele é o equivalente do [JPA] e do [Hibernate] em [Java], do [Entity Framework Core] para [C#], ou do [SQLAlchemy] (usado com o [Flask]) para o [Python]. Observe uma consequência do funcionamento do [Django]: por padrão, cada requisição abre sua própria conexão com o banco de dados (na primeira requisição SQL) e a fecha ao terminar (no sinal [request_finished], exemplo 24). A configuração [CONN_MAX_AGE] permite que as conexões permaneçam abertas de uma requisição para outra (conexões persistentes), e o [Django] 5.1 acrescentou um verdadeiro pool de conexões para o [PostgreSQL]. Abrir uma conexão com o [MySQL] na mesma máquina leva apenas alguns milissegundos.

Este exemplo requer um servidor [MySQL] 8.4 ou posterior em execução (ou [MariaDB] 10.11 ou posterior; as versões mínimas são as do [Django] 6.1): o apêndice explica como instalar um usando o [Laragon].

9.1. Exemplo 28: um sistema de gerenciamento de pessoas em três camadas

28-layers/
├── config/
│   ├── middleware.py
│   ├── rendering.py
│   ├── settings.py
│   ├── urls.py
│   └── ...
├── database/
│   └── dbpersons.sql
├── persons/
│   ├── __init__.py
│   ├── business.py
│   ├── dao.py
│   ├── forms.py
│   ├── models.py
│   ├── urls.py
│   └── views.py
├── static/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── templates/
│   ├── forms/
│   │   └── field.html
│   ├── fragments/
│   │   └── confirmation.html
│   ├── persons/
│   │   ├── form.html
│   │   └── list.html
│   └── layout.html
└── manage.py

9.1.1. O banco de dados

O banco de dados [dbpersons] é criado pelo script SQL. Usando o [Laragon], você pode executá-lo, por exemplo, na ferramenta [HeidiSQL] (menu Arquivo / Executar arquivo SQL), ou pela linha de comando, a partir da pasta do exemplo:

mysql -u root < database/dbpersons.sql

O arquivo [database/dbpersons.sql]:

-- banco de dados do exemplo 28: uma única tabela, [persons]
-- o script é escrito em UTF-8
SET NAMES utf8mb4;
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
USE dbpersons;

CREATE TABLE persons (
  id INT NOT NULL AUTO_INCREMENT,
  -- a versão da linha, incrementada a cada modificação (veja camada DAO)
  version INT NOT NULL DEFAULT 0,
  first_name VARCHAR(30) NOT NULL,
  last_name VARCHAR(30) NOT NULL,
  age INT NOT NULL,
  PRIMARY KEY (id),
  -- duas pessoas não podem ter o mesmo nome e sobrenome
  CONSTRAINT unq_persons_first_name_last_name UNIQUE (first_name, last_name)
) ENGINE = InnoDB;

INSERT INTO persons (first_name, last_name, age) VALUES
  ('Marie', 'Pélissier', 42),
  ('Jacques', 'Bromard', 35),
  ('Philippe', 'Jandot', 58);
  • Linha 3: o script é escrito em [UTF-8]; isso é informado ao servidor para que os acentos dos dados ([Pélissier]) permaneçam intactos;
  • linha 5: o conjunto de caracteres [utf8mb4] aceita todos os caracteres (acentos, emojis etc.). A collation [utf8mb4_unicode_ci] compara strings sem distinguir letras maiúsculas e minúsculas nem acentos: para o [MySQL], [pelissier] e [Pélissier] são iguais;
  • linha 11: um número de versão, incrementado cada vez que a linha é modificada (veja “bloqueio otimista”, abaixo);
  • linha 17: uma restrição de unicidade nomeada: o banco de dados não permite duas pessoas com o mesmo nome e sobrenome.

[Django] também pode criar as tabelas por conta própria, a partir dos schemas, por meio de migrações: arquivos [Python] que descrevem, passo a passo, a criação e as modificações de cada tabela. O comando [python manage.py makemigrations] escreve esses arquivos comparando os schemas com o estado descrito pelas migrações anteriores; [python manage.py migrate] as aplica ao banco de dados. Essa é a maneira padrão de trabalhar com o [Django]. Mantemos um script SQL, comum a todas as versões do estudo de caso, que mostra exatamente o que o banco de dados contém. Inversamente, o comando [python manage.py inspectdb] escreve os schemas de um banco de dados existente: um bom ponto de partida, que vale a pena revisar.

9.1.2. A configuração: config/settings.py

# config/settings.py: a configuração do exemplo 28

from pathlib import Path

BASE_DIR = Path(__file__).resolve().parent.parent
DEBUG = True
SECRET_KEY = "django-insecure--7xp)7k(l6nl(owyoe0r99a@hufm3z2t@a(@w+va%5uw^%fbbm"
ALLOWED_HOSTS = []
LANGUAGE_CODE = "en"
TIME_ZONE = "Europe/Paris"
ROOT_URLCONF = "config.urls"
WSGI_APPLICATION = "config.wsgi.application"

INSTALLED_APPS = [
    "django.contrib.staticfiles",
    "django.contrib.messages",
    "django.forms",
    "persons",
]

MIDDLEWARE = [
    "django.middleware.csrf.CsrfViewMiddleware",
    "django.contrib.messages.middleware.MessageMiddleware",
    # PUT e DELETE por meio do campo oculto _method (veja o exemplo 21)
    "config.middleware.MethodOverride",
]

MESSAGE_STORAGE = "django.contrib.messages.storage.cookie.CookieStorage"

# o BANCO DE DADOS: o SGBD MySQL, nesta máquina (127.0.0.1), porta 3306, o
# banco dbpersons, o usuário root sem senha (configurações do Laragon)
DATABASES = {
    "default": {
        "ENGINE": "django.db.backends.mysql",
        "NAME": "dbpersons",
        "USER": "root",
        "PASSWORD": "",
        "HOST": "127.0.0.1",
        "PORT": "3306",
        "OPTIONS": {"charset": "utf8mb4"},
    },
}

TEMPLATES = [
    {
        "BACKEND": "django.template.backends.django.DjangoTemplates",
        "DIRS": [BASE_DIR / "templates"],
        "APP_DIRS": True,
        "OPTIONS": {
            "context_processors": [
                "django.contrib.messages.context_processors.messages",
            ],
        },
    },
]

FORM_RENDERER = "config.rendering.BootstrapRenderer"

STATIC_URL = "static/"
STATICFILES_DIRS = [
    BASE_DIR / "static",
    BASE_DIR.parent / "common" / "static",
]

# o LOG (logging): as instruções SQL enviadas ao banco de dados são escritas no console
# (o logger django.db.backends só as emite no modo de depuração)
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {"handlers": ["console"], "level": "DEBUG"},
    },
}
  • linhas 21–26: os middlewares do Exemplo 21: a proteção anti-CSRF, as mensagens flash e a simulação dos métodos PUT e DELETE (o arquivo [config/middleware.py] é o do Exemplo 21);
  • linhas 32–42: a configuração [DATABASES] descreve os bancos de dados da aplicação: neste caso, um só, o banco de dados [default]. [ENGINE] designa o engine do [Django] para o [MySQL] (que usa o driver [mysqlclient]); seguido do nome do banco de dados, do nome de usuário e da senha (deixada em branco com as configurações do [Laragon]: se o seu servidor tiver senha, informe-a aqui), do nome do host e da porta. [OPTIONS] passa ao driver o conjunto de caracteres da comunicação com o servidor — o conjunto de caracteres do banco de dados;
  • linhas 44–55: os templates, com [APP_DIRS] para os templates de formulário (exemplo 18) e o context processor de mensagens (exemplo 20);
  • linhas 67–74: a configuração [LOGGING] configura o log do [Python] (o módulo [logging]), que o [Django] usa para suas mensagens. Ela segue o formato do módulo [logging.config]: destinos ([handlers]: neste caso, o console, por meio de um [StreamHandler], que escreve na saída de erro) e logs ([loggers]), identificados por seus nomes. O log [django.db.backends] recebe, somente no modo de depuração, cada comando SQL enviado ao banco de dados, junto com sua duração: enviamos isso ao console no nível [DEBUG] (o mais detalhado). [disable_existing_loggers: False] preserva os logs que o [Django] configura por conta própria.

Não há mais nada a configurar: os módulos das três camadas se importam mutuamente (a camada web importa a camada de negócio, que importa a camada DAO), e a camada ORM estabelece ela mesma a conexão com o banco de dados quando precisa.

9.1.3. O modelo Person: persons/models.py

# persons/models.py: uma linha da tabela [persons], um MODELO Django

from django.db import models


# um modelo Django: uma classe que herda de models.Model; cada atributo de classe
# que é um CAMPO (models.XxxField) corresponde a uma coluna da tabela
class Person(models.Model):
    # a chave primária, gerada pelo banco de dados (AUTO_INCREMENT)
    id = models.AutoField(primary_key=True)
    # a VERSÃO da linha, incrementada a cada modificação (veja a camada DAO)
    version = models.IntegerField(default=0)
    # as colunas VARCHAR(30) e INT
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)
    age = models.IntegerField()

    # Meta: as informações sobre o próprio modelo
    class Meta:
        # o nome da tabela (por padrão: persons_person, aplicação_modelo)
        db_table = "persons"
        # a tabela já existe (script database/dbpersons.sql): o Django não a cria
        managed = False
        # a ordem das linhas quando a consulta não especifica uma
        ordering = ["last_name", "first_name"]

    # o texto que representa o objeto (no console, nas mensagens...)
    def __str__(self):
        return f"{self.first_name} {self.last_name}"

O arquivo se chama [models.py]: é onde o [Django] procura os modelos de uma aplicação declarada em [INSTALLED_APPS].

  • Linha 8: um modelo é uma classe que herda de [models.Model];
  • linha 10: a chave primária, gerada pelo banco de dados ([AutoField]: o [AUTO_INCREMENT] do [MySQL]). [Django] a acrescentaria automaticamente se ela não fosse declarada (um campo [id], do tipo escolhido pela configuração [DEFAULT_AUTO_FIELD]); nós a incluímos aqui para maior clareza. Ela é igual a [None] até que o objeto seja inserido;
  • linha 12: a versão da linha. O ORM do [Django] não tem bloqueio otimista embutido: ele é escrito pela camada DAO (veja abaixo);
  • linhas 14–16: as colunas. Cada atributo de classe que é um campo do modelo ([models.XxxField]) corresponde à coluna de mesmo nome; o tipo da coluna é inferido do tipo do campo ([CharField]: [VARCHAR], de tamanho [max_length]; [IntegerField]: [INT]). Como em um formulário (exemplo 08), os campos são declarados como atributos da classe, mas não são os mesmos campos: os de [django.db.models] descrevem colunas, enquanto os de [django.forms] descrevem campos de formulário;
  • linhas 19–25: a classe interna [Meta] fornece informações sobre o próprio modelo. [db_table]: o nome da tabela (caso contrário, o [Django] usaria o nome da aplicação seguido do nome do modelo, [persons_person]). [managed = False]: a tabela já existe, e o [Django] não a gerencia: [makemigrations] não gerará nenhuma migração de criação ou modificação para ela. [ordering]: a ordem das linhas quando uma consulta não especifica nenhuma;
  • linhas 28–29: o método [__str__] (Exemplo 12) retorna o texto que representa o objeto: [str(p)], ou [{p}] em uma f-string, retorna [Marie Pélissier].

Um modelo é uma classe comum à qual é possível acrescentar métodos e propriedades. O ORM, por sua vez, preenche os atributos com base nas linhas lidas e gera os comandos SQL a partir dos atributos.

9.1.4. A camada DAO: persons/dao.py

# persons/dao.py: a camada DAO, consultas, nenhuma regra de negócio

from django.db.models import F

from .models import Person


# SELECT ... FROM persons ORDER BY last_name, first_name. objects: o MANAGER do modelo,
# de onde partem todas as consultas; all() retorna um QuerySet, uma consulta que só é
# executada quando seus resultados são lidos (aqui, por list)
def list_all() -> list[Person]:
    return list(Person.objects.all())


# SELECT ... FROM persons WHERE id = ?; None se a pessoa não existir
def read(id: int) -> Person | None:
    return Person.objects.filter(id=id).first()


# uma pessoa com os mesmos nome e sobrenome, diferente de [except_id]. filter: as
# condições WHERE; exclude: as condições WHERE NOT
def namesake(first_name: str, last_name: str, except_id: int = 0) -> Person | None:
    return Person.objects.filter(first_name=first_name, last_name=last_name).exclude(id=except_id).first()


# INSERT INTO persons ...: create constrói o objeto e o salva
def insert(first_name: str, last_name: str, age: int) -> Person:
    return Person.objects.create(first_name=first_name, last_name=last_name, age=age)


# UPDATE persons SET ..., version = version + 1 WHERE id = ? AND version = ?: a
# linha só é modificada se sua versão não mudou desde que foi lida (BLOQUEIO
# OTIMISTA). F("version") designa a própria coluna, na instrução SQL. update
# retorna o número de linhas modificadas: 0 se a versão mudou
def update(id: int, version: int, first_name: str, last_name: str, age: int) -> bool:
    rows = Person.objects.filter(id=id, version=version).update(
        first_name=first_name, last_name=last_name, age=age, version=F("version") + 1)
    return rows == 1


# DELETE FROM persons WHERE id = ?
def delete(person: Person) -> None:
    person.delete()

A camada DAO contém apenas consultas, sem regras de negócio. Cada função começa com [Person.objects], o manager do modelo, de onde partem todas as consultas.

  • linhas 11–12: [all()] retorna um [QuerySet]: um objeto que descreve uma consulta sem executá-la. A consulta só é enviada ao banco de dados quando seus resultados são necessários (aqui, quando [list] os percorre): diz-se que um [QuerySet] é lazy (tardio). Ele pode, assim, ser refinado antes da execução ([filter], [exclude], [order_by]...), e cada método retorna um novo [QuerySet]. A ordem é a de [Meta.ordering];
  • linhas 16–17: [filter(id=id)] acrescenta a condição [WHERE id = ...]; [first()] executa a consulta, limitada a uma linha ([LIMIT 1]), e retorna o primeiro objeto, ou [None]. ([Person.objects.get(id=id)] retornaria o objeto, mas lançaria a exceção [Person.DoesNotExist] se ele não existisse, e o atalho [get_object_or_404], exemplo 03, retornaria um erro 404);
  • linhas 22–23: várias condições em [filter] são combinadas por [AND]; [exclude] acrescenta uma condição [NOT]. Os parâmetros nomeados se referem aos campos ([first_name=...]); sufixos especificam a comparação: [age__gte=18] ([>=]), [last_name__startswith="P"], [last_name__iexact=...] (sem diferenciar maiúsculas de minúsculas)... Os valores são transmitidos ao banco de dados separadamente e nunca são copiados para o texto do comando SQL, o que impossibilita a injeção de SQL;
  • linhas 27–28: [create] constrói o objeto e o salva ([INSERT]); após a inserção, o ORM guarda no objeto o id gerado pelo banco de dados. Equivale a [p = Person(first_name=..., ...)] seguido de [p.save()];
  • linhas 35–38: a atualização, com seu bloqueio otimista. [update] atualiza todas as linhas especificadas por [QuerySet] em uma única operação, com um único comando [UPDATE], e retorna o número de linhas atualizadas. O filtro tem duas condições: o id e a versão lida. Se outra requisição modificou a linha nesse meio-tempo — fazendo sua versão mudar —, [UPDATE] não modifica nenhuma linha, e a função retorna [False]. Esse é o princípio do bloqueio otimista: nada é bloqueado, mas as modificações concorrentes são detectadas. A expressão [F("version") + 1] se refere à própria coluna, no comando SQL ([version = version + 1]): o cálculo é feito pelo banco de dados, e não em [Python] com base em um valor lido anteriormente;
  • linhas 42–43: a exclusão: [delete()] envia o [DELETE] da linha do objeto.

Ao contrário do [Doctrine], o ORM do [Django] não tem um manager que compare cada objeto lido com seu estado original para salvar apenas as colunas modificadas: [save()] reescreve todas as colunas do objeto (ou as de seu parâmetro [update_fields]). Isso é mais simples e previsível; [update] permite escrever exatamente o comando desejado.

9.1.5. A camada de negócio: persons/business.py

# persons/business.py: a camada de NEGÓCIO, as regras de negócio, e somente elas.
# Cada operação que escreve é uma TRANSAÇÃO: confirmada (COMMIT) se a função
# termina normalmente, cancelada (ROLLBACK) se uma exceção a interrompe

from dataclasses import dataclass

from django.db import IntegrityError, transaction

from . import dao
from .models import Person

NAMESAKE = "A person already has these first and last names."
MODIFIED = "This record has been modified meanwhile: reload it."
UNKNOWN = "This person does not exist (anymore)."


# uma regra de negócio recusa a operação; a mensagem é destinada ao usuário
class BusinessError(Exception):
    pass


# os dados de uma pessoa, como a camada web os passa
@dataclass(frozen=True)
class PersonData:
    first_name: str
    last_name: str
    age: int


def list_all() -> list[Person]:
    return dao.list_all()


def read(id: int) -> Person:
    person = dao.read(id)
    if person is None:
        raise BusinessError(UNKNOWN)
    return person


# with transaction.atomic(): o bloco é executado em uma transação. A restrição de
# unicidade do banco de dados (duas adições simultâneas) lança IntegrityError, que vira um
# erro de negócio
def add(data: PersonData) -> Person:
    try:
        with transaction.atomic():
            # regra 1: não pode haver duas pessoas com os mesmos nome e sobrenome
            if dao.namesake(data.first_name, data.last_name):
                raise BusinessError(NAMESAKE)
            return dao.insert(data.first_name, data.last_name, data.age)
    except IntegrityError as e:
        raise BusinessError(NAMESAKE) from e


def update(id: int, version: int, data: PersonData) -> Person:
    try:
        with transaction.atomic():
            person = read(id)
            # regra 2: um registro modificado nesse meio-tempo por outra pessoa não é modificado
            if person.version != version:
                raise BusinessError(MODIFIED)
            if dao.namesake(data.first_name, data.last_name, id):
                raise BusinessError(NAMESAKE)
            # o UPDATE ... WHERE version = ... não modifica nada se outra requisição
            # modificou a linha desde a nossa leitura
            if not dao.update(id, version, data.first_name, data.last_name, data.age):
                raise BusinessError(MODIFIED)
            return read(id)
    except IntegrityError as e:
        raise BusinessError(NAMESAKE) from e


def delete(id: int) -> Person:
    with transaction.atomic():
        person = read(id)
        dao.delete(person)
        return person
  • linhas 12–14: as mensagens das regras de negócio;
  • linhas 18–19: uma classe de exceção específica da camada de negócio: uma regra de negócio rejeita a operação, e a mensagem da exceção se destina ao usuário. Ela herda de [Exception] sem acrescentar nada; só o seu nome importa;
  • linhas 23–27: os dados de uma pessoa, como transmitidos pela camada web à camada de negócio: um objeto simples, sem relação com o [Django];
  • linhas 34–38: uma pessoa inexistente é um erro de negócio;
  • linhas 44–52: regra nº 1: duas pessoas não podem ter o mesmo nome e sobrenome. A regra é verificada antes da gravação no banco de dados, e uma exceção [BusinessError] é lançada se ela não for respeitada. Mas essa verificação não é suficiente: duas requisições simultâneas poderiam verificar, ambas, que não há homônimo e depois inserir o registro. A restrição de unicidade do banco de dados rejeita então o segundo [INSERT], e o ORM lança uma [IntegrityError], que é transformada na mesma [BusinessError]. O banco de dados é a última linha de defesa. [raise ... from e] liga a exceção original à nova: o log mostrará as duas;
  • linhas 55–70: regra nº 2: não modificar um registro que foi modificado nesse meio-tempo por outra pessoa. O formulário de atualização carrega a versão do registro que foi lida (em um campo oculto); se ela difere da versão atual, o registro mudou desde que foi exibido. Resta o caso em que a modificação concorrente ocorre entre a leitura da linha 58 e a gravação da linha 66: ela é detectada pelo bloqueio otimista da camada DAO. A função relê então o registro da pessoa para retornar a nova versão;
  • linhas 73–77: a exclusão retorna a pessoa como “excluída”, para a mensagem de confirmação.

Toda operação que grava dados é executada dentro de uma transação: [transaction.atomic()], usado com [with] (um gerenciador de contexto, exemplo 20), abre uma transação ([BEGIN]) no início do bloco; se o bloco termina normalmente (mesmo com um [return]), a transação é confirmada ([COMMIT]); se uma exceção ocorre dentro do bloco, a transação é desfeita ([ROLLBACK]): nenhuma das alterações feitas no bloco é mantida, e a exceção segue seu caminho. [transaction.atomic] também pode ser usado como decorador de uma função inteira ([@transaction.atomic]). A camada de negócio determina, assim, o escopo das transações: uma operação de negócio equivale a uma transação. Fora de um bloco [atomic], o ORM opera em modo “autocommit”: cada comando SQL é confirmado imediatamente. Uma [IntegrityError] é interceptada fora do bloco [with]: dentro do bloco, a transação não seria mais utilizável após o erro. As demais exceções (como uma falha do banco de dados ou um erro de programação) não são erros de negócio: elas continuam seu processamento.

9.1.6. A camada web

A entrada de dados é descrita por um formulário (Exemplo 19):

# persons/forms.py: o formulário de uma pessoa (veja os exemplos 18 e 19)

from django import forms

from .business import PersonData


class PersonForm(forms.Form):
    first_name = forms.CharField(label="First name", max_length=30, error_messages={
        "required": "The first name is required.", "max_length": "30 characters at most."})
    last_name = forms.CharField(label="Last name", max_length=30, error_messages={
        "required": "The last name is required.", "max_length": "30 characters at most."})
    age = forms.IntegerField(label="Age", min_value=0, max_value=150, error_messages={
        "required": "The age is required.",
        "invalid": "The age must be an integer.",
        "min_value": "The age must be between 0 and 150.",
        "max_value": "The age must be between 0 and 150."})

    # edit=True: o formulário de edição, que tem um campo a mais
    def __init__(self, *args, edit=False, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            field.widget.attrs["class"] = "form-control"
        # a versão: um campo oculto, somente no formulário de edição
        if edit:
            self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)

    # os dados validados, para a camada de negócio; CharField já removeu os
    # espaços no início e no fim da entrada (opção strip, verdadeira por padrão)
    def data_for_business(self) -> PersonData:
        d = self.cleaned_data
        return PersonData(d["first_name"], d["last_name"], d["age"])
  • linhas 9–17: os campos e suas restrições, com mensagens em inglês;
  • linhas 20–26: um parâmetro adicional do construtor, [edit], especificado por nome ([PersonForm(request.POST, edit=True)]): um parâmetro escrito depois de [*args] só pode ser passado por nome. O formulário de atualização recebe um campo adicional, “version”, em um campo oculto: [self.fields] é um dicionário ao qual é possível acrescentar um campo;
  • linhas 30–32: os dados validados, no formato esperado pela camada de negócio.

O [Django] também pode gerar um formulário a partir de um modelo (a classe [forms.ModelForm]): seus campos e suas restrições são derivados das colunas, e seu método [save()] salva o objeto. Isso é muito comum. No entanto, o formulário modificaria então o modelo antes que a camada de negócio verificasse suas regras. Um formulário separado mantém as camadas distintas: a camada web transmite à camada de negócio apenas dados validados.

# persons/views.py: a camada WEB; ela só conhece a camada de negócio

from django.contrib import messages
from django.shortcuts import redirect, render
from django.urls import reverse
from django.views.decorators.http import require_GET, require_http_methods

from . import business
from .business import BusinessError
from .forms import PersonForm


@require_GET
def home(request):
    return redirect("persons_list")


@require_GET
def list_persons(request):
    return render(request, "persons/list.html", {"persons": business.list_all()})


# GET: o formulário vazio; POST: o formulário enviado
@require_http_methods(["GET", "POST"])
def add(request):
    title = "Add a person"
    action = reverse("persons_add")
    if request.method == "GET":
        return form_page(request, title, PersonForm(), action)
    form = PersonForm(request.POST)
    if not form.is_valid():
        return form_page(request, title, form, action, status=422)
    try:
        p = business.add(form.data_for_business())
    except BusinessError as e:
        # uma regra de negócio recusa: o formulário é exibido novamente, com a entrada e
        # a mensagem, no final da página
        return form_page(request, title, form, action, error=str(e))
    messages.success(request, f"{p} has been added.")
    return redirect("persons_list")


# GET: o formulário de edição, preenchido previamente
@require_GET
def edit(request, id):
    try:
        p = business.read(id)
    except BusinessError as e:
        messages.error(request, str(e))
        return redirect("persons_list")
    form = PersonForm(edit=True, initial={
        "first_name": p.first_name, "last_name": p.last_name, "age": p.age, "version": p.version})
    return form_page(request, "Edit a person", form,
                     reverse("persons_person", args=[id]), method="PUT")


# PUT: o formulário de edição enviado; DELETE: a exclusão
@require_http_methods(["PUT", "DELETE"])
def person(request, id):
    if request.method == "DELETE":
        try:
            p = business.delete(id)
            messages.success(request, f"{p} has been deleted.")
        except BusinessError as e:
            # nenhum formulário a exibir novamente: o erro também viaja como mensagem flash
            messages.error(request, str(e))
        return redirect("persons_list")
    title = "Edit a person"
    action = reverse("persons_person", args=[id])
    form = PersonForm(request.POST, edit=True)
    if not form.is_valid():
        return form_page(request, title, form, action, method="PUT", status=422)
    try:
        p = business.update(id, form.cleaned_data["version"], form.data_for_business())
    except BusinessError as e:
        return form_page(request, title, form, action, method="PUT", error=str(e))
    messages.success(request, f"{p} has been edited.")
    return redirect("persons_list")


# a página do formulário; um erro de negócio: o código 422, como para um formulário inválido
# (veja o exemplo 19)
def form_page(request, title, form, action, method=None, error=None, status=200):
    return render(request, "persons/form.html", {
        "title": title, "form": form, "action": action, "method": method,
        "error": error}, status=422 if error else status)
  • linha 8: a camada de negócio, a única camada conhecida pela camada web;
  • linhas 25–40: a adição, em três etapas: validação do formulário (erros de entrada, exemplo 19); a chamada à camada de negócio (regras de negócio); e depois o esquema PRG, com uma mensagem flash de sucesso (exemplo 20). Um [BusinessError] exibe o formulário novamente, junto com os dados digitados e a mensagem da exceção ([str(e)]), que o template exibirá no rodapé da página. Os erros de entrada e os erros de lógica de negócio são, assim, tratados da mesma forma;
  • linhas 44–54: o formulário de edição, pré-preenchido com a pessoa recuperada (parâmetro [initial], exemplo 18). Se a pessoa não existe, a view redireciona para a lista com uma mensagem flash de erro ([messages.error]). O formulário é enviado com o método PUT (o campo oculto [_method], Exemplo 21), para a URL [/persons/<id>] ([reverse], com os parâmetros de rota em [args]);
  • linhas 58–78: a view de [/persons/<id>], para os métodos PUT (atualização, seguindo o mesmo padrão da adição) e DELETE (exclusão, protegida pelo token anti-CSRF, Exemplo 21). Na exclusão, não há formulário para exibir novamente: qualquer erro também é transmitido em uma mensagem flash;
  • linhas 83–86: a página do formulário. Um erro de negócio é retornado com o código 422, como para um formulário inválido.

A camada web não contém nem SQL nem qualquer regra de negócio: ela traduz a requisição em uma chamada à camada de negócio e o resultado em uma página. As rotas ([persons/urls.py]): [/persons] (a lista), [/persons/add], [/persons/<id>/edit] e [/persons/<id>] (PUT e DELETE).

Os templates:

<!doctype html>
{% load static %}
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Persons</title>
  <link rel="stylesheet" href="{% static 'bootstrap/css/bootstrap.min.css' %}">
  <link rel="stylesheet" href="{% static 'css/styles.css' %}">
</head>
<body>
  <div class="container py-3" style="max-width: 44rem">
    {# as mensagens flash; tags: seu nível (success, error) #}
    {% for message in messages %}
      <div class="alert {% if message.tags == 'error' %}alert-danger{% else %}alert-success{% endif %}" role="status">{{ message }}</div>
    {% endfor %}
    <main>
      {% block content %}{% endblock %}
    </main>
    {% block page_bottom %}{% endblock %}
  </div>
  {% include "fragments/confirmation.html" %}
  <script src="{% static 'js/app.js' %}"></script>
</body>
</html>
  • linhas 14–16: as mensagens flash no topo da página (exemplo 20). Seu rótulo ([message.tags]: [success], [error]) determina sua cor;
  • linha 20: o bloco de rodapé, onde as páginas exibem seus erros (exemplo 19);
  • linhas 22–23: a janela de confirmação e seu script (exemplo 21).
{% extends "layout.html" %}

{% block content %}
  <div class="d-flex justify-content-between align-items-center mb-2">
    <h1 class="h3 mb-0">Persons</h1>
    <a class="btn btn-primary btn-sm" href="{% url 'persons_add' %}">Add</a>
  </div>
  <table class="table align-middle">
    <thead><tr><th>First name</th><th>Last name</th><th>Age</th><th></th></tr></thead>
    <tbody>
      {% for p in persons %}
        <tr>
          <td>{{ p.first_name }}</td>
          <td>{{ p.last_name }}</td>
          <td>{{ p.age }}</td>
          <td class="text-end">
            <a class="btn btn-sm btn-outline-primary" href="{% url 'persons_edit' p.id %}">Edit</a>
            <form method="post" class="d-inline" action="{% url 'persons_person' p.id %}"
                  data-confirmation="Delete {{ p.first_name }} {{ p.last_name }}?">
              {% csrf_token %}
              <input type="hidden" name="_method" value="DELETE">
              <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
            </form>
          </td>
        </tr>
      {% empty %}
        <tr><td colspan="4">No persons.</td></tr>
      {% endfor %}
    </tbody>
  </table>
{% endblock %}

A lista inclui os links e botões do Exemplo 21, junto com sua janela de confirmação (os arquivos [fragments/confirmation.html] e [static/js/app.js] são os do Exemplo 21). Os atributos [p.first_name], [p.last_name]... são os dos [Person] objects lidos pelo ORM. O bloco [{% empty %}] (Exemplo 14) trata a lista vazia.

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  <form method="post" action="{{ action }}" novalidate style="max-width: 24rem">
    {% csrf_token %}
    {# a modificação é enviada com o método PUT (veja o exemplo 21) #}
    {% if method %}<input type="hidden" name="_method" value="{{ method }}">{% endif %}
    {{ form.first_name.as_field_group }}
    {{ form.last_name.as_field_group }}
    {{ form.age.as_field_group }}
    {# a versão: um campo oculto, apenas no formulário de edição #}
    {% if form.version %}{{ form.version }}{% endif %}
    <div class="d-flex gap-2">
      <button class="btn btn-primary" type="submit">Save</button>
      <a class="btn btn-link" href="{% url 'persons_list' %}">Cancel</a>
    </div>
  </form>
{% endblock %}

{% block page_bottom %}
  {% if error %}
    <div class="error-area" role="alert">{{ error }}</div>
  {% endif %}
{% endblock %}

Um template comum à adição e à modificação:

  • linha 8: o campo oculto [_method], somente para a modificação;
  • linha 13: o campo oculto de versão, se ele existe no formulário;
  • linhas 21–25: o erro de negócio, no rodapé da página.

9.1.7. Execução

A lista de pessoas:

Image

Um formulário de adição preenchido incorretamente: os erros de entrada são detectados pela camada web.

Image

Um homônimo: a entrada está correta, mas a camada de negócio rejeita a adição. Como a comparação é feita pelo banco de dados, ela ignora tanto as letras maiúsculas quanto os acentos: [marie pelissier] é homônimo de [Marie Pélissier].

Image

Uma adição bem-sucedida:

Image

Para testar a regra nº 2, vamos abrir o mesmo registro em duas abas. Na primeira aba, vamos alterar a idade e salvar. Na segunda aba, que ainda exibe a versão antiga, vamos também modificar o registro:

Image

A exclusão, com sua confirmação:

Image

Image

9.1.8. Os comandos SQL

Vamos acompanhar no console os comandos SQL de uma modificação (o servidor foi reiniciado e o banco de dados foi recriado). A exibição do formulário de modificação da pessoa nº 1:

(0.000)
                SELECT VERSION(),
                       @@sql_mode,
                       @@default_storage_engine,
                       @@sql_auto_is_null,
                       @@lower_case_table_names,
                       CONVERT_TZ('2001-01-01 01:00:00', 'UTC', 'UTC') IS NOT NULL
            ; args=None; alias=default
(0.000) SET SESSION TRANSACTION ISOLATION LEVEL READ COMMITTED; args=None; alias=default
(0.000) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
[27/Sep/2026 19:45:19] "GET /persons/1/edit HTTP/1.1" 200 2460

Cada linha mostra a duração do comando (em segundos), o comando SQL, seus parâmetros ([args]) e o nome do banco de dados ([alias]). Os dois primeiros comandos servem para estabelecer a conexão: o [Django] consulta o servidor (sua versão, suas configurações) e depois define o nível de isolamento das transações ([READ COMMITTED]: uma transação vê as alterações confirmadas pelas outras). Em seguida vem a leitura por chave primária, com seu [ORDER BY] (correspondente a [Meta.ordering]) e seu [LIMIT 1] (correspondente a [first()]). No log, os parâmetros são copiados na ordem para que possam ser lidos; originalmente, são enviados separadamente ([args]). Não há transação: uma leitura isolada não precisa de uma. O registro principal é salvo com uma nova idade:

1
2
3
4
5
6
7
(0.000) BEGIN; args=None; alias=default
(0.001) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
(0.001) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE (`persons`.`first_name` = 'Marie' AND `persons`.`last_name` = 'Pélissier' AND NOT (`persons`.`id` = 1)) ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=('Marie', 'Pélissier', 1); alias=default
(0.000) UPDATE `persons` SET `first_name` = 'Marie', `last_name` = 'Pélissier', `age` = 43, `version` = (`persons`.`version` + 1) WHERE (`persons`.`id` = 1 AND `persons`.`version` = 0); args=('Marie', 'Pélissier', 43, 1, 1, 0); alias=default
(0.000) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
(0.001) COMMIT; args=None; alias=default
[27/Sep/2026 19:45:19] "POST /persons/1 HTTP/1.1" 302 0

(a conexão foi aberta, como na requisição anterior). Dentro de uma única transação ([BEGIN] ... [COMMIT]), vemos: a leitura do registro, a busca de um homônimo, o [UPDATE] e depois a releitura do registro. O [UPDATE] incrementa a versão ([version + 1]) e define a condição do bloqueio otimista ([AND version = 0]). O servidor de desenvolvimento registra a requisição como POST: foi assim que ela chegou, antes de o middleware convertê-la em PUT. Vamos agora enviar o mesmo formulário uma segunda vez, ainda com a versão antiga:

1
2
3
4
5
(0.000) BEGIN; args=None; alias=default
(0.000) SELECT `persons`.`id`, `persons`.`version`, `persons`.`first_name`, `persons`.`last_name`, `persons`.`age` FROM `persons` WHERE `persons`.`id` = 1 ORDER BY `persons`.`last_name` ASC, `persons`.`first_name` ASC LIMIT 1; args=(1,); alias=default
(0.000) ROLLBACK; args=None; alias=default
Unprocessable Content: /persons/1
[27/Sep/2026 19:45:19] "POST /persons/1 HTTP/1.1" 422 2562

A versão lida não é a do formulário: a camada de negócio lançou uma [BusinessError], que desfez a transação ([ROLLBACK]), e a página exibe “This record has been modified meanwhile: reload it.” Da mesma forma, a adição de um homônimo para após a busca do homônimo, sem um [INSERT].