Clean Architecture en FastAPI

Objetivo

Construir aplicaciones mantenibles, testeables y preparadas para crecer sin reescribir el código.

main.py
routes.py
models.py
database.py
utils.py

Después de unos meses...

main.py     4.000 líneas
services.py  7.000 líneas
utils.py     2.500 líneas

Separar responsabilidades para que cada capa tenga un único propósito.

El dominio nunca depende de FastAPI, SQLAlchemy o PostgreSQL.

Regla principal

Las dependencias siempre apuntan hacia el dominio.

Nunca al revés.

app/
├── domain/
│   ├── entities/
│   ├── repositories/
│   ├── value_objects/
│   └── exceptions/
│
├── application/
│   ├── use_cases/
│   ├── dto/
│   ├── services/
│   └── interfaces/
│
├── infrastructure/
│   ├── database/
│   ├── repositories/
│   ├── external/
│   ├── cache/
│   └── messaging/
│
├── presentation/
│   ├── api/
│   ├── dependencies/
│   └── middleware/
│
├── config/
│
└── main.py

Aquí ocurre la lógica del negocio.

Cada caso de uso representa una acción del negocio.

• Crear usuario
• Registrar pedido
• Aprobar préstamo
• Procesar pago

Aquí conectamos el mundo real.

Si mañana migramos a MongoDB, solo cambia la implementación. El dominio permanece igual.

• PostgreSQL
• MongoDB
• Redis
• Kafka
• RabbitMQ
• AWS S3
• OpenAI
• Claude
• Stripe

Un endpoint solo:

recibe datos llama un caso de uso devuelve una respuesta

Nunca contiene lógica de negocio.

Cada componente tiene una única responsabilidad.

La arquitectura facilita integrar nuevos servicios sin modificar el núcleo.

Agregar una integración implica crear un nuevo adaptador, no reescribir el dominio.

Gracias a la inversión de dependencias podemos sustituir implementaciones reales por mocks.

• FastAPI para la capa de presentación.
• Pydantic v2 para validación y DTOs.
• SQLAlchemy 2.0 para persistencia.
• Alembic para migraciones.
• PostgreSQL como base de datos principal.
• Redis para caché y sesiones.
• Celery o ARQ para tareas asíncronas.
• Docker y Docker Compose para despliegue.
• Pytest para pruebas automatizadas.
• Ruff, Black y MyPy para calidad del código.