Golden Path: Backend Python FastAPI
Template para servicios FastAPI async (Python 3.11+) con arquitectura hexagonal, desplegado en Cloud Run. Incluye una API de referencia Flights CRUD que ilustra los patrones a extender al crear un nuevo microservicio.
Repositorio
GitLab: templates/template-python-cr
Referencia técnica detallada del template: Template FastAPI.
Stack
| Componente | Valor |
|---|---|
| Lenguaje | Python 3.11+ |
| Framework | FastAPI (async) |
| Gestor de dependencias | uv (recomendado) o pip |
| Arquitectura | Hexagonal (domain / services / infrastructure) |
| Persistencia | PostgreSQL (SQLModel + SQLAlchemy async, asyncpg) |
| Migraciones | Alembic (migrate.py) con seed data |
| Runtime | Cloud Run |
| Observabilidad | OpenTelemetry (opentelemetry-instrument) |
Características
- OpenAPI automático — documentación interactiva en
/docs. - Autenticación JWT — validación de Bearer token contra Azure AD JWKS (
aud,exp,iss). - Schema management — sincronización del esquema al iniciar + migraciones Alembic.
- Cloud Run ready —
Dockerfile, plantillas ERB de despliegue y CI con pipelines ANDES.
API de referencia (Flights)
| Método | Ruta | Auth |
|---|---|---|
GET | /health | No |
POST | /flights | JWT |
GET | /flights | JWT |
GET | /flights/{id} | JWT |
PATCH | /flights/{id} | JWT |
DELETE | /flights/{id} | JWT |
Requisitos para desarrollo local
- Python 3.11+
- PostgreSQL (local o remoto)
- uv o
pip - Docker (opcional, para builds de contenedor)
- Registro de app en Azure AD (para los endpoints protegidos con JWT)
# Instalar dependencias y ejecutar
uv sync
uvicorn main:app --reload --host 0.0.0.0 --port 8080
La documentación interactiva queda disponible en http://localhost:8080/docs.