Lección 45 de 47 · Proyecto final: CRUD de tareas con SQLite✦ WebMCP implementado
Fase 4: los casos de uso
10 min de lectura4 retos
El dominio sabe qué es una tarea y el repositorio sabe guardarla. Falta quien dirija la orquesta: los casos de uso, una pieza por cada cosa que la app sabe hacer. En esta fase escribes CrearTarea, ListarTareas, CompletarTarea y BorrarTarea, los pruebas con repositorios falsos y los enchufas a SQLite.
¿De dónde vienen los nombres?
caso de uso = inglés use case: un uso concreto que le das a la app
Una clase pequeña con una cosa que la app sabe hacer: «crear una tarea», «completar una tarea». Son los verbos de tu app.
ejecutar = inglés execute (ejecutar, llevar a cabo)
El nombre del método único de cada caso de uso. Quien lo llama no necesita saber nada más.
inyección de dependencias = inyectar = meter desde fuera; dependencia = algo que otra pieza necesita
El caso de uso recibe el repositorio en el constructor en vez de crearlo él. Es el __construct(private RepositorioTareas $repo) de PHP.
doble de test = del cine: el doble que sustituye al actor en las escenas peligrosas
Un objeto falso (fake, spy…) que ocupa el lugar del repositorio real en los tests.
En 4 ideas
1/4
Un caso de uso es una clase con un constructor que recibe el repositorio y un único método, ejecutar(). Es tu service o handler de PHP, y hay uno por acción: crear, listar, completar, borrar.
Cambiar una tarea siempre es buscar → cambiar → guardar. Si te olvidas del guardar(), el cambio se pierde en silencio: una tarea que lees es una copia, no la fila.
Como RepositorioTareas es un Protocol, los tests le pasan un repositorio falso (en memoria, o un espía que cuenta llamadas) sin heredar de nada. Los casos de uso no saben ni les importa si hay SQLite detrás.
Los casos de uso no devuelven None cuando falla: lanzanTareaNoEncontrada, y es la capa de arriba (la API) la que decide qué hacer con ella.
1 · Qué es un caso de uso
Piensa en la barra de una cafetería. El camarero no sabe cocinar ni cómo está montada la nevera: recibe un pedido («un café con leche»), lo pasa a quien corresponda y devuelve el resultado. Un caso de uso hace lo mismo: recibe una petición, usa el dominio y el repositorio, y devuelve el resultado. No sabe si le habla una API, una consola o un test.
Cada caso de uso es una clase con un solo método. Así, mirando la carpeta app/application, ves de un vistazo todo lo que la app sabe hacer. Pulsa Ejecutar:
Pythonmain.py
from dataclasses import dataclass, field, replace
@dataclassclassTarea:
titulo: str
hecha: bool = False
etiquetas: list[str] = field(default_factory=list)
id: int | None = NoneclassRepositorioMemoria:
def__init__(self):
self._tareas = {}
self._siguiente = 1defguardar(self, tarea):
if tarea.id isNone:
tarea = replace(tarea, id=self._siguiente)
self._siguiente += 1self._tareas[tarea.id] = replace(tarea)
return tarea
deflistar(self):
return [replace(t) for t inself._tareas.values()]
classCrearTarea:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, titulo, etiquetas=None):
tarea = Tarea(titulo.strip(), etiquetas=list(etiquetas or []))
returnself._repositorio.guardar(tarea)
classListarTareas:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, solo_pendientes=False):
tareas = self._repositorio.listar()
if solo_pendientes:
tareas = [t for t in tareas ifnot t.hecha]
return tareas
repositorio = RepositorioMemoria()
crear = CrearTarea(repositorio)
listar = ListarTareas(repositorio)
crear.ejecutar(" Comprar pan ")
crear.ejecutar("Llamar al banco", etiquetas=["casa"])
for tarea in listar.ejecutar():
print(tarea.id, tarea.titulo, tarea.etiquetas)
Se guarda en el objeto; con _ por convenio es privado
$this->repositorio->guardar(...)
self._repositorio.guardar(...)
Solo el propio caso de uso
final readonly class
Una clase normal: no tiene final ni readonly de clase
Se confía en no reasignar self._repositorio
new CrearTarea(new RepositorioMemoria())
CrearTarea(RepositorioMemoria())
Sin new: llamar a la clase crea el objeto
¿Por qué? · En PHP no existe
¿Por qué una clase con ejecutar() y no una función suelta crear_tarea(repositorio, titulo)?
Una función también valdría, y en Python es muy normal. Elegimos la clase porque el repositorio es una dependencia que no cambia entre llamadas: se pasa una vez al construir y el método solo recibe los datos de la petición. Quien use el caso de uso no necesita ni saber que existe un repositorio.
Además, así encaja con el sistema de dependencias de FastAPI que verás en la fase 5, donde cada ruta pide su caso de uso ya construido. Y es el mismo patrón que verás en cualquier proyecto PHP con DDD: Application Services con un método público.
2 · Buscar, cambiar, guardar
Completar una tarea parece trivial: tarea.hecha = True. Pero la tarea que te da el repositorio es una copia (módulo 04), no la fila de la base de datos. Cambiar la copia no cambia nada guardado. El camino correcto tiene tres pasos:
Buscar la tarea con buscar_por_id(id) (lanza TareaNoEncontrada si no existe).
Cambiarla con su método del dominio, tarea.completar().
Guardarla con guardar(tarea): sin este paso, el cambio se pierde.
Mira qué pasa si te olvidas del tercero. El programa no da ningún error:
¿Por qué el repositorio devuelve copias y no el objeto de dentro? Sería más cómodo
Sería más cómodo y mentiría. Si la memoria devolviera el propio objeto, el caso de uso sin guardar()funcionaría en los tests, y fallaría en producción con SQLite, que siempre construye una tarea nueva a partir de la fila. El bug solo aparecería en el despliegue.
Con copias, el repositorio falso se comporta como el real y los tests cazan el olvido. Es el mismo problema que en PHP con Doctrine: ahí un flush() olvidado se salta los tests si el entity manager ya tiene el objeto en memoria.
3 · Repositorios falsos: probar sin base de datos
Como RepositorioTareas es un Protocol, no hace falta heredar de nada para ser un repositorio falso: basta con tener los métodos. En PHP necesitarías un mock de PHPUnit o una clase que implements la interfaz; aquí es una clase normal. Un buen doble para probar casos de uso es un espía: guarda lo que ha recibido para que el test lo compruebe.
Pythonmain.py
from dataclasses import dataclass
@dataclassclassTarea:
titulo: str
hecha: bool = False
id: int | None = Nonedefcompletar(self):
self.hecha = TrueclassRepositorioEspia:
"""Un repositorio falso: guarda las llamadas para que el test las mire."""def__init__(self, tareas):
self._tareas = {t.id: t for t in tareas}
self.guardadas = []
defbuscar_por_id(self, id):
returnself._tareas[id]
defguardar(self, tarea):
self.guardadas.append(tarea.id)
return tarea
classCompletarTarea:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, id):
tarea = self._repositorio.buscar_por_id(id)
tarea.completar()
returnself._repositorio.guardar(tarea)
espia = RepositorioEspia([Tarea("Comprar pan", id=1), Tarea("Llamar al banco", id=2)])
resultado = CompletarTarea(espia).ejecutar(2)
print(resultado.titulo, resultado.hecha)
print("guardó las tareas:", espia.guardadas)
Doble
Qué hace
Cuándo lo usas
Fake (falso)
Funciona de verdad pero sin base de datos: RepositorioMemoria
Probar el flujo completo de varios casos de uso
Spy (espía)
Funciona y además anota cada llamada
Comprobar que se llamó a guardar() y con qué
Mock
Tiene la respuesta preparada y falla si no recibe la llamada esperada
Casos raros: forzar un error del repositorio
4 · Cuando falla: lanzar, no devolver None
Qué debe hacer CompletarTarea si la tarea no existe. Hay dos opciones: devolver None o lanzar TareaNoEncontrada. Elegimos lanzar, y el buscar_por_id del repositorio ya lo hace: el caso de uso no tiene que escribir nada, el error sube solo.
Pythonmain.py
from dataclasses import dataclass, replace
classTareaNoEncontrada(Exception):
def__init__(self, id):
super().__init__(f"No existe la tarea {id}")
self.id = id
@dataclassclassTarea:
titulo: str
hecha: bool = False
id: int | None = Nonedefcompletar(self):
self.hecha = TrueclassRepositorioMemoria:
def__init__(self, tareas):
self._tareas = {t.id: t for t in tareas}
defbuscar_por_id(self, id):
if id notinself._tareas:
raiseTareaNoEncontrada(id)
returnreplace(self._tareas[id])
defguardar(self, tarea):
self._tareas[tarea.id] = replace(tarea)
return tarea
defborrar(self, id):
if id notinself._tareas:
raiseTareaNoEncontrada(id)
delself._tareas[id]
classCompletarTarea:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, id):
tarea = self._repositorio.buscar_por_id(id)
tarea.completar()
returnself._repositorio.guardar(tarea)
classBorrarTarea:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, id):
self._repositorio.borrar(id)
repositorio = RepositorioMemoria([Tarea("Comprar pan", id=1)])
for caso, id in [(CompletarTarea(repositorio), 1), (CompletarTarea(repositorio), 7), (BorrarTarea(repositorio), 1), (BorrarTarea(repositorio), 1)]:
try:
caso.ejecutar(id)
print(f"{type(caso).__name__}({id}): bien")
exceptTareaNoEncontradaas error:
print(f"{type(caso).__name__}({id}): {error}")
¿Por qué? · En PHP no existe
¿Por qué el caso de uso no atrapa el error y devuelve un mensaje?
Porque no sabe quién le llama. Una API quiere un 404 con JSON, una consola quiere imprimir un aviso en rojo y un test quiere comprobar que se lanzó. Si el caso de uso decidiera el mensaje, tendría que conocer a todos.
Lanzar el error de dominio y dejar que cada capa de fuera lo traduzca mantiene el caso de uso limpio. Es la misma idea del throw en PHP: el que sabe qué hacer con el error es el que está arriba, no el que lo detecta.
5 · Enchufar todo: del caso de uso al SQLite real
Falta la pieza que monta el puzzle: construir el repositorio, construir los casos de uso con él y entregárselos a la capa de fuera. A ese sitio se le llama raíz de composición (composition root): es el único lugar que conoce las clases concretas. En PHP sería el contenedor de dependencias; aquí, una función. Lo ves funcionando con SQLite de verdad (en memoria):
Pythonmain.py
import sqlite3
from dataclasses import dataclass, field, replace
classTareaNoEncontrada(Exception):
pass@dataclassclassTarea:
titulo: str
hecha: bool = False
etiquetas: list[str] = field(default_factory=list)
id: int | None = Nonedefcompletar(self):
self.hecha = TrueclassRepositorioSqlite:
def__init__(self, conexion):
conexion.row_factory = sqlite3.Rowself._conexion = conexion
defguardar(self, tarea):
if tarea.id isNone:
cursor = self._conexion.execute(
"INSERT INTO tareas (titulo, hecha) VALUES (?, ?)", (tarea.titulo, int(tarea.hecha))
)
self._conexion.commit()
returnreplace(tarea, id=cursor.lastrowid)
self._conexion.execute(
"UPDATE tareas SET titulo = ?, hecha = ? WHERE id = ?", (tarea.titulo, int(tarea.hecha), tarea.id)
)
self._conexion.commit()
return tarea
defbuscar_por_id(self, id):
fila = self._conexion.execute("SELECT id, titulo, hecha FROM tareas WHERE id = ?", (id,)).fetchone()
if fila isNone:
raiseTareaNoEncontrada(id)
returnTarea(fila["titulo"], bool(fila["hecha"]), id=fila["id"])
deflistar(self):
filas = self._conexion.execute("SELECT id, titulo, hecha FROM tareas ORDER BY id")
return [Tarea(f["titulo"], bool(f["hecha"]), id=f["id"]) for f in filas]
classCrearTarea:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, titulo):
returnself._repositorio.guardar(Tarea(titulo))
classListarTareas:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self):
returnself._repositorio.listar()
classCompletarTarea:
def__init__(self, repositorio):
self._repositorio = repositorio
defejecutar(self, id):
tarea = self._repositorio.buscar_por_id(id)
tarea.completar()
returnself._repositorio.guardar(tarea)
defconstruir_casos_de_uso(conexion):
"""La raíz de composición: el único sitio que conoce las clases concretas."""
repositorio = RepositorioSqlite(conexion)
returnCrearTarea(repositorio), ListarTareas(repositorio), CompletarTarea(repositorio)
conexion = sqlite3.connect(":memory:")
conexion.execute("CREATE TABLE tareas (id INTEGER PRIMARY KEY AUTOINCREMENT, titulo TEXT NOT NULL, hecha INTEGER NOT NULL DEFAULT 0)")
crear, listar, completar = construir_casos_de_uso(conexion)
crear.ejecutar("Comprar pan")
crear.ejecutar("Llamar al banco")
completar.ejecutar(1)
for tarea in listar.ejecutar():
print(tarea.id, tarea.titulo, "hecha"if tarea.hecha else"pendiente")
La pregunta que te vas a hacer
Vale, pero… ¿no hay un contenedor de dependencias como el de Symfony o Laravel?
Existen librerías para ello, pero en Python casi nunca hacen falta: una función que construye las piezas (como construir_casos_de_uso) es más sencilla y se lee de arriba abajo. FastAPI trae además su propio sistema de dependencias, Depends, que verás en la fase 5. Para curiosear:
typing.Protocol: los Protocol de la documentación oficial, la base de este diseño.
Hora de practicar
Retos · 0/4 resueltos
Reto 1 de 4 · ✓ Resuelto
Crear y listar
Los casos de uso CrearTarea y ListarTareas ya están escritos. Usa el mismo repositorio en los dos para que el programa imprima, una por línea, Comprar pan y Llamar al banco. Es crear dos veces con un mismo new RepositorioMemoria() en PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Ahora cada caso de uso crea su propio RepositorioMemoria(), así que no comparten nada. Crea uno solo, guárdalo en una variable y pásalo a los dos.
Reto 2 de 4 · ✓ Resuelto
El caso de uso CrearTarea
Escribe CrearTarea.ejecutar(titulo, etiquetas=None): crea una Tarea con el título sin espacios sobrantes y una copia de las etiquetas (o lista vacía si no hay), la guarda con el repositorio y devuelve la tarea guardada. Es el CrearTarea::ejecutar() de PHP.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista.Tarea(titulo.strip(), etiquetas=list(etiquetas or [])) y return self._repositorio.guardar(tarea). La copia con list(...) evita compartir la lista del que llama.
Reto 3 de 4 · ✓ Resuelto
Listar solo las pendientes
Escribe ListarTareas.ejecutar(solo_pendientes=False): devuelve todas las tareas del repositorio, o solo las no hechas si solo_pendientes es True. Es un array_filter() de PHP con la condición !$t->hecha.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Pide self._repositorio.listar() y, si solo_pendientes, filtra con [t for t in tareas if not t.hecha].
Reto 4 de 4 · ✓ Resuelto
Completar: buscar, cambiar, guardar
Escribe CompletarTarea.ejecutar(id): busca la tarea, la completa con completar(), la guarda y la devuelve. Si no existe, el error TareaNoEncontrada del repositorio tiene que subir sin atraparlo. El test relee el repositorio: si no guardas, falla.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Falta el tercer paso: en vez de return tarea, devuelve self._repositorio.guardar(tarea).
Resumen
Lo que te llevas de esta lección
Un caso de uso es una clase con el repositorio en el constructor y un único ejecutar() (en PHP, un service o handler).
Cambiar algo es buscar → cambiar → guardar: lo que lees es una copia, y sin guardar() el cambio se pierde en silencio.
Un repositorio falso no hereda de nada: basta con que tenga los métodos del Protocol (en PHP harías un mock o una clase que implemente la interface).
Los errores se lanzan (TareaNoEncontrada), no se devuelven como None; la capa de fuera decide cómo contarlos.
Un único sitio, la raíz de composición, conoce las clases concretas; el resto trabaja con el Protocol (en PHP, el contenedor de dependencias).
Para recordarlo: «Busca, Cambia, Guarda»
BBusca buscar_por_id(id)
CCambia tarea.completar()
GGuarda guardar(tarea)
El ritmo de todo caso de uso que modifica algo: Busca la tarea, Cámbiala con su método del dominio y Guárdala. Si te saltas el último paso, nadie te avisa.