Django

El Framework clásico de Python

Un marco de trabajo brinda una serie de mecanismos que pueden ser utiles en ciertos proyectos. Django deriva su implementación del patrón MVC (Model-View-Controller), haciendo uso de plantillas (Template), y cubre caracteríticas que facilitan el desarrollo de proyectos de software.

Personalmente, hasta 2025 no he sido un experto en Django, dado mi enfoque empresarial, puesto que con este Framework se parte inicialmene de un Monolito. Sin embargo, he encontrado que puede ser muy útil y se puede mitigar o suavizar sus desventajas aplicando un diseño a otro nivel (ejemplo EDA), es decir, en lugar de descartarlo hay casos de uso para proyectos vigentes (como veremos en ejercicio avanzando).

Veamos a continuacion como iniciar con Django teniendo Python instalado.

bash

mkdir project
cd project
python3 -m venv ./venv
source venv/bin/activate
pip install Django
django-admin startproject project
mv project run
cd run
python manage.py runserver

La linea correspondiente a source varia en Windows asi: source venv/Scripts/activate
La linea correspondiente a django-admin inicializa la carpeta project pero se renombra a run y luego se inicia el entorno de ejecucion

Cancelamos el entorno (usando CTRL+C) y luego ejecutamos la migracion para crear la base de datos asi:

bash

python manage.py migrate

Podemos crear un usuario para administrar el entorno de Django asi:

bash

python manage.py createsuperuser --username=myuser [email protected]

Para agregar un modulo de aplicacion se ejecuta lo siguiente:

bash

python manage.py startapp app

app corresponderia al nombre asignado a la aplicacion o modulo.
Se debe reportar esta aplicacion en el archivo settings.py (ubicado en la carpeta con el nombre del proyecto) dentro de la lista INSTALLED_APPS.

Django gestiona el modelo de datos y para sincronizar esto con la base de datos se realiza un proceso de migracion usando:

bash

python manage.py makemigrations

Para cerrar el entorno virtual ejecutas:

bash

deactivate

Podrías probar como alternativa el proyecto Django-Bolt, el cual se asemeja a Django combinando Rust

Comprendiendo la estructura clasica de Django

Cuando creas un proyecto con django-admin startproject, se genera una estructura de carpetas y archivos que sigue el patrón MVT (Model-View-Template), la variación de Django del clásico MVC (Model-View-Controller):

  ______
./ run /
├── manage.py
└── project/
    ├── __init__.py
    ├── settings.py
    ├── urls.py
    ├── asgi.py
    └── wsgi.py

project se refiere al nombre asignado al proyecto

Archivos clave del proyecto:

manage.py: Utilidad de línea de comandos para gestionar el proyecto (migraciones, servidor, usuarios, etc.)
settings.py: Configuración central del proyecto (base de datos, aplicaciones instaladas, middleware, plantillas, etc.)
urls.py: Define las rutas URL del proyecto y cómo se mapean a las vistas
wsgi.py / asgi.py: Puntos de entrada para servidores WSGI/ASGI (necesarios para despliegue en producción)

Al crear una aplicación con startapp app, se genera una estructura como la siguiente:

  ______
./ app /
├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── views.py
├── tests.py
├── migrations/
│   └── __init__.py
└── templates/

Es decir, Django contempla un proyecto del que se derivan aplicaciones, por lo que su estructura base es aumentada con cada aplicación o sección del sistema. Podría verse con un esquema como el siguiente:

  ______
./ run /
├── manage.py
├── project/
├── app1/
├── app2/
└── app3/

Archivos clave de la aplicación:

models.py: Define los modelos de datos (tablas de la base de datos) usando clases Python
views.py: Contiene la lógica de negocio y procesamiento de peticiones HTTP
admin.py: Configuración del panel de administración automático de Django
apps.py: Configuración de la aplicación
migrations/: Historial de cambios en los modelos para sincronizar con la base de datos
templates/: Directorio para plantillas HTML (capa de presentación)

Flujo de trabajo típico:

Definir modelos en models.py
Crear migraciones con makemigrations
Aplicar migraciones con migrate
Crear vistas en views.py
Configurar rutas en urls.py
Crear plantillas en templates/
Registrar modelos en admin.py para el panel de administración

Esta estructura modular permite separar responsabilidades y escalar aplicaciones de manera organizada.

Un poco de Django-Bolt

Django-Bolt es un módulo que busca combinar las facultades de Django con la velocidad de Rust.

Instalando Django-Bolt

Para instalar o agregar Django-Bolt (teniendo Django preparado en un espacio de trabajo) simplemente ejecutas:

bash

pip install django-bolt

API de ejemplo con Django-Bolt

Basados en el ejemplo del repositorio respectivo, podemos abrir un archivo api.py, bajo la carpeta project, colocando el siguiente contenido:

python

from django_bolt import BoltAPI
from django.contrib.auth import get_user_model
import msgspec

User = get_user_model()

api = BoltAPI()

class UserSchema(msgspec.Struct):
    id: int
    username: str

@api.get("/users/{user_id}")
async def get_user(user_id: int) -> UserSchema:
    user = await User.objects.aget(id=user_id)
    return {"id": user.id, "username": user.username}

@api.get es la anotación para API (Application Programming Interface) que simplifica la definición de rutas directamente.
msgspec es una librería para serializar datos que es más eficiente que stdlib de Python.

En el archivo de configuración project/settings.py se debe agregar django_bolt en la lista de componentes instalados (INSTALLED_APPS), por ejemplo:

python

INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'django_bolt',
]

Para ejecutar esta api usamos el comando:

bash

python manage.py runbolt

Esto habilita también las direcciones: http://127.0.0.1:8000/docs y http://127.0.0.1:8000/admin
Para cerrar el entorno virtual recuerda ejecutar: deactivate

Proyecto de inicio rápido con Django (Bolt)

En repositorio de mi proyecto OnMind-UCV he planteado un ejercicio dónde se habilita mecanismo para cargar curriculums vitae (CV). Se usa compatiblidad con Django REST Framework implementando Django-Bolt (en backend) así como React (en frontend) y almacenamiento tipo S3 (RustFS) para los archivos .pdf.

Puedes revisarlo y/o analizarlo desde GitHub. Como contexto se tendría lo siguiente...

Estructura del proyecto

  ______
./ ucv /
│
├── backend/                          # Django API (Django-Bolt)
│   ├── cvmanager/
│   │   ├── api.py                    # POST /api/upload + GET /api/cv-files endpoints (Django-Bolt)
│   │   ├── models.py                 # Modelo CV (firstName, lastName, email, country, url, cv_file)
│   │   ├── admin.py                  # Registro en admin de Django
│   │   └── apps.py
│   ├── ucv/
│   │   ├── settings.py               # Configuración global (S3, CORS, Django-Bolt)
│   │   ├── urls.py                   # Rutas raíz (admin)
│   │   └── wsgi.py
│   ├── manage.py
│   ├── requirements.txt
│   └── .env.example                  # Variables de entorno (S3, secrets)
│
├── frontend/                         # React + Vite
│   ├── src/
│   │   ├── App.jsx                   # Formulario con validación y notificaciones
│   │   ├── App.css                   # Estilos del formulario
│   │   ├── index.css                 # Estilos globales
│   │   └── main.jsx                  # Punto de entrada
│   ├── index.html
│   ├── vite.config.js                # Proxy /api -> Django
│   └── package.json
│
├── storage/                          # Folder para archivos de CV (PDF)
│
└── README.md

Si se usara Django REST Framework sería posible incluir archivos views.py, serializers.py y urls.py en cvmanager/, pero se sintetiza lógica en cvmanager/api.py usando Django-Bolt, un framework de API potenciado por Rust (el que reemplaza a Django REST Framework).

Prerrequisitos

Python 3.10+
Bun
Un servicio S3-compatible (RustFS, Floci, MinIO, AWS S3, etc.)

Inicio del servicio

Para inciar el servicio, se abre la carpeta backend y se ejecutan las sentencias para preparar el entorno virtual de Python y proyecto de Django. De modo semejante ocurre con el frontend, abriendo una terminal o sesión adicional.

1. Backend

bash

cd backend
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
python manage.py migrate
python manage.py runbolt --dev

Servicio disponible en http://localhost:8000. Documentación OpenAPI en http://localhost:8000/docs. Recuerda editar .env con las credenciales S3 correspondientes.

2. Frontend

bash

cd frontend
bun install
bun run dev

El frontend se abre en http://localhost:5173.
El proxy de Vite redirige las peticiones /api/* al backend en :8000.

Uso

Abrir http://localhost:5173
Completar: nombre, apellido, email, país (selector) y adjuntar CV (PDF)
Hacer clic en Enviar
Si es exitoso: notificación verde y el formulario se deshabilita
Si hay error: notificación roja con el detalle

Endpoint API

Método	Ruta	Descripción
POST	`/api/upload`	Sube un CV (multipart/form-data)
GET	`/api/cv-files`	Lista CVs

Campos del endpoint - POST

Campo	Tipo	Descripción
first_name	string	Nombre
last_name	string	Apellido
email	string	Correo electrónico
country	string	País
url	string	Sitio Web o LinkedIn
cv_file	file	Archivo PDF (máx. 10 MB)

Almacenamiento S3

Los archivos se guardan en un recipiente (bucket) S3 configurable vía variables de entorno.
Si has instalado el binario de RustFS, puedes lanzar el servicio ejecutando:

bash

rustfs server --address :9000 ./storage

Se el volumen, por ejemplo, carpeta storage. El puerto apunta a http://localhost:9000.

Recuerda crear el recipiente (bucket) antes de usar. Por ejemplo, usando la API de RustFS:

bash

curl --location --request PUT 'http://localhost:9000/ucv-bucket' \
--header 'X-Amz-Content-Sha256: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855' \
--header 'X-Amz-Date: 20250801T023519Z' \
--header 'Authorization: AWS4-HMAC-SHA256 Credential=H4xcBZKQfvJjEnk3zp1N/20250801/cn-east-1/s3/aws4_request, SignedHeaders=host;x-amz-content-sha256;x-amz-date, Signature=c2fb2ba5199a30ebcfa9976d0f35000ba274da3701327957e84ea0f3920288f2'

La API se obtiene con la consola web (UI) de RustFS desde contenedor.
También se puede crear el recipiente (bucket) desde de allí.

Django ​

Comprendiendo la estructura clasica de Django ​

Un poco de Django-Bolt ​

Instalando Django-Bolt ​

API de ejemplo con Django-Bolt ​

Proyecto de inicio rápido con Django (Bolt) ​

Estructura del proyecto ​

Prerrequisitos ​

Inicio del servicio ​

1. Backend ​

2. Frontend ​

Uso ​

Endpoint API ​

Campos del endpoint - POST ​

Almacenamiento S3 ​

Django

Comprendiendo la estructura clasica de Django

Un poco de Django-Bolt

Instalando Django-Bolt

API de ejemplo con Django-Bolt

Proyecto de inicio rápido con Django (Bolt)

Estructura del proyecto

Prerrequisitos

Inicio del servicio

1. Backend

2. Frontend

Uso

Endpoint API

Campos del endpoint - POST

Almacenamiento S3