Configurar un Proyecto FastAPI con Estructura Modular

Concepto clave

La estructura modular en FastAPI transforma un proyecto monolítico en un conjunto de componentes independientes y reutilizables. Imagina construir una casa prefabricada: en lugar de hacer todo desde cero en un solo lugar, fabricas módulos como cocina, baño y dormitorios por separado, luego los ensamblas. Esto permite que diferentes equipos trabajen simultáneamente, facilita el mantenimiento y evita que un error en un área afecte todo el sistema.

En el desarrollo backend, una estructura modular organiza el código por responsabilidades: rutas, modelos de datos, lógica de negocio y configuración en directorios separados. Esto mejora la escalabilidad, ya que puedes agregar nuevas funcionalidades sin modificar el núcleo existente, y la seguridad, al aislar componentes críticos. Para proyectos avanzados, es esencial dominar esta arquitectura para construir APIs que puedan crecer con la demanda.

Cómo funciona en la práctica

Para configurar un proyecto FastAPI con estructura modular, sigue estos pasos:

1. Crea una carpeta principal para el proyecto, por ejemplo mi_api_avanzada.
2. Dentro, organiza subdirectorios como app para la lógica principal, core para configuración, api para endpoints, models para esquemas de datos, y services para lógica de negocio.
3. En app, coloca el archivo principal main.py que importa y monta los routers desde api.
4. Usa __init__.py en cada directorio para definir paquetes Python y facilitar las importaciones relativas.
5. Configura variables de entorno y settings en core para manejar diferentes entornos (desarrollo, producción).

Este enfoque separa claramente las preocupaciones, haciendo el código más testeable y mantenible. Por ejemplo, si necesitas agregar un nuevo módulo de autenticación, solo creas un directorio auth con sus propios routers y servicios, sin tocar el resto.

Código en acción

Aquí un ejemplo funcional de configuración inicial. Primero, la estructura de directorios:

mi_api_avanzada/
├── app/
│   ├── __init__.py
│   └── main.py
├── api/
│   ├── __init__.py
│   └── v1/
│       ├── __init__.py
│       ├── endpoints/
│       │   ├── __init__.py
│       │   ├── users.py
│       │   └── items.py
│       └── routers.py
├── core/
│   ├── __init__.py
│   └── config.py
├── models/
│   ├── __init__.py
│   └── schemas.py
└── requirements.txt

Ahora, el archivo principal app/main.py que monta los routers modularmente:

from fastapi import FastAPI
from api.v1.routers import api_router
from core.config import settings

app = FastAPI(title=settings.PROJECT_NAME, version=settings.VERSION)

# Montar todos los routers del API v1
app.include_router(api_router, prefix="/api/v1")

@app.get("/")
def read_root():
    return {"message": "API modular configurada exitosamente"}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)

Y un ejemplo de router en api/v1/routers.py que agrupa endpoints:

from fastapi import APIRouter
from api.v1.endpoints import users, items

api_router = APIRouter()
api_router.include_router(users.router, prefix="/users", tags=["users"])
api_router.include_router(items.router, prefix="/items", tags=["items"])

Errores comunes

• Importaciones circulares: Ocurre cuando dos módulos se importan mutuamente, causando errores en tiempo de ejecución. Para evitarlo, organiza las dependencias jerárquicamente y usa importaciones tardías si es necesario.
• Mala gestión de dependencias: Incluir todas las librerías en un solo archivo requirements.txt puede llevar a conflictos. Usa entornos virtuales y separa dependencias de desarrollo y producción.
• Ignorar el manejo de entornos: Configurar settings directamente en el código dificulta los despliegues. Utiliza archivos como .env y librerías como pydantic-settings para manejar variables por entorno.
• Sobrecarga de routers: Agrupar demasiados endpoints en un solo router hace el código difícil de mantener. Divide los routers por dominio funcional, como usuarios, items, pagos.
• No usar type hints: En proyectos avanzados, omitir anotaciones de tipos reduce la claridad y el soporte de herramientas como mypy. Siempre define schemas con Pydantic y usa type hints en funciones.

Checklist de dominio

• He organizado el proyecto en directorios separados por responsabilidad (api, core, models, etc.).
• Uso routers de FastAPI para agrupar endpoints relacionados y montarlos modularmente.
• Configuro variables de entorno con pydantic-settings para diferentes entornos.
• He evitado importaciones circulares mediante una estructura jerárquica clara.
• Los schemas de Pydantic están definidos en models/ y se reutilizan en endpoints.
• Manejo dependencias con un archivo requirements.txt o pyproject.toml actualizado.
• He probado que cada módulo funcione independientemente antes de integrarlo.

Refactorizar un proyecto FastAPI monolítico a estructura modular

En este ejercicio, tomarás un proyecto FastAPI existente con estructura plana y lo reorganizarás en una arquitectura modular. Sigue estos pasos:

1. Descarga o crea un proyecto básico FastAPI con un solo archivo main.py que contenga múltiples endpoints para usuarios y items.
2. Crea la estructura de directorios modular como se muestra en la lección, incluyendo app/, api/v1/endpoints/, core/, y models/.
3. Mueve la lógica de los endpoints a archivos separados en api/v1/endpoints/, definiendo routers individuales para usuarios e items.
4. Configura un archivo core/config.py usando pydantic-settings para manejar variables como el título y versión del proyecto.
5. Actualiza app/main.py para importar y montar los routers desde api/v1/routers.py.
6. Prueba la API ejecutando uvicorn app.main:app --reload y verifica que todos los endpoints funcionen correctamente.
7. Documenta los cambios en un README.md, explicando la nueva estructura y cómo agregar un nuevo módulo.

Pistas

• Usa el comando tree en terminal para visualizar la estructura de directorios después de crearla.
• Asegúrate de que cada directorio tenga un archivo __init__.py vacío para que Python lo reconozca como paquete.
• Prueba cada endpoint con herramientas como curl o Postman para validar que la refactorización no rompió funcionalidades.

Evalua tu comprension

Completa el quiz interactivo de arriba para ganar XP.

Práctica acompañada: Automatiza una tarea verificable

Python, archivos CSV y pruebas pequeñas. Usa este cuaderno como práctica complementaria de la ruta; el material original de la lección continúa siendo tu referencia.

Práctica: añade una salida reutilizable

Amplía el programa para escribir un nuevo archivo resumen.csv con encabezados categoria,total_centavos. No cambies resumir: añade una función que reciba su resultado y escriba la salida. Ejecuta dos veces y comprueba que no acumula filas duplicadas.

Después agrega una categoría con acento y una cantidad de dos dígitos. Comprueba que la codificación y la conversión siguen funcionando. Para automatizaciones de carpetas, aplica primero este patrón en una carpeta de prueba. Genera un informe de qué se cambiaría antes de habilitar operaciones de escritura sobre archivos importantes.

Comprueba tu entrega

Entrega el programa, la prueba, un ejemplo de entrada y un README con el comando exacto. Indica qué hace ante un archivo inexistente, una columna ausente o un valor inválido. La confiabilidad viene de conocer esos límites, no de añadir muchas funciones.

• Abrir el cuaderno ilustrado de 7 páginas
• Descargar PDF, ejercicios y plantillas de esta ruta
• Tutorial oficial de Python en español · recurso externo
• CS50 Python: funciones y variables · inglés · video complementario externo