Cómo Estructurar las Carpetas de un Proyecto Backend con FastAPI

#

Cuando comienzas a desarrollar y probar una aplicación, es fundamental comprender la función de cada carpeta dentro del proyecto. La modularización y la escalabilidad son aspectos clave a considerar para que tu proyecto pueda crecer de manera eficiente en el futuro.

En este artículo, te mostraré cómo estructurar un proyecto de FastAPI de forma modular y eficiente, explicando de forma breve y concisa la funcionalidad de cada carpeta y archivo.

Preparando tu Entorno de Desarrollo

#

El entorno de desarrollo que utilizo por sus amplias funcionalidades es VSC (Visual Studio Code). Me gusta por su variedad de extensiones y la facilidad para integrarlo con diferentes plataformas como Postman o GitHub. Lo primero que hago es crear dos terminales: una para el entorno virtual y otra para ejecutar FastAPI en el navegador. De esta forma, puedo probar los endpoints o ejecutar tests para verificar el funcionamiento de la aplicación.

Cómo Crear y Configurar un Entorno Virtual para tu Backend con FastAPI

#

Es fundamental crear un entorno virtual para evitar conflictos entre proyectos, dependencias o librerías.

python -m venv venv 

Activar el entorno virtual creado

#

.\venv\Scripts\activate

Instalar FastAPI

#

La opción all instala algunas dependencias que pueden ser útiles a medida que vayas desarrollando el proyecto.

pip install fastapi[all]

Cómo Ejecutar tu Aplicación FastAPI en el Navegador para Probar Endpoints

#

Para comenzar, crea dentro de la carpeta app el archivo main.py y pega el siguiente código:

from typing import Union

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"mensaje": "Hola Mundo"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: Union[str, None] = None):
    return {"item_id": item_id, "q": q}

Ejecuta la aplicación FastAPI

#

Una vez que hayas creado tu archivo main.py, el siguiente paso es ejecutar la aplicación utilizando Uvicorn, que es el servidor ASGI utilizado para correr aplicaciones FastAPI.

uvicorn main:app --reload

Una vez preparado brevemente el entorno y lo básico, es hora de explicar las funciones de cada carpeta

Estructura del Proyecto: Funciones de las Carpetas en un Backend con FastAPI

#

📂alembic

#

Es una herramienta de migración de bases de datos para ser utilizada con el kit de herramientas SQLAlchemy para Python.

📂app

#

Dentro de esta carpeta se ubicará tu aplicación con el resto de carpetas necesarias para su funcionamiento.

📂 api/routes

#

Contiene todas las rutas de la API, organizadas por módulos, para facilitar el acceso y mantenimiento del código.

📂 admin

#

Rutas accesibles si tienes el rol de administrador en la aplicación.

📂 auth

#

Rutas para el login de los usuarios o para recordar una contraseña olvidada.

📂 client

#

Rutas accesibles para los usuarios con el rol de cliente. Crear un pedido o ver tu perfil completo.

📂 public

#

Rutas sin necesidad de estar autenticados.

📜 api.py

#

En este archivo se registran todas las rutas de la aplicación y se crea un router principal, importando las rutas definidas en el archivo main.py.

📂 core

#

En esta carpeta se alojan archivos relacionados con la seguridad, configuración, etc. Como indica su significado, es el núcleo, es decir, la parte esencial para el funcionamiento de la aplicación.

📂 dependencies

#

Dependencias que se utilizan para validar los datos antes de procesar las solicitudes a las rutas de los endpoints.

📂 middlewares

#

Los middlewares son funciones que comprueban las solicitudes antes y después de procesar la solicitud para dar respuestas en cualquier caso. Se pueden comparar con los controles de seguridad en un aeropuerto✈️.

📂 models

#

Define los modelos que corresponden a las tablas en la base de datos, con su estructura y relaciones.

📂 category

#

Modelo de las categorías de los productos.

📂 order

#

Modelo de los pedidos de los clientes.

📂 product

#

Modelo de los productos que ofrece la tienda.

📂 user

#

Modelo de los usuarios de la aplicación.

📂 responses

#

Diferentes clases para gestionar las respuestas HTTP de la aplicación

📂 schemas

#

Esquemas de datos para estructurar y validar la información que la aplicación recibe y envía.

📂 services

#

En esta carpeta se centra la lógica de negocio de la aplicación. Esta carpeta recoge las funciones que realizan las operaciones de consultas y procesamiento de la base de datos.

📂 category

#

Funciones relacionadas con las categorías.

📂 order

#

Funciones relacionadas con los pedidos.

📂 product

#

Funciones relacionadas con los productos.

📜 email.py

#

Funciones relacionadas el envío de los correos.

📜 user_profile.py

#

Funciones relacionadas con el perfil de los usuarios.

📜 user.py

#

Funciones relacionadas con los usuarios.

📂 templates/user

#

En esta carpeta se almacenan las plantillas de los correos html que son enviados a los usuarios.

📂 utils

#

Funciones o elementos generales que se pueden utilizar en diferentes partes de la aplicación.

📜 main.py

#

Este archivo es el principal y el que lanza la aplicación.

📂test

#

La carpeta test contiene todos los archivos de prueba necesarios para asegurar que la aplicación funciona correctamente, realizando verificaciones en áreas clave como lógica de negocio, base de datos, y envío de correos.

📜requirements.txt

#

Este archivo lista todas las dependencias necesarias para que la aplicación funcione correctamente, incluyendo las librerías y sus versiones específicas.

🐋docker-compose.yml

#

Se utiliza para configurar los contenedores necesarios para la aplicación, incluyendo la base de datos y otros servicios dependientes.

🐋Dockerfile

#

Define el entorno del contenedor de Docker

⚙️alembic.ini

#

Archivo para configurar las migraciones de la base de datos en proyectos que usan SQLAlchemy

📜 .env

#

Crea el archivo .env con las variables del entorno que vas a utilizar y por motivos de seguridad e información sensible no es recomendable subirlo a ningún repositorio público.

Estructura del proyecto subida a un repositorio público

#

📂elembic
┣ 📂versions
┃  ┗ 📜initial_migration.pyc
┣ 📜env.py
┣ 📜README
┣ 📜script.py.mako
📂app
┣ 📂api
┃ ┣ 📂routes
┃ ┃ ┣ 📂admin
┃ ┃ ┣ 📂auth
┃ ┃ ┣ 📂client
┃ ┃ ┗ 📂public
┃ ┗ 📜api.py
┣ 📂core
┣ 📂dependencies
┣ 📂middlewares
┣ 📂models
┃ ┣ 📂category
┃ ┣ 📂order
┃ ┣ 📂product
┃ ┣ 📂user
┃ ┗ 📜__init__.py
┣ 📂responses
┣ 📂schemas
┣ 📂services
┃ ┣ 📂category
┃ ┣ 📂order
┃ ┣ 📂product
┃ ┣ 📜email.py
┃ ┣ 📜user_profile.py
┃ ┗ 📜user.py
┣ 📂templates
┃ ┗ 📂user
┣ 📂utils
┣ 📜main.py
┣ 📂test
┣ 📜.env
┣ 📜requirements.txt
┣ 🐋docker-compose.yml
┣ 🐋Dockerfile
┗ ⚙️alembic.ini 

Enlaces útiles para leer la documentación

#

• Fastapi
• Python
• PostgreSQL
• Docker
• Postman

¿Te ha sido útil esta explicación? Encuentra el código completo del proyecto en mi GitHub: