Estructura de proyecto y tests

Teoría22 min20 XP

Un archivo main.py con todo dentro funciona para aprender, pero una API real se organiza en una ESTRUCTURA por capas para que crezca sin volverse un caos. Y para confiar en que funciona, se prueba con TESTS automáticos —FastAPI trae un TestClient que llama a tus endpoints sin levantar un servidor—. Hoy cierras la ruta de backend con lo que separa un experimento de una API de producción: organización y pruebas.

El edificio con planos vs el cuarto abarrotado

Estructura por capas

Organizar un proyecto FastAPI

Un proyecto FastAPI que escala se organiza por responsabilidad (como la arquitectura por features que viste en React, SC-06):

estructura

mi_api/
app/
  main.py           # crea la app FastAPI y monta las rutas
  models.py         # modelos SQLModel/Pydantic (la forma de los datos)
  database.py       # conexión y sesión de la base de datos
  routers/          # los endpoints, agrupados por recurso
    gastos.py       # /gastos (GET, POST, PUT, DELETE)
    auth.py         # /login, /registro
  services/         # lógica de negocio (separada de las rutas)
    gastos_service.py
  core/
    config.py       # configuración (lee variables de entorno)
    security.py     # hasheo, JWT
tests/
  test_gastos.py    # pruebas de los endpoints
requirements.txt    # dependencias
.env                # secretos (NUNCA se sube a git)

Cada capa tiene una responsabilidad: los routers definen los endpoints (y usan los services); los services tienen la lógica de negocio (independiente de HTTP, fácil de testear); models la forma de los datos; database la persistencia; core la configuración y seguridad. Los endpoints se dividen por RECURSO (un router para gastos, otro para auth) y se montan en main.py con app.include_router(...). Esta separación —igual que la arquitectura por features de React— hace que agregar una funcionalidad sea claro y que el proyecto no se vuelva un nudo. El .env con los secretos NUNCA se sube a git (va en .gitignore).

Tests con TestClient

Probar endpoints sin servidor

FastAPI trae un TestClient que llama a tus endpoints directamente (sin levantar un servidor real), perfecto para tests con pytest:

test_gastos.py

from fastapi.testclient import TestClient
from app.main import app

cliente = TestClient(app)

def test_listar_gastos():
  respuesta = cliente.get("/gastos")
  assert respuesta.status_code == 200
  assert isinstance(respuesta.json(), list)

def test_crear_gasto():
  respuesta = cliente.post("/gastos", json={"nombre": "Café", "valor": 4000})
  assert respuesta.status_code == 201
  datos = respuesta.json()
  assert datos["nombre"] == "Café"
  assert "id" in datos

def test_valor_invalido_es_rechazado():
  # valor negativo -> Pydantic debe rechazarlo con 422
  respuesta = cliente.post("/gastos", json={"nombre": "Bus", "valor": -100})
  assert respuesta.status_code == 422

def test_gasto_inexistente_da_404():
  respuesta = cliente.get("/gastos/99999")
  assert respuesta.status_code == 404

terminal

$ pytest

tests/test_gastos.py .... [100%]

4 passed in 0.32s

El TestClient (envuelve tu app) hace peticiones como si fueras un cliente real, pero en memoria —rápido y sin servidor—. Cada test verifica un comportamiento: que listar devuelve 200 y una lista, que crear devuelve 201 con el id, que un valor inválido da 422 (¡la validación de Pydantic!), que un id inexistente da 404. Es el mismo Vitest/pytest que ya conoces (SC-02, módulo 6 de Python), aplicado a endpoints. Con estos tests, cada cambio en tu API se verifica automáticamente —confías en que no rompiste nada—.

¿Por qué organizar una API en capas y qué hace el TestClient de FastAPI?

Mini-reto

Diseña (en papel o en tu proyecto) la estructura y tests de tu API: 1) esboza las carpetas por capas (routers, services, models, database) y qué iría en cada una para un recurso "gastos"; 2) escribe tres tests con TestClient: listar devuelve 200 y una lista, crear con datos válidos devuelve 201, y crear con valor negativo devuelve 422; 3) explica por qué el .env con secretos no se sube a git. Piensa qué pondrías en un service vs en un router.

Qué sigue

¡Módulo 8 conquistado! Dominas la ruta de backend —APIs REST, FastAPI, Pydantic, bases de datos, JWT, estructura y tests—. Puedes construir el servidor que alimenta cualquier app. El reto del módulo junta la lógica CRUD en una capa de datos que corre en vivo. Después, el módulo 9 abre la última ruta: DATOS E IA, donde Python reina —NumPy, Pandas y machine learning—.