Cómo construir un esqueleto funcional de backend FastAPI en un par de minutos

Cada vez que inicio un nuevo proyecto FastAPI, me quedo atrapado en un Día de la Marmota. Necesito configurar la estructura de directorios de nuevo, conectar la base de datos, escribir migraciones, conectar las variables de entorno, construir el Dockerfile y configurar los linters. Es fácil desperdiciar toda una noche en esta rutina antes de que aparezca el primer endpoint real.

Por supuesto, puedes copiar la estructura de tu repositorio anterior. Pero generalmente tiene un montón de workarounds antiguos, dependencias innecesarias y librerías desactualizadas. Las plantillas listas para usar de los resultados de búsqueda también rara vez dan en el blanco, porque el autor eligió TortoiseORM pero tú necesitas SQLAlchemy 2.0, o incluyeron Celery pesado en lugar de colas ligeras.

El repositorio FastAPI-template del desarrollador s3rius resuelve este problema de manera diferente. No es solo una plantilla estática, sino un generador interactivo de proyectos flexible.

Constructor en lugar de una plantilla rígida

El proyecto funciona como un cuestionario de terminal. Lanzas la utilidad vía pip, uv o Docker, respondes un par de docenas de preguntas y obtienes una base de código lista y adaptada a tus necesidades.

La principal ventaja del generador es la variabilidad. La mayoría de las plantillas imponen una pila específica, pero aquí ensamblas el conjunto de componentes que necesitas.

Bases de datos y ORM de tu elección

En lugar de estar atado a una única librería, la utilidad soporta varias opciones populares de manejo de datos:

• SQLAlchemy 2.0 con motor async
• TortoiseORM con generación de migraciones vía Aerich
• Piccolo ORM
• Ormar
• Beanie para MongoDB
• Driver psycopg raw sin ORM

Si no necesitas una base de datos en absoluto, puedes elegir la opción sin almacenamiento de datos. En ese caso, el código no tendrá dependencias innecesarias ni archivos de configuración basura.

REST o GraphQL

Por defecto, el generador construye una API REST clásica con documentación Swagger automática. Pero si tu frontend prefiere trabajar a través de GraphQL, el generador configurará el wrapper basado en la librería Strawberry. No necesitas configurar manualmente el esquema y los tipos para comenzar.

Tareas en segundo plano y colas

En lugar de Celery voluminoso, el autor de la plantilla añadió integración con Taskiq — un gestor de tareas async moderno para Python. Encaja perfectamente en la arquitectura async general de FastAPI. Como broker de mensajes, puedes elegir Redis, RabbitMQ o Kafka durante la generación.

Monitoreo y logging de serie

La plantilla ya tiene integraciones listas incorporadas que normalmente tienes que configurar manualmente a partir de artículos separados:

• Recolección de métricas para Prometheus
• Trazado vía OpenTelemetry
• Envío de errores a Sentry
• Logging estructurado vía Loguru

Todas estas opciones se activan mediante flags simples o selección en el menú interactivo.

Inicio rápido

Para ejecutar la utilidad, necesitas Git, Python y el gestor de paquetes rápido uv instalados en tu máquina.

El generador se instala vía pip:

python3 -m pip install fastapi_template
fastapi_template

Después de lanzar, aparecerá un cuestionario paso a paso en la consola. Seleccionas el nombre del proyecto, el DBMS deseado, el tipo de autenticación (JWT o cookie vía fastapi-users), el formato de CI/CD (GitHub Actions o GitLab CI) y los servicios adicionales.

Cuando el generador termine, ve a la carpeta creada y levanta el entorno:

cd my_awesome_project
docker-compose up --build

Si no quieres instalar el paquete localmente, puedes ejecutar el generador vía Docker en una línea:

docker run --rm -it -v "$(pwd):/projects" ghcr.io/s3rius/fastapi_template

Generación vía flags de CLI

Si estás configurando la creación automatizada de microservicios en tu empresa, puedes desactivar el modo interactivo. La utilidad acepta todos los parámetros vía argumentos de línea de comandos:

fastapi_template \
  --name billing_service \
  --api-type rest \
  --db postgresql \
  --orm sqlalchemy \
  --migrations \
  --redis \
  --taskiq \
  --prometheus \
  --ci github \
  --quiet

Esta llamada creará un servicio listo con SQLAlchemy configurado, migraciones Alembic, tareas en segundo plano con Taskiq, métricas y un pipeline de GitHub sin una sola pregunta en la terminal.

Qué hay dentro del proyecto generado

El código generado sorprende agradablemente por su estructura. No hay un desastre de todo metido en un archivo main.py.

La arquitectura se divide en capas lógicas:

• web/api: routers separados por prefijos de versión y módulos
• db: conexión a la base de datos, modelos y configuración de migraciones
• services: lógica de negocio y clientes de servicios externos
• settings.py: configuración tipada basada en pydantic-settings

El proyecto inmediatamente incluye tests con pytest con aproximadamente 90% de cobertura para la estructura base, pre-commit configurado con linters y un docker-compose.yml listo con todos los servicios seleccionados. No necesitarás levantar por separado Redis o PostgreSQL para desarrollo local.

A quién le será útil este proyecto

El generador es perfecto para dos escenarios.

El primer caso es el lanzamiento rápido de proyectos personales y MVPs. Cuando quieres probar una hipótesis durante el fin de semana, no hay deseo de pasar medio día en boilerplate.

El segundo caso es la estandarización de microservicios en un equipo. Puedes tomar esta plantilla como base o usar su interfaz CLI para que los nuevos servicios de la empresa se creen según un estándar único con telemetría y tests ya configurados.

Si escribes en Python y frecuentemente levantas nuevos backends FastAPI, definitivamente marca este repositorio. Ahorrará mucho tiempo y nervios al inicio.