Cómo estructurar tus proyectos FastAPI

En este artículo analizaremos dos estrategias principales para estructurar sus proyectos FastAPI y destacaremos los escenarios en los que cada una es más adecuada.

¿Por qué es importante una estructuración adecuada de tus proyectos FastAPI?

He aquí las razones más importantes para estructurar su código basándose en las mejores prácticas.

Escalabilidad mejorada: Un código bien organizado crece sin problemas con su proyecto FastAPI.
Mejor mantenimiento: Un código fácil de entender simplifica las actualizaciones y correcciones.
Colaboración optimizada: Una estructura clara ayuda a los equipos a trabajar juntos de forma eficiente.

Principios clave para estructurar proyectos

A la hora de crear aplicaciones FastAPI, es fundamental seguir estas prácticas recomendadas:

Separación de intereses: Separe los diferentes aspectos de su proyecto FastAPI, como rutas, modelos y lógica de negocio, para mayor claridad y facilidad de mantenimiento.
Modularización: Divida su aplicación FastAPI en módulos reutilizables para promover la reutilización y organización del código.
Inyección de dependencias: Desacople los componentes implementando la inyección de dependencias, que permite un código más flexible y comprobable en FastAPI utilizando bibliotecas como fastapi.Dependencies.
Comprobabilidad: Dar prioridad a la escritura de código comprobable en aplicaciones FastAPI mediante el empleo de estrategias como la inyección de dependencia y mocking para asegurar pruebas robustas y garantía de calidad.

Formatos de estructuración

Las aplicaciones FastAPI pueden estructurarse de distintas formas para adaptarse a las necesidades de los proyectos.

Existen dos enfoques principales para estructurar proyectos. Uno se basa en el tipo de archivo y el otro en la funcionalidad del módulo.

Estructuración basada en el tipo de archivo

En este enfoque, los archivos se organizan por tipo (por ejemplo, API, CRUD, modelos, esquemas, enrutadores) tal y como lo representa la propia FastAPI.

Esta estructura es más adecuada para microservicios o proyectos con menos alcance:

.
├── app  # Contains the main application files.
│   ├── __init__.py   # this file makes "app" a "Python package"
│   ├── main.py       # Initializes the FastAPI application.
│   ├── dependencies.py # Defines dependencies used by the routers
│   ├── routers
│   │   ├── __init__.py
│   │   ├── items.py  # Defines routes and endpoints related to items.
│   │   └── users.py  # Defines routes and endpoints related to users.
│   ├── crud
│   │   ├── __init__.py
│   │   ├── item.py  # Defines CRUD operations for items.
│   │   └── user.py  # Defines CRUD operations for users.
│   ├── schemas
│   │   ├── __init__.py
│   │   ├── item.py  # Defines schemas for items.
│   │   └── user.py  # Defines schemas for users.
│   ├── models
│   │   ├── __init__.py
│   │   ├── item.py  # Defines database models for items.
│   │   └── user.py  # Defines database models for users.
│   ├── external_services
│   │   ├── __init__.py
│   │   ├── email.py          # Defines functions for sending emails.
│   │   └── notification.py   # Defines functions for sending notifications
│   └── utils
│       ├── __init__.py
│       ├── authentication.py  # Defines functions for authentication.
│       └── validation.py      # Defines functions for validation.
├── tests
│   ├── __init__.py
│   ├── test_main.py
│   ├── test_items.py  # Tests for the items module.
│   └── test_users.py  # Tests for the users module.
├── requirements.txt
├── .gitignore
└── README.md

En esta estructura

app/: Contiene los archivos principales de la aplicación.
main.py: Inicializa la aplicación FastAPI.
dependencies.py: Define las dependencias utilizadas por los routers.
routers/: Contiene los módulos de los routers.
crud/: Contiene módulos de operaciones CRUD (Create, Read, Update, Delete).
schemas/: Contiene módulos de esquemas Pydantic.
models/: Contiene módulos de modelos de bases de datos.
external_services/: Contiene módulos para interactuar con servicios externos.
utils/: Contiene módulos de utilidades.
tests/: Contiene módulos de prueba.

Estructuración basada en la funcionalidad de los módulos

En el segundo enfoque, organizamos nuestros archivos basándonos en la funcionalidad del paquete, por ejemplo, el subpaquete de autenticación, el subpaquete de usuarios y el subpaquete de mensajes.

La estructura módulo-funcionalidad es más adecuada para proyectos monolíticos que contienen numerosos dominios y módulos. Al agrupar todos los tipos de archivos requeridos por un único subpaquete, mejora la eficiencia del desarrollo.

Esta estructura se sugiere en el repositorio fastapi-best-practices de GitHub.

En esta estructura, cada paquete tiene su propio enrutador, esquemas, modelos, etc.

fastapi-project
├── alembic/
├── src
│   ├── auth
│   │   ├── router.py         # auth main router with all the endpoints
│   │   ├── schemas.py        # pydantic models
│   │   ├── models.py         # database models
│   │   ├── dependencies.py   # router dependencies
│   │   ├── config.py         # local configs
│   │   ├── constants.py      # module-specific constants
│   │   ├── exceptions.py     # module-specific errors
│   │   ├── service.py        # module-specific business logic
│   │   └── utils.py          # any other non-business logic functions
│   ├── aws
│   │   ├── client.py  # client model for external service communication
│   │   ├── schemas.py
│   │   ├── config.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   └── utils.py
│   └── posts
│   │   ├── router.py
│   │   ├── schemas.py
│   │   ├── models.py
│   │   ├── dependencies.py
│   │   ├── constants.py
│   │   ├── exceptions.py
│   │   ├── service.py
│   │   └── utils.py
│   ├── config.py      # global configs
│   ├── models.py      # global database models
│   ├── exceptions.py  # global exceptions
│   ├── pagination.py  # global module e.g. pagination
│   ├── database.py    # db connection related stuff
│   └── main.py
├── tests/
│   ├── auth
│   ├── aws
│   └── posts
├── templates/
│   └── index.html
├── requirements
│   ├── base.txt
│   ├── dev.txt
│   └── prod.txt
├── .env
├── .gitignore
├── logging.ini
└── alembic.ini

En esta estructura

Almacenar todos los directorios de dominio dentro de la carpeta src.

src/: El nivel más alto de una app, contiene modelos comunes, configs, y constantes, etc.
src/main.py: Raíz del proyecto, que inits la aplicación FastAPI
Cada paquete tiene su propio router, esquemas, modelos, etc.
router.py: es el núcleo de cada módulo con todos los endpoints
schemas.py: para modelos pydánticos
models.py: para modelos de base de datos
service.py: lógica de negocio específica del módulo
dependencies.py: dependencias del enrutador
constants.py: constantes y códigos de error específicos del módulo
config.py: p.e. env vars
utils.py: funciones no relacionadas con la lógica de negocio, por ejemplo, normalización de respuestas, enriquecimiento de datos, etc.
exceptions.py: excepciones específicas del módulo, p.ej. PostNotFound, InvalidUserData

Cuando un paquete requiera servicios o dependencias o constantes de otros paquetes, impórtelos con un nombre de módulo explícito para evitar ambigüedades.

En conclusión, la estructuración de sus proyectos FastAPI es esencial para mantener la escalabilidad, legibilidad y facilidad de mantenimiento a medida que crece tu aplicación. Al organizar el código de forma efectiva, se asegura de que sigue siendo manejable y adaptable a las necesidades cambiantes.

Hemos discutido dos tipos principales de estructuración de proyectos FastAPI: la estructura de tipo archivo y la estructura de funcionalidad de módulo.

La estructura de tipo archivo, representada por la propia FastAPI, organiza los archivos en función de su tipo (por ejemplo, enrutadores, esquemas, modelos). Esta estructura es adecuada para arquitecturas de microservicios en las que los servicios individuales tienen responsabilidades únicas.

Por otro lado, la estructura módulo-funcionalidad separa los archivos en función de la funcionalidad del módulo y no del tipo de archivo.

Este enfoque es más adecuado para aplicaciones monolíticas de mayor tamaño, ya que favorece una mejor organización y capacidad de mantenimiento.

A la hora de elegir la estructura adecuada para su proyecto FastAPI, tenga en cuenta factores como el tamaño del proyecto, la complejidad y el diseño arquitectónico. En última instancia, tanto si opta por la estructura de tipo archivo como por la estructura de funcionalidad de módulo, dar prioridad a la organización y la claridad contribuirá al éxito a largo plazo de sus aplicaciones FastAPI.

Fuente