fastapi-best-practices

Este repositorio es una lista seleccionada de buenas prácticas y convenciones de FastAPI basada en experiencia de producción en startups. No es una biblioteca ni un framework, sino un recurso de documentación con ejemplos de código y orientación arquitectónica. Los temas clave incluyen: - Estructura del proyecto: un diseño basado en dominios inspirado en Dispatch de Netflix, donde cada módulo contiene su propio router, esquemas, modelos, servicios, dependencias, constantes, configuración, utilidades y excepciones. - Rutas asíncronas: orientación sobre el manejo de tareas intensivas en E/S y en CPU, explicando cómo FastAPI ejecuta rutas síncronas en un pool de hilos y por qué las operaciones bloqueantes en rutas asíncronas pueden detener el event loop. - Uso de Pydantic: uso extensivo de Pydantic para validación, creación de un modelo base global personalizado para una serialización consistente de fechas y horas, y división de BaseSettings entre módulos. - Dependencias: uso de dependencias de FastAPI más allá de la inyección para validación de solicitudes, encadenamiento de dependencias, aprovechamiento del almacenamiento en caché con alcance de solicitud y preferencia por dependencias asíncronas. - Prácticas varias: seguir convenciones REST, comprender el comportamiento de serialización de respuestas de FastAPI, ejecutar SDK síncronos en pools de hilos, elegir entre BackgroundTasks y colas de tareas reales, manejar la conversión de ValueError a ValidationError, ocultar la documentación por defecto, establecer convenciones de nomenclatura de bases de datos, usar migraciones de Alembic y adoptar ruff. El repositorio también incluye un archivo AGENTS.md con las mismas reglas en un formato legible por máquina para agentes de IA, con una matriz de versiones, bloques de hacer/no hacer y una lista de verificación de antipatrones. Hay disponible una traducción al chino simplificado del README.