Lección 40 de 47 · Un proyecto real✦ WebMCP implementado
FastAPI y por qué necesita uvicorn
10 min de lectura3 retos
FastAPI no es un servidor. Es el framework: define tus rutas, valida lo que llega y genera la documentación. Quien abre el puerto y habla HTTP es uvicorn. En esta lección ves por qué son dos piezas, qué hace cada una, cómo se compara con nginx + php-fpm y por qué tus funciones se escriben con async def.
¿De dónde vienen los nombres?
FastAPI = inglés fast (rápido) + API (Application Programming Interface, interfaz de programación de aplicaciones)
Rápido por dos motivos que ellos mismos citan: el rendimiento (corre sobre ASGI) y lo rápido que se escribe (los tipos hacen el trabajo de validar).
uvicorn = nombre propio del servidor; su documentación lo define como «una implementación de servidor web ASGI para Python»
El programa que abre el puerto, entiende HTTP y llama a tu aplicación. Es el nginx + php-fpm de Python, todo en uno.
BaseModel = inglés base model (modelo base)
La clase de pydantic de la que heredas para describir los datos de una petición. Tus campos con tipos se validan solos.
OpenAPI = Open (abierto) + API
El formato estándar para describir una API (rutas, parámetros, respuestas). FastAPI lo genera solo y de él salen las páginas de documentación interactiva /docs.
gunicorn = Green Unicorn (unicornio verde), con juego de palabras con el servidor Unicorn de Ruby
Un servidor clásico de Python (WSGI) que gestiona varios procesos. Se puede combinar con uvicorn en producción.
En 4 ideas
1/4
FastAPI es una aplicación ASGI: un objeto que se puede llamar (app(scope, receive, send)). Define rutas, valida con pydantic y documenta en OpenAPI. No abre ningún puerto: es como tu index.php sin nginx.
uvicorn es el servidor: abre el socket, lee y entiende el HTTP, construye el scope y llama a tu app. Se lanza con uvicorn main:app (el fichero main.py, el objeto app). Es el nginx + php-fpm de Python.
En desarrollo, --reload reinicia al guardar (no hace falta en PHP: relee el script cada vez). En producción, --workers N y casi siempre nginx delante. --reload y --workers no se combinan.
Las rutas se escriben con async def cuando esperan algo (una BD, otra API): el bucle de eventos atiende otras peticiones mientras tanto. Un time.sleep o una llamada bloqueante dentro de un async defcongela todo.
1 · FastAPI es una aplicación, no un servidor
En la lección anterior viste que una aplicación ASGI es solo una función que el servidor llama. Esto es literalmente lo que es un objeto FastAPI: algo que se puede llamar con scope, receive y send. Para demostrarlo, aquí no hay servidor: llamamos nosotros a la aplicación con una petición inventada y vemos qué mensajes devuelve.
callable(app) es True: la aplicación es un objeto que se llama como una función.
FastAPI devolvió dos mensajes: la cabecera (http.response.start, con el 200) y el cuerpo (http.response.body). Es el protocolo ASGI que viste a mano.
Fíjate en que no ha hecho falta abrir ningún puerto. Por eso el TestClient de la lección de tests prueba una API sin servidor.
2 · Rutas, tipos y validación: lo que PHP hace a mano
Esta es la misma ruta, POST /tareas, en un index.php y en FastAPI. A la izquierda lo haces todo tú: leer el cuerpo, decodificar el JSON, comprobar el título y poner el código de estado. A la derecha declaras qué forma tiene el dato y FastAPI hace lo demás:
Salida real de las cuatro líneas de prueba. Una prioridad "alta" no es un entero, y FastAPI responde 422 con el campo exacto que falla, sin que escribas un solo if:
201 {'id': 1, 'titulo': 'Comprar pan', 'prioridad': 1}
422 {'detail': [{'type': 'int_parsing', 'loc': ['body', 'prioridad'], 'msg': 'Input should be a valid integer, unable to parse string as an integer', 'input': 'alta'}]}
422
404
Equivalencia POO · PHP → Python
La clase TareaNueva es el equivalente del DTO (el objeto que transporta datos) que en PHP escribirías a mano. Esto es lo que cambia:
PHP
Python (pydantic)
Quién lo ve
final readonly class TareaNueva { public function __construct(public string $titulo, public int $prioridad = 1) {} }
class TareaNueva(BaseModel): titulo: str; prioridad: int = 1
FastAPI, que lo construye con lo que llega
Validar a mano en el constructor y lanzar InvalidArgumentException
Field(min_length=1) y los tipos: pydantic valida al crear el objeto
Responde 422 sola
extends
(BaseModel): heredar de la clase base
pydantic, que lee las anotaciones de tipo
#[Route('/tareas', methods: ['POST'])] en un controlador
Lo mismo vale para los datos que van en la URL: un parámetro de la función con un tipo se convierte en parámetro de ruta (/tareas/{id} con id: int) o de consulta (?pendientes=true con pendientes: bool = False). Si id no es un entero, 422 también.
¿Por qué? · En PHP no existe
¿Por qué FastAPI usa los tipos para validar? En PHP no existe
En PHP, un tipo (int $id) se comprueba dentro de tu código y lanza un TypeError que tú has de capturar y convertir en una respuesta. Los tipos y el HTTP son dos mundos separados.
En FastAPI el tipo es la declaración de qué se espera: el framework lo lee antes de llamar a tu función, valida, convierte ("7" se vuelve 7) y, si falla, responde con el error sin que tu código llegue a ejecutarse. Los mismos tipos generan la documentación OpenAPI: el módulo 01 dijo que los tipos eran opcionales; aquí es donde se aprovechan.
Un detalle que muerde: FastAPI prueba las rutas en el orden en que las definiste y se queda con la primera que encaja. Si pones /tareas/{id}antes de /tareas/pendientes, la palabra pendientes entra como un id. Con FastAPI de verdad:
422 {'detail': [{'type': 'int_parsing', 'loc': ['path', 'id'], 'msg': 'Input should be a valid integer, unable to parse string as an integer', 'input': 'pendientes'}]}
{'detalle': 7}
La ruta /tareas/pendientes nunca se alcanza: /tareas/{id} ya la había cogido. La regla es las rutas fijas, antes que las que tienen variables. Este enrutador de juguete, con la misma regla de «gana la primera», lo muestra con Python puro:
Pythonmain.py
classEnrutador:
def__init__(self):
self.rutas = []
defregistra(self, patron, funcion):
self.rutas.append((patron.split("/"), funcion))
defatiende(self, ruta):
partes = ruta.split("/")
for patron, funcion inself.rutas:
iflen(patron) != len(partes):
continue
variables = {}
for esperado, real inzip(patron, partes):
if esperado.startswith("{"):
variables[esperado[1:-1]] = real
elif esperado != real:
breakelse:
returnfuncion(**variables)
return"404"defdetalle(id):
returnf"detalle de {id}"defpendientes():
return"lista de pendientes"
bien = Enrutador()
bien.registra("/tareas/pendientes", pendientes)
bien.registra("/tareas/{id}", detalle)
mal = Enrutador()
mal.registra("/tareas/{id}", detalle)
mal.registra("/tareas/pendientes", pendientes)
print("fijas primero:", bien.atiende("/tareas/pendientes"))
print("variables primero:", mal.atiende("/tareas/pendientes"))
3 · uvicorn: el servidor que llama a tu app
Si FastAPI no abre puertos, ¿quién lo hace? uvicorn. Se lanza desde la terminal diciéndole dónde está tu app, con la forma fichero:objeto:
$ uvicorn main:app --port 8000
INFO: Started server process [7]
INFO: Waiting for application startup.
INFO: Application startup complete.
INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO: 127.0.0.1:60024 - "GET /tareas HTTP/1.1" 200 OK
Esa salida es real (la última línea es una petición GET /tareas que le hicimos). main:app quiere decir: «importa el módulo main (el fichero main.py) y coge la variable app». Es lo mismo que escribir from main import app.
Lo que uvicorn hace por cada petición es lo que tú hiciste a mano en la lección anterior, pero con red de verdad:
Abre un puerto (por defecto 127.0.0.1:8000) y se queda escuchando.
Lee los bytes que llegan y entiende el HTTP: método, ruta, cabeceras, cuerpo.
Construye el scope con esos datos (el $_SERVER).
Llama a tu app: await app(scope, receive, send).
Convierte los mensajes que la app manda por send en una respuesta HTTP y la devuelve al navegador.
Aspecto
PHP: nginx + php-fpm
Python: uvicorn + FastAPI
Quién escucha en el puerto
nginx
uvicorn (o nginx delante, redirigiendo a uvicorn)
Cómo llega la petición a tu código
nginx habla FastCGI con php-fpm, que arranca el script
uvicorn llama a la función appdentro de su propio proceso
Procesos
Un grupo de procesos php-fpm (pm.max_children)
Un proceso con un bucle de eventos, o varios con --workers
Estado entre peticiones
Ninguno: cada una empieza limpia
Tu app vive en memoria: lo que guardes en una variable global sigue ahí
Tras editar el código
Se relee solo (con OPcache, tras su revalidación)
Hay que reiniciar, o arrancar con --reload en desarrollo
¿Por qué? · En PHP no existe
¿Por qué FastAPI y uvicorn son dos programas separados? En PHP no existe
En PHP, nginx y php-fpm también son dos programas, pero PHP trae su lado ya integrado: tú nunca ves el contrato entre los dos. En Python lo ves, porque FastAPI (el framework) y uvicorn (el servidor) los escriben autores distintos.
Esa separación es útil: la misma app FastAPI corre en uvicorn, en hypercorn o en granian sin cambiar una línea, y puedes cambiar de servidor sin tocar tu código. Y para pruebas, el TestClient hace de servidor falso y no abre ningún puerto.
4 · async def: por qué las rutas son asíncronas
Con uvicorn, un solo proceso atiende muchas peticiones a la vez usando un bucle de eventos (lo viste en el módulo 08: async/await). El truco es que, cuando una ruta tiene que esperar (a la BD, a otra API), le dice al bucle «avísame cuando llegue» con await, y mientras tanto el bucle atiende otras peticiones.
Mira la diferencia con dos tareas que esperan una décima. La primera usa time.sleep, que bloquea todo el proceso; la segunda usa await asyncio.sleep, que deja pasar a la otra. Fíjate en el orden de los mensajes:
Con time.sleep, la tarea b no empieza hasta que la a termina: una petición lenta congela a todas las demás. Con await asyncio.sleep empiezan las dos a la vez. En una API, esa espera sería una consulta a la BD.
FastAPI te deja elegir entre def y async def en cada ruta, y hace cosas distintas con cada una:
Escribes…
FastAPI la ejecuta…
Úsala cuando…
async def con await
en el bucle de eventos, sin hilos
esperas con cosas asíncronas (await consulta(...), httpx.AsyncClient)
def normal
en un hilo aparte, para no bloquear el bucle
llamas a código bloqueante de siempre (sqlite3, requests, ficheros)
async def con una llamada bloqueante dentro
bloquea todo el servidor mientras dure
nunca: es el error más típico
Pythonmain.pySolo lectura: necesita FastAPI
import asyncio
import time
from fastapi importFastAPIfrom fastapi.testclient importTestClient
app = FastAPI()
@app.get("/bien")
asyncdefbien():
await asyncio.sleep(0.01)
return {"ok": True}
@app.get("/con-def")
defcon_def():
time.sleep(0.01)
return {"ok": True}
@app.get("/mal")
asyncdefmal():
# Bloquea el bucle de eventos: ninguna otra petición avanza hasta que acabe
time.sleep(0.01)
return {"ok": True}
if __name__ == "__main__":
cliente = TestClient(app)
for ruta in ["/bien", "/con-def", "/mal"]:
print(ruta, cliente.get(ruta).json())
Las tres funcionan, y con una sola petición ni lo notarías. La diferencia aparece con carga: /mal frena a todos los demás mientras duerme; /con-def duerme en un hilo y el bucle sigue libre; /bien ni siquiera ocupa un hilo.
¿Por qué? · En PHP no existe
¿Por qué async def y no un proceso por petición como en PHP? En PHP no existe
PHP resuelve la concurrencia repitiendo procesos: cada petición, uno. Es sencillo y aísla los fallos, pero cada proceso ocupa memoria mientras espera la BD, y para atender 1000 a la vez necesitas 1000 procesos.
El bucle de eventos resuelve lo mismo esperando mejor: un solo proceso con miles de peticiones en espera, porque esperar no cuesta nada. Por eso FastAPI nació sobre ASGI y async. El inconveniente es el que acabas de ver: una llamada bloqueante frena a todos.
5 · Desarrollo y producción
Lo mismo que ya haces con PHP (php -S para probar, nginx + php-fpm para producir) tiene su pareja:
--reload vigila los ficheros y reinicia el servidor al guardar. Solo en desarrollo: gasta CPU y reinicia en medio de peticiones. Es la comodidad que PHP te da gratis al releer el script.
--workers 4 arranca 4 procesos de la app, cada uno con su bucle de eventos, para aprovechar varios núcleos. No se puede usar con --reload.
--host 0.0.0.0 hace que escuche en todas las interfaces. Por defecto escucha solo en 127.0.0.1, y dentro de un contenedor de Docker no verías nada desde fuera.
Con gunicorn como gestor de procesos (reinicio ordenado, señales) se usa el paquete uvicorn-worker: gunicorn main:app -w 4 -k uvicorn_worker.UvicornWorker. El módulo antiguo uvicorn.workers está marcado como obsoleto.
Detrás de nginx: en producción casi siempre nginx sigue delante (HTTPS, límites, ficheros estáticos) y reenvía a uvicorn con proxy_pass en vez del fastcgi_pass de php-fpm.
La pregunta que te vas a hacer
Vale, pero… ¿cómo dejo mi API siempre encendida en el VPS?
Igual que cualquier programa que no debe morir: un contenedor (Docker) con la orden de uvicorn como CMD, o un servicio de systemd, con nginx delante. El módulo 10 termina con esa fase de despliegue. A diferencia de PHP, aquí tú eres quien mantiene vivo el proceso.
cuenta_pendientes es una corrutina (async def), así que print(cuenta_pendientes()) no imprime el número: imprime un objeto corrutina. En una app real, uvicorn hace el await por ti; aquí lo tienes que hacer tú. Haz que el programa imprima 2 con asyncio.run.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Llamar a una función async def solo crea la corrutina. asyncio.run(corrutina) la ejecuta hasta el final y devuelve su resultado.
Reto 2 de 3 · ✓ Resuelto
Carga las tareas a la vez
busca(id) es una corrutina que tarda un poco (como una consulta a la BD). Escribe carga_tareas(ids): una corrutina que devuelve la lista de tareas, en el mismo orden que ids, lanzando todas las búsquedas a la vez con asyncio.gather (no una detrás de otra). Con 20 ids tiene que tardar lo de una sola.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista.asyncio.gather(*corrutinas) las lanza todas y devuelve sus resultados en el orden en que las pasaste. Crea las corrutinas con busca(id) sin await y ábrelas con *.
Reto 3 de 3 · ✓ Resuelto
Un middleware a mano
Escribe con_log(app, registro): recibe una aplicación ASGI y una lista, y devuelve otra aplicación ASGI (una async def con scope, receive y send) que primero añade scope["path"] a registro y después llama a la app original con los mismos tres argumentos. Es un middleware: en PHP, el handle($request, $next) de PSR-15.
Al pulsar Comprobar, unos tests ocultos prueban tu código en tu navegador, con Python 3.14.
Pythonmain.py · editable
Pista. Define dentro de con_log una async def envuelta(scope, receive, send): apunta scope["path"] en registro, haz await app(scope, receive, send) y devuelve envuelta (sin llamarla).
Resumen
Lo que te llevas de esta lección
FastAPI es la app, uvicorn es el servidor: FastAPI define rutas y validación; uvicorn abre el puerto y la llama (tu index.php frente a nginx + php-fpm).
uvicorn main:app = «del fichero main.py, el objeto app». Sin lanzar uvicorn, python main.py no sirve nada.
Un parámetro con tipo (id: int, nueva: TareaNueva) lo valida FastAPI antes de ejecutar tu función; si falla, responde 422 (en PHP, if a mano sobre $_POST).
async def para esperar con await, def normal para código bloqueante; un time.sleep dentro de async defcongela todo el servidor.
--reload solo en desarrollo, --workers N en producción (no se combinan) y nginx por delante, con proxy_pass en vez de fastcgi_pass.
Para recordarlo: «La app se llama, el servidor llama»
FFastAPI rutas y validación: la app
Uuvicorn puerto y HTTP: el servidor
Aasync def await si esperas; def si bloqueas
FastAPI es la app, Uvicorn el servidor y Async decide cómo esperas. Un truco para no liarte: la app es una función, y las funciones se llaman; el servidor es quien las llama.