Skip to content

README-es.md

Latest commit

 

History

History
364 lines (260 loc) · 11 KB

README-es.md

File metadata and controls

364 lines (260 loc) · 11 KB
Raw

Proyecto Base FastAPI

🇺🇸 English | 🇧🇷 Português | 🇫🇷 Français

Estado de GitHub Actions Estado de Versión

Una plantilla backend FastAPI moderna y lista para producción con mejores prácticas, soporte Docker y herramientas integrales para desarrollo rápido.

🏗️ Plantilla del Proyecto

Este proyecto fue creado usando la excelente plantilla cookiecutter-fastapi-backend por @nickatnight, que proporciona una base sólida para aplicaciones FastAPI con mejores prácticas y herramientas modernas.

📚 Documentación

✨ Características

  • FastAPI - Framework web moderno y rápido para construir APIs
  • Docker - Desarrollo y despliegue containerizado
  • PostgreSQL - Base de datos relacional robusta con soporte asíncrono
  • Redis - Caché y gestión de sesiones
  • Celery - Procesamiento de tareas en segundo plano
  • Alembic - Gestión de migraciones de base de datos
  • Pruebas - Suite de pruebas completa con pytest
  • Calidad de Código - Hooks pre-commit, linting y formateo
  • Seguridad de Tipos - Anotaciones de tipo completas con validación mypy
  • Documentación - Documentación API auto-generada con Swagger UI

🚀 Inicio Rápido

Requisitos Previos

  • Docker y Docker Compose
  • Python 3.13+ (para desarrollo local)
  • Gestor de paquetes uv

Ejecutar con Docker (Recomendado)

  1. Clonar el repositorio:

    git clone https://github.com/GabrielVGS/fastapi-base.git
cd fastapi-base

  2. Copiar variables de entorno:

    cp .env.example .env

  3. Iniciar los servicios:

    make up

  4. Acceder a la aplicación:

    • API: http://localhost:8666/v1/
    • Verificación de salud: http://localhost:8666/v1/ping
    • Documentación interactiva: http://localhost:8666/docs
    • Documentación alternativa: http://localhost:8666/redoc

🛠️ Desarrollo Local

Configuración del Entorno Local

  1. Instalar uv (si no está ya instalado):

    curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Navegar al directorio del proyecto:

    cd fastapi-base/

  3. Instalar dependencias:

    uv sync

  4. Instalar hooks pre-commit:

    make hooks

Migraciones de Base de Datos

Inicializar la primera migración (el proyecto debe estar ejecutándose con docker compose up y no contener archivos 'version'):

make alembic-init

Crear nuevo archivo de migración:

make alembic-make-migrations "describe sus cambios"

Aplicar migraciones:

make alembic-migrate

Flujo de Trabajo de Migraciones

Después de cada migración, puede crear nuevas migraciones y aplicarlas con:

make alembic-make-migrations "describe sus cambios"
make alembic-migrate

📋 Variables de Entorno

Cree un archivo .env basado en .env.example:

Configuración de Aplicación

  • PROJECT_NAME - Nombre del proyecto (por defecto: fastapi-base)
  • VERSION - Versión de la API (por defecto: v1)
  • DEBUG - Habilitar modo debug (por defecto: True)
  • SECRET_KEY - Clave secreta para JWT y encriptación
  • ENV - Entorno (dev/staging/production)

Configuración de Base de Datos

  • POSTGRES_USER - Nombre de usuario PostgreSQL
  • POSTGRES_PASSWORD - Contraseña PostgreSQL
  • POSTGRES_DB - Nombre de la base de datos
  • POSTGRES_HOST - Host de la base de datos (por defecto: localhost)
  • POSTGRES_PORT - Puerto de la base de datos (por defecto: 5432)
  • POSTGRES_URL - URL completa de la base de datos (opcional, auto-generada si no se proporciona)

Configuración Redis

  • REDIS_HOST - Host Redis (por defecto: redis)
  • REDIS_PORT - Puerto Redis (por defecto: 6379)
  • REDIS_URL - URL completa Redis (opcional, auto-generada si no se proporciona)

Configuraciones Opcionales

  • SENTRY_DSN - DSN de seguimiento de errores Sentry
  • LOG_LEVEL - Nivel de logging (por defecto: INFO)
  • CACHE_TTL - Tiempo de vida del caché en segundos (por defecto: 60)

🏃 Ejecutar la Aplicación

Usando Docker Compose (Recomendado)

# Construir e iniciar todos los servicios
make build

# Iniciar servicios (sin construcción)
make up

# Detener servicios
make down

# Acceder al bash del contenedor
make bash

Desarrollo Local (sin Docker)

# Asegurar que PostgreSQL y Redis estén ejecutándose localmente
# Actualizar .env con conexiones locales de base de datos/redis

# Ejecutar la aplicación FastAPI
uv run uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

🔧 Flujo de Trabajo de Desarrollo

Consulte el Makefile para ver todos los comandos disponibles.

Comandos Make Disponibles

# Desarrollo
make up          # Iniciar todos los servicios con Docker Compose
make down        # Detener todos los servicios
make build       # Construir e iniciar servicios
make bash        # Acceder al shell del contenedor principal

# Base de Datos
make alembic-init              # Inicializar primera migración
make alembic-make-migrations   # Crear nueva migración
make alembic-migrate          # Aplicar migraciones
make alembic-reset            # Reiniciar base de datos
make init-db                  # Inicializar base de datos con datos de ejemplo

# Calidad de Código
make test           # Ejecutar suite de pruebas con cobertura
make lint           # Ejecutar linter ruff
make black          # Formatear código con black
make isort          # Ordenar imports
make mypy           # Verificación de tipos
make precommit-run  # Ejecutar todos los hooks pre-commit

# Mantenimiento
make hooks          # Instalar hooks pre-commit

Dependencias

Por defecto, las dependencias se gestionan con uv. Por favor visite el enlace e instálelo.

Desde ./fastapi-base/ puede instalar todas las dependencias con:

uv sync

Hooks Pre-commit

El proyecto usa hooks pre-commit para asegurar la calidad del código. Instálelos con:

make hooks

Esto instalará hooks que se ejecutan automáticamente antes de cada commit para:

  • Formatear código con black
  • Ordenar imports con isort
  • Analizar código con ruff
  • Verificar tipos con mypy
  • Ejecutar pruebas

🧪 Pruebas

Ejecutar la suite completa de pruebas:

make test

Ejecutar pruebas específicas:

# Dentro del contenedor
docker compose exec fastapi-base pytest tests/test_specific.py

# Localmente (si las dependencias están instaladas)
uv run pytest tests/test_specific.py

🚀 Despliegue en Producción

El proyecto incluye configuraciones Docker listas para producción:

Usando Dockerfile de Producción

# Construir imagen de producción
docker build -f ops/production.Dockerfile -t fastapi-base:prod .

# Ejecutar contenedor de producción
docker run -p 8000:8000 --env-file .env fastapi-base:prod

Consideraciones Específicas del Entorno

  • Establecer DEBUG=False en producción
  • Usar SECRET_KEY apropiada
  • Configurar SENTRY_DSN para seguimiento de errores
  • Establecer credenciales apropiadas de base de datos
  • Usar Redis para gestión de sesiones y caché

🏗️ Estructura del Proyecto

fastapi-base/
├── fastapi-base/              # Directorio principal de la aplicación
│   ├── src/                   # Código fuente
│   │   ├── core/              # Configuración y ajustes principales
│   │   ├── models/            # Modelos de base de datos
│   │   ├── api/               # Rutas y endpoints API
│   │   ├── db/                # Utilidades de base de datos
│   │   ├── migrations/        # Migraciones de base de datos Alembic
│   │   └── main.py            # Punto de entrada de la aplicación
│   ├── tests/                 # Suite de pruebas
│   ├── pyproject.toml         # Dependencias Python y configuración de herramientas
│   └── Dockerfile             # Imagen Docker de desarrollo
├── ops/                       # Operaciones y despliegue
│   └── production.Dockerfile  # Imagen Docker de producción
├── docs/                      # Documentación
├── docker-compose.yml         # Configuración del entorno de desarrollo
├── Makefile                   # Comandos de desarrollo
└── .env.example              # Plantilla de variables de entorno

🤝 Contribuir

¡Damos la bienvenida a las contribuciones! Por favor consulte nuestras Directrices de Contribución para información detallada sobre:

  • Configurar su entorno de desarrollo
  • Estilo de código y estándares
  • Requisitos de pruebas
  • Proceso de pull request
  • Código de conducta

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - vea el archivo LICENSE para detalles.

🛠️ Construido Con

  • FastAPI - Framework web moderno y rápido
  • SQLModel - Bases de datos SQL en Python, diseñado para simplicidad
  • Alembic - Herramienta de migración de base de datos
  • Celery - Cola de tareas distribuida
  • Redis - Almacén de estructura de datos en memoria
  • PostgreSQL - Base de datos avanzada de código abierto
  • Docker - Plataforma de containerización
  • uv - Gestor de paquetes Python rápido

📚 Recursos Adicionales

⭐️ Soporte

Si encontró útil este proyecto, por favor considere:

  • Darle una estrella ⭐️ en GitHub
  • Compartirlo con sus colegas
  • Contribuir a su desarrollo
  • Reportar problemas o sugerir mejoras

¡Feliz codificación! 🚀