Prácticas recomendadas de FastAPI
Reglas de defensa para servicios FastAPI mantenibles, seguros y rápidos.
Cómo usar esta lista
- Revísala durante las revisiones de diseño y antes de los despliegues a producción.
- Convierte los fallos repetidos en políticas automatizadas de CI siempre que sea posible.
- Vuelve a revisarla después de las actualizaciones menores del framework.
Estructura
- Mantén los routers delgados y los servicios testeables.
- Un módulo de router por área de dominio.
- Coloca los esquemas Pydantic junto a las rutas o en un paquete de esquemas.
Validación
- Valida en el límite HTTP con Pydantic 2.
- Usa modelos de entrada y salida separados.
- Devuelve cuerpos 422 compatibles con los formularios del cliente.
Rendimiento
- Usa rutas async para manejadores con mucha E/S.
- Establece tiempos de espera (timeouts) en las llamadas HTTP y de base de datos salientes.
- Dimensiona los pools de bases de datos según las conexiones máximas y el número de workers.
Seguridad
- Nunca registres tokens o contraseñas.
- Deshabilita la documentación pública en producción cuando sea necesario.
- Aplica dependencias de autenticación de forma consistente en los routers protegidos.
Preguntas frecuentes
¿Cuándo debo adoptar las prácticas recomendadas de FastAPI?
Úsalas cuando los patrones y las compensaciones de esta página coincidan con tu API o límite de datos.
¿Cuál es el principal error de producción con las prácticas recomendadas de FastAPI?
Omitir la validación, los tiempos de espera o los contratos de error explícitos en el borde HTTP.
¿Cómo pruebo las prácticas recomendadas de FastAPI?
Usa el cliente de prueba del framework, anula las dependencias y afirma el estado más la forma JSON.
¿Funcionan las prácticas recomendadas de FastAPI con Python 3.14?
Sí, los ejemplos se dirigen a Python 3.14 con versiones de framework fijadas del pie de página de la pila.
¿Cómo se relacionan las prácticas recomendadas de FastAPI con Pydantic 2?
Valida y serializa en los límites; mantén los servicios funcionando con objetos de dominio tipados.
¿Síncrono o asíncrono?
Prefiere rutas asíncronas cuando la E/S domina; mantén el trabajo de CPU pequeño o descárgalo en workers.
¿Dónde debe residir la lógica de negocio?
Manejadores delgados; las reglas pertenecen a los servicios; las consultas pertenecen a los repositorios.
¿Cómo documento las APIs?
Publica documentación OpenAPI o de esquemas que coincida con los modelos de respuesta en el código.
¿Cómo manejo el versionado?
Versionado explícito de URL o encabezado con ventanas de deprecación; evita roturas silenciosas.
¿Qué debo leer a continuación?
Sigue los enlaces Relacionados para la siguiente capa de profundidad en esta sección.
¿Cómo me mantengo seguro?
Autentica a los llamadores, autoriza por recurso, limita la tasa y nunca registres secretos.
¿Primer paso para el rendimiento?
Mide la latencia de la base de datos y de los sistemas externos antes de cambiar de framework.
Relacionados
- Conceptos básicos de FastAPI - Rutas y modelos principales
- Inyección de dependencias - Proveedores por solicitud
- Pruebas de FastAPI - Patrones de cliente de prueba
- Despliegue de FastAPI - Servidores de producción
Versiones de la pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+ y uv 0.6+.