Skip to content

9. Arquitectura en capas y acceso a datos

Los ejemplos anteriores mantenían sus datos en memoria. Una aplicación real los almacena en una base de datos y está organizada en capas (véase el diagrama de la introducción):

  • la capa web (vistas, formularios, plantillas): lee la solicitud, llama a la capa de negocio, selecciona la plantilla;
  • la capa de negocio: las reglas de negocio;
  • la capa DAO (Data Access Object): las consultas a la base de datos.

Cada capa conoce solo la capa inferior, y con la menor cantidad de detalles posible: la capa web desconoce las consultas, y la capa de negocio desconoce el HTML. Esta separación hace que cada capa sea más fácil de entender, probar y evolucionar. El ejemplo 28 aplica esto a la gestión de una lista de personas: es, a menor escala, la gestión de médicos y clientes del caso de estudio.

En [Python], el acceso a las bases de datos se organiza en varias capas:

  • el estándar DB-API 2.0 (PEP 249) de [Python] define una interfaz común para todos los SGBD: abrir una conexión, obtener un cursor, ejecutar un comando SQL y leer filas. Cada SGBD tiene su propio controlador: para [MySQL] (y [MariaDB]), [Django] recomienda [mysqlclient], una biblioteca escrita en C, instalada por el archivo de ejemplo [requirements.txt] ;
  • el ORM (Object-Relational Mapper) de [Django] asigna clases (modelos) a tablas de la base de datos y convierte las filas leídas en objetos. Gestiona las conexiones y las transacciones, genera por sí mismo los comandos SQL —adaptados a cada SGBD— y traduce los errores de cada controlador en excepciones comunes (una violación de una restricción de unicidad se convierte en una [IntegrityError], sea cual sea el SGBD). Sigue el llamado patrón Active Record: cada objeto sabe cómo guardarse ([person.save()]) y eliminarse ([person.delete()]), y cada clase tiene un gestor ([Person.objects]) desde el cual se envían las consultas. Este es el modelo de [Eloquent], el ORM de [Laravel]; [Doctrine], el ORM derivado de [Symfony], en cambio, siguió el patrón Data Mapper, en el que un objeto separado lee y guarda las entidades.

El ORM, derivado de [Django], forma parte de [Django] y es uno de sus componentes clave: la interfaz de administración, la aplicación de autenticación, las sesiones en base de datos y las vistas genéricas se apoyan en él. Es el equivalente de [JPA] y [Hibernate] en [Java], de [Entity Framework Core] para [C#], o de [SQLAlchemy] (usado con [Flask]) para [Python]. Observe una consecuencia de cómo funciona [Django]: de forma predeterminada, cada solicitud abre su propia conexión a la base de datos (en su primera solicitud SQL) y la cierra al terminar (con la señal [request_finished], ejemplo 24). El ajuste [CONN_MAX_AGE] permite que las conexiones permanezcan abiertas de una solicitud a otra (conexiones persistentes), y [Django] 5.1 agregó un verdadero pool de conexiones para [PostgreSQL]. Abrir una conexión a [MySQL] en la misma máquina toma apenas unos milisegundos.

Este ejemplo requiere un servidor [MySQL] 8.4 o posterior en ejecución (o [MariaDB] 10.11 o posterior; las versiones mínimas son las de [Django] 6.1): el apéndice explica cómo instalar uno con [Laragon].

9.1. Ejemplo 28: un sistema de gestión de personal en tres capas

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. La base de datos

La base de datos [dbpersons] se crea mediante el script SQL. Con [Laragon], se puede ejecutar, por ejemplo, en la herramienta [HeidiSQL] (menú Archivo / Ejecutar un archivo SQL), o desde la línea de comandos, en la carpeta del ejemplo:

mysql -u root < database/dbpersons.sql

El archivo [database/dbpersons.sql]:

-- base de datos del ejemplo 28: una sola tabla, [persons]
-- el script está escrito en 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,
  -- la versión de la fila, incrementada en cada modificación (véase la capa 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),
  -- dos personas no pueden tener el mismo nombre y apellido
  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);
  • línea 3: el script está escrito en [UTF-8]; esto se indica al servidor para que los acentos de los datos ([Pélissier]) permanezcan intactos;
  • línea 5: el conjunto de caracteres [utf8mb4] acepta todos los caracteres (acentos, emojis, etc.). La collation [utf8mb4_unicode_ci] compara las cadenas sin distinguir entre mayúsculas y minúsculas ni acentos: para [MySQL], [pelissier] y [Pélissier] son iguales;
  • línea 11: un número de versión, incrementado cada vez que se modifica la fila (véase «bloqueo optimista», más abajo);
  • línea 17: una restricción de unicidad con nombre: la base de datos no permite dos personas con el mismo nombre y apellido.

[Django] también puede crear las tablas por sí mismo, a partir de los modelos, mediante migraciones: archivos [Python] que describen, paso a paso, la creación y las modificaciones de cada tabla. El comando [python manage.py makemigrations] escribe estos archivos comparando los modelos con el estado descrito por las migraciones anteriores; [python manage.py migrate] las aplica a la base de datos. Esta es la forma estándar de trabajar con [Django]. Aquí mantenemos un script SQL, común a todas las versiones del caso de estudio, que muestra exactamente lo que contiene la base de datos. A la inversa, el comando [python manage.py inspectdb] escribe los modelos de una base de datos existente: un buen punto de partida, que conviene revisar.

9.1.2. La configuración: config/settings.py

# config/settings.py: la configuración del ejemplo 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 y DELETE mediante el campo oculto _method (véase el ejemplo 21)
    "config.middleware.MethodOverride",
]

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

# la BASE DE DATOS: el SGBD MySQL, en esta máquina (127.0.0.1), puerto 3306, la
# base de datos dbpersons, el usuario root sin contraseña (ajustes de 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",
]

# el LOG (logging): las sentencias SQL enviadas a la base de datos se escriben en la consola
# (el logger django.db.backends las emite solo en modo de depuración)
LOGGING = {
    "version": 1,
    "disable_existing_loggers": False,
    "handlers": {"console": {"class": "logging.StreamHandler"}},
    "loggers": {
        "django.db.backends": {"handlers": ["console"], "level": "DEBUG"},
    },
}
  • líneas 21–26: el middleware del ejemplo 21: protección anti-CSRF, mensajes flash y la simulación de los métodos PUT y DELETE (el archivo [config/middleware.py] es el del ejemplo 21);
  • líneas 32–42: la configuración [DATABASES] describe las bases de datos de la aplicación: en este caso, una sola, la base de datos [default]. [ENGINE] hace referencia al motor de [Django] para [MySQL] (que usa el controlador [mysqlclient]); seguido del nombre de la base de datos, el nombre de usuario y la contraseña (en blanco con la configuración de [Laragon]: si su servidor tiene contraseña, escríbala aquí), el nombre del host y el puerto. [OPTIONS] pasa al controlador el conjunto de caracteres para la comunicación con el servidor, que es el de la base de datos;
  • líneas 44–55: las plantillas, con [APP_DIRS] para las plantillas de formulario (ejemplo 18) y el procesador de contexto de mensajes (ejemplo 20);
  • líneas 67–74: el ajuste [LOGGING] configura el registro de [Python] (el módulo [logging]), que [Django] usa para sus mensajes. Sigue el formato del módulo [logging.config]: destinos ([handlers]: en este caso, la consola, mediante un [StreamHandler], que escribe en la salida de error) y registros ([loggers]), identificados por sus nombres. El registro [django.db.backends] recibe, solo en modo de depuración, cada comando SQL enviado a la base de datos, junto con su duración: lo enviamos a la consola en el nivel [DEBUG] (el más detallado). [disable_existing_loggers: False] conserva los registros que [Django] configura por sí mismo.

No hay nada más que configurar: los módulos de las tres capas se importan entre sí (la capa web importa la capa de negocio, que importa la capa DAO), y el ORM establece por sí mismo la conexión con la base de datos cuando la necesita.

9.1.3. El modelo Person: persons/models.py

# persons/models.py: una fila de la tabla [persons], un MODELO de Django

from django.db import models


# un modelo de Django: una clase que hereda de models.Model; cada atributo de clase
# que es un CAMPO (models.XxxField) corresponde a una columna de la tabla
class Person(models.Model):
    # la clave primaria, generada por la base de datos (AUTO_INCREMENT)
    id = models.AutoField(primary_key=True)
    # la VERSIÓN de la fila, incrementada en cada modificación (véase la capa DAO)
    version = models.IntegerField(default=0)
    # las columnas VARCHAR(30) e INT
    first_name = models.CharField(max_length=30)
    last_name = models.CharField(max_length=30)
    age = models.IntegerField()

    # Meta: la información sobre el propio modelo
    class Meta:
        # el nombre de la tabla (de forma predeterminada: persons_person, aplicación_modelo)
        db_table = "persons"
        # la tabla ya existe (script database/dbpersons.sql): Django no la crea
        managed = False
        # el orden de las filas cuando la consulta no especifica uno
        ordering = ["last_name", "first_name"]

    # el texto que representa al objeto (en la consola, los mensajes...)
    def __str__(self):
        return f"{self.first_name} {self.last_name}"

El archivo se llama [models.py]: es donde [Django] busca los modelos de una aplicación declarada en [INSTALLED_APPS].

  • línea 8: un modelo es una clase que hereda de [models.Model];
  • línea 10: la clave primaria, generada por la base de datos ([AutoField]: el [AUTO_INCREMENT] de [MySQL]). [Django] la agregaría automáticamente si no estuviera declarada (un campo [id], del tipo elegido por el ajuste [DEFAULT_AUTO_FIELD]); la incluimos aquí para mayor claridad. Es igual a [None] hasta que el objeto se ha insertado;
  • línea 12: la versión de la fila. El ORM de [Django] no tiene un bloqueo optimista integrado: lo escribe la capa DAO (véase más abajo);
  • líneas 14–16: las columnas. Cada atributo de clase que es un campo del modelo ([models.XxxField]) corresponde a la columna del mismo nombre; el tipo de columna se infiere del tipo de campo ([CharField]: [VARCHAR], de longitud [max_length]; [IntegerField]: [INT]). Como en un formulario (ejemplo 08), los campos se declaran como atributos de la clase, pero no son los mismos campos: los de [django.db.models] describen columnas, mientras que los de [django.forms] describen campos de formulario;
  • líneas 19–25: la clase interna [Meta] proporciona información sobre el propio modelo. [db_table]: el nombre de la tabla (de lo contrario, [Django] tomaría el nombre de la aplicación seguido del nombre del modelo, [persons_person]). [managed = False]: la tabla ya existe y [Django] no la gestiona: [makemigrations] no generará ninguna migración de creación ni de modificación para ella. [ordering]: el orden de las filas cuando una consulta no especifica ninguno;
  • líneas 28–29: el método [__str__] (ejemplo 12) devuelve el texto que representa al objeto: [str(p)], o [{p}] en una f-string, devuelve [Marie Pélissier].

Un modelo es una clase ordinaria a la que se pueden agregar métodos y propiedades. El ORM, por su parte, completa los atributos a partir de las filas leídas y genera los comandos SQL a partir de los atributos.

9.1.4. La capa DAO: persons/dao.py

# persons/dao.py: la capa DAO, consultas, ninguna regla de negocio

from django.db.models import F

from .models import Person


# SELECT ... FROM persons ORDER BY last_name, first_name. objects: el ADMINISTRADOR (manager) del modelo,
# desde donde parten todas las consultas; all() devuelve un QuerySet, una consulta que solo se
# ejecuta cuando se leen sus resultados (aquí, con list)
def list_all() -> list[Person]:
    return list(Person.objects.all())


# SELECT ... FROM persons WHERE id = ?; None si la persona no existe
def read(id: int) -> Person | None:
    return Person.objects.filter(id=id).first()


# una persona con los mismos nombre y apellido, distinta de [except_id]. filter: las
# condiciones WHERE; exclude: las condiciones 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 construye el objeto y lo guarda
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 = ?: la
# fila se modifica solo si su versión no ha cambiado desde que se leyó (BLOQUEO
# OPTIMISTA). F("version") designa la propia columna, en la sentencia SQL. update
# devuelve el número de filas modificadas: 0 si la versión cambió
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()

La capa DAO contiene solo consultas, sin reglas de negocio. Cada función comienza con [Person.objects], el administrador del modelo, del cual parten todas las consultas.

  • Líneas 11–12: [all()] devuelve un [QuerySet]: un objeto que describe una consulta sin ejecutarla. La consulta se envía a la base de datos solo cuando se necesitan sus resultados (aquí, cuando [list] los recorre): se dice que un [QuerySet] es diferido (lazy). Por lo tanto, se puede enriquecer antes de ejecutarlo ([filter], [exclude], [order_by]...), y cada método devuelve un nuevo [QuerySet]. El orden es el de [Meta.ordering];
  • Líneas 16–17: [filter(id=id)] agrega la condición [WHERE id = ...]; [first()] ejecuta la consulta, limitada a una fila ([LIMIT 1]), y devuelve el primer objeto, o [None]. ([Person.objects.get(id=id)] devolvería el objeto, pero lanzaría la excepción [Person.DoesNotExist] si no existiera, y el atajo [get_object_or_404], ejemplo 03, devolvería un error 404);
  • Líneas 22–23: varias condiciones en [filter] se combinan con [AND]; [exclude] agrega una condición [NOT]. Los parámetros con nombre se refieren a los campos ([first_name=...]); los sufijos especifican la comparación: [age__gte=18] ([>=]), [last_name__startswith="P"], [last_name__iexact=...] (sin distinguir mayúsculas de minúsculas)... Los valores se transmiten a la base de datos por separado y nunca se copian en el texto de la instrucción SQL, lo que hace imposible la inyección SQL;
  • líneas 27–28: [create] construye el objeto y lo guarda ([INSERT]); después de la inserción, el ORM almacena en el objeto el identificador generado por la base de datos. Esto equivale a [p = Person(first_name=..., ...)] seguido de [p.save()];
  • líneas 35–38: la actualización, con su bloqueo optimista. [update] actualiza todas las filas especificadas por el [QuerySet] en una sola operación, con un único comando [UPDATE], y devuelve el número de filas actualizadas. El filtro tiene dos condiciones: el identificador y la versión leída. Si otra solicitud ha modificado la fila entretanto —lo que hace cambiar su versión—, [UPDATE] no modifica ninguna fila y la función devuelve [False]. Este es el principio del bloqueo optimista: no se bloquea nada, pero se detectan las modificaciones concurrentes. La expresión [F("version") + 1] se refiere a la propia columna, en la instrucción SQL ([version = version + 1]): el cálculo lo realiza la base de datos, no [Python] a partir de un valor leído con anterioridad;
  • Líneas 42–43: la eliminación: [delete()] envía el [DELETE] de la fila del objeto.

A diferencia de [Doctrine], el ORM de [Django] no tiene un gestor que compare cada objeto leído con su estado original para guardar solo las columnas modificadas: [save()] reescribe todas las columnas del objeto (o las de su parámetro [update_fields]). Esto es más simple y más predecible; [update] permite escribir exactamente la instrucción deseada.

9.1.5. La capa de negocio: persons/business.py

# persons/business.py: la capa de NEGOCIO, las reglas de negocio, y solo ellas.
# Cada operación que escribe es una TRANSACCIÓN: confirmada (COMMIT) si la función
# termina normalmente, cancelada (ROLLBACK) si una excepción sale de ella

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)."


# una regla de negocio rechaza la operación; el mensaje está destinado al usuario
class BusinessError(Exception):
    pass


# los datos de una persona, tal como los pasa la capa web
@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(): el bloque se ejecuta en una transacción. La restricción de
# unicidad de la base de datos (dos adiciones simultáneas) lanza IntegrityError, que se convierte en un
# error de negocio
def add(data: PersonData) -> Person:
    try:
        with transaction.atomic():
            # regla 1: no puede haber dos personas con el mismo nombre y apellido
            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)
            # regla 2: un registro modificado mientras tanto por otra persona no se modifica
            if person.version != version:
                raise BusinessError(MODIFIED)
            if dao.namesake(data.first_name, data.last_name, id):
                raise BusinessError(NAMESAKE)
            # el UPDATE ... WHERE version = ... no modifica nada si otra solicitud ha
            # modificado la fila desde nuestra lectura
            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
  • líneas 12–14: mensajes de las reglas de negocio;
  • líneas 18–19: una clase de excepción propia de la capa de negocio: una regla de negocio rechaza la operación, y el mensaje de la excepción está destinado al usuario. Hereda de [Exception] sin añadirle nada; solo importa su nombre;
  • líneas 23–27: los datos de una persona, tal como la capa web los transmite a la capa de negocio: un objeto simple, independiente de [Django];
  • líneas 34–38: una persona inexistente es un error de negocio;
  • líneas 44–52: regla n.º 1: no puede haber dos personas con el mismo nombre y apellido. La regla se verifica antes de escribir en la base de datos, y se lanza una excepción [BusinessError] si no se cumple. Pero esta verificación no es suficiente: dos solicitudes simultáneas podrían verificar ambas que no hay homónimo y luego proceder las dos a insertar el registro. La restricción de unicidad de la base de datos rechaza entonces el segundo [INSERT], y el ORM lanza un [IntegrityError], que se transforma en el mismo [BusinessError]. La base de datos es la última línea de defensa. [raise ... from e] vincula la excepción original con la nueva: el registro mostrará ambas;
  • líneas 55–70: regla n.º 2: no modificar un registro que otra persona ha modificado entretanto. El formulario de actualización lleva la versión del registro leída (en un campo oculto); si difiere de la versión actual, el registro cambió desde que se mostró. Queda el caso en que la modificación concurrente ocurre entre la lectura de la línea 58 y el guardado de la línea 66: lo detecta el bloqueo optimista de la capa DAO. La función vuelve entonces a leer el registro de la persona para devolver la nueva versión;
  • líneas 73–77: la eliminación deja a la persona como «eliminada» para el mensaje de confirmación.

Toda operación que escribe datos se ejecuta dentro de una transacción: [transaction.atomic()], utilizado con [with] (un administrador de contexto, ejemplo 20), abre una transacción ([BEGIN]) al comienzo del bloque; si el bloque termina con normalidad (incluso con un [return]), la transacción se confirma ([COMMIT]); si se produce una excepción dentro del bloque, la transacción se revierte ([ROLLBACK]): no se conserva ninguno de los cambios realizados en el bloque, y la excepción sigue su camino. [transaction.atomic] también puede usarse como decorador de una función completa ([@transaction.atomic]). La capa de negocio determina así el alcance de las transacciones: una operación de negocio equivale a una transacción. Fuera de un bloque [atomic], el ORM funciona en modo «autocommit»: cada instrucción SQL se confirma de inmediato. Un [IntegrityError] se intercepta fuera del bloque [with]: dentro del bloque, la transacción ya no sería utilizable después del error. Las demás excepciones (como una falla de la base de datos o un error de programación) no son errores de negocio: siguen su curso.

9.1.6. La capa web

La entrada de datos se describe mediante un formulario (ejemplo 19):

# persons/forms.py: el formulario de una persona (véanse los ejemplos 18 y 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: el formulario de edición, que tiene un campo más
    def __init__(self, *args, edit=False, **kwargs):
        super().__init__(*args, **kwargs)
        for field in self.fields.values():
            field.widget.attrs["class"] = "form-control"
        # la versión: un campo oculto, solo en el formulario de edición
        if edit:
            self.fields["version"] = forms.IntegerField(widget=forms.HiddenInput)

    # los datos validados, para la capa de negocio; CharField ya eliminó los
    # espacios al inicio y al final de la entrada (opción strip, verdadera de forma predeterminada)
    def data_for_business(self) -> PersonData:
        d = self.cleaned_data
        return PersonData(d["first_name"], d["last_name"], d["age"])
  • líneas 9–17: los campos y sus restricciones, con mensajes en inglés;
  • líneas 20–26: un parámetro adicional del constructor, [edit], especificado por nombre ([PersonForm(request.POST, edit=True)]): un parámetro escrito después de [*args] solo puede pasarse por nombre. El formulario de actualización recibe un campo adicional, «version», en un campo oculto: [self.fields] es un diccionario al que se le puede agregar un campo;
  • líneas 30–32: los datos validados, en el formato esperado por la capa de negocio.

[Django] también puede generar un formulario a partir de un modelo (la clase [forms.ModelForm]): sus campos y sus restricciones se derivan de las columnas, y su método [save()] guarda el objeto. Esto es muy común. Sin embargo, el formulario modificaría entonces el modelo antes de que la capa de negocio haya verificado sus reglas. Un formulario separado mantiene las capas distintas: la capa web transmite a la capa de negocio solo datos validados.

# persons/views.py: la capa WEB; solo conoce la capa de negocio

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: el formulario vacío; POST: el formulario 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:
        # una regla de negocio rechaza: el formulario se muestra de nuevo, con la entrada y
        # el mensaje, al final de la 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: el formulario de edición, rellenado 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: el formulario de edición enviado; DELETE: la eliminación
@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:
            # ningún formulario por mostrar de nuevo: el error también viaja como mensaje 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")


# la página del formulario; un error de negocio: el código 422, como para un formulario inválido
# (véase el ejemplo 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)
  • línea 8: la capa de negocio, la única capa que conoce la capa web;
  • líneas 25–40: el alta, en tres pasos: validación del formulario (errores de entrada, ejemplo 19); llamada a la capa de negocio (reglas de negocio); y luego el esquema PRG, con un mensaje flash de éxito (ejemplo 20). Un [BusinessError] vuelve a mostrar el formulario, junto con los datos ingresados y el mensaje de la excepción ([str(e)]), que la plantilla mostrará al final de la página. Los errores de entrada y los errores de lógica de negocio se tratan así de la misma manera;
  • líneas 44–54: el formulario de edición, rellenado con la persona recuperada (parámetro [initial], ejemplo 18). Si la persona no existe, se redirige a la lista con un mensaje flash de error ([messages.error]). El formulario se envía con el método PUT (el campo oculto [_method], ejemplo 21), a la URL [/persons/<id>] ([reverse], con los parámetros de la ruta en [args]);
  • líneas 58–78: la vista de [/persons/<id>], para los métodos PUT (actualización, con el mismo esquema que el alta) y DELETE (eliminación, protegida por el token anti-CSRF, ejemplo 21). En la eliminación no hay formulario que volver a mostrar: cualquier error también se comunica mediante un mensaje flash;
  • líneas 83–86: la página del formulario. Un error de negocio se devuelve con el código 422, igual que un formulario no válido.

La capa web no contiene ni SQL ni reglas de negocio: traduce la solicitud en una llamada a la capa de negocio y el resultado en una página. Las rutas ([persons/urls.py]): [/persons] (la lista), [/persons/add], [/persons/<id>/edit] y [/persons/<id>] (PUT y DELETE).

Las plantillas:

<!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">
    {# los mensajes flash; tags: su nivel (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>
  • líneas 14–16: los mensajes flash en la parte superior de la página (ejemplo 20). Su etiqueta ([message.tags]: [success], [error]) determina su color;
  • línea 20: el bloque del pie de página, donde las páginas muestran sus errores (ejemplo 19);
  • líneas 22–23: la ventana de confirmación y su script (ejemplo 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 %}

La lista incluye los enlaces y botones del ejemplo 21, junto con su ventana de confirmación (los archivos [fragments/confirmation.html] y [static/js/app.js] son los del ejemplo 21). Los atributos [p.first_name], [p.last_name]... son los de los objetos [Person] leídos por el ORM. El bloque [{% empty %}] (ejemplo 14) procesa la lista vacía.

{% extends "layout.html" %}

{% block content %}
  <h1 class="h3">{{ title }}</h1>
  <form method="post" action="{{ action }}" novalidate style="max-width: 24rem">
    {% csrf_token %}
    {# la modificación se envía con el método PUT (ver ejemplo 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 }}
    {# la versión: un campo oculto, solo en el formulario de edición #}
    {% 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 %}

Una plantilla común para el alta y la modificación:

  • línea 8: el campo oculto [_method], solo para la modificación;
  • línea 13: el campo oculto de la versión, si existe en el formulario;
  • líneas 21–25: el error de negocio, al final de la página.

9.1.7. Ejecución

La lista de personas:

Image

Un formulario de alta completado incorrectamente: los errores de entrada los detecta la capa web.

Image

Un homónimo: la entrada es correcta, pero la capa de negocio rechaza el alta. Como la comparación la realiza la base de datos, esta ignora tanto las mayúsculas como los acentos: [marie pelissier] es un homónimo de [Marie Pélissier].

Image

Un alta exitosa:

Image

Para probar la regla n.º 2, abramos el mismo registro en dos pestañas. En la primera pestaña, cambiemos la edad y guardemos. En la segunda pestaña, que todavía muestra la versión anterior, modifiquemos también el registro:

Image

La eliminación, con su confirmación:

Image

Image

9.1.8. Los comandos SQL

Sigamos en la consola los comandos SQL de una modificación (se reinició el servidor y se recreó la base de datos). La visualización del formulario de modificación de la persona 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 línea muestra la duración del comando (en segundos), el comando SQL, sus parámetros ([args]) y el nombre de la base de datos ([alias]). Los dos primeros comandos sirven para establecer la conexión: [Django] consulta al servidor (su versión, su configuración) y luego establece el nivel de aislamiento de las transacciones ([READ COMMITTED]: una transacción ve los cambios confirmados por otras). A continuación viene la lectura por clave primaria, con su [ORDER BY] (correspondiente a [Meta.ordering]) y su [LIMIT 1] (correspondiente a [first()]). En el registro, los parámetros se copian en orden para que puedan leerse; originalmente se envían por separado ([args]). No hay transacción: una lectura aislada no la requiere. Se guarda el registro del maestro con una nueva edad:

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

(la conexión ya estaba abierta, como en la solicitud anterior). Dentro de una sola transacción ([BEGIN] ... [COMMIT]), se ven: la lectura del registro, la búsqueda de un homónimo, el [UPDATE] y luego la nueva lectura del registro. El [UPDATE] incrementa la versión ([version + 1]) y establece la condición del bloqueo optimista ([AND version = 0]). El servidor de desarrollo registra la solicitud como POST: así llegó, antes de que el middleware la convirtiera en PUT. Ahora enviemos el mismo formulario por segunda vez, siempre con la versión anterior:

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

La versión leída no es la del formulario: la capa de negocio lanzó un [BusinessError], que revirtió la transacción ([ROLLBACK]), y la página muestra «This record has been modified meanwhile: reload it.» De igual modo, el alta de un homónimo se detiene después de la búsqueda del homónimo, sin ningún [INSERT].