Guía de Desarrollo

Esta guía explica cómo configurar y ejecutar la API de Autenticación SaaS en modo de desarrollo.

Prerrequisitos

Antes de comenzar, asegúrate de tener lo siguiente instalado:

Go 1.24.1 o posterior
Docker y Docker Compose
Git
Cliente de PostgreSQL (opcional, para acceso directo a la base de datos)
Cliente de Redis (opcional, para acceso directo a la caché)

Obtener el Código

git clone https://github.com/yersonargotev/saas-auth-api.git
cd saas-auth-api

Configuración del Entorno de Desarrollo

Usando Docker Compose (Recomendado)

El proyecto incluye una configuración de Docker Compose para desarrollo que proporciona:

Recarga en caliente usando Air
Base de datos PostgreSQL
Caché Redis

Para iniciar el entorno de desarrollo:

docker-compose -f docker-compose.dev.yml up

Esto realizará:

Construir la imagen Docker de desarrollo
Iniciar los servicios de PostgreSQL y Redis
Ejecutar automáticamente las migraciones de la base de datos
Iniciar la API con recarga en caliente en http://localhost:3000

Desarrollo Local (Sin Docker)

Si prefieres ejecutar la aplicación directamente en tu máquina:

Instalar las dependencias de Go:
Ventana de terminal
```
go mod download
```
Instalar Air para recarga en caliente (opcional):
Ventana de terminal
```
go install github.com/air-verse/air@latest
```
Configurar PostgreSQL y Redis localmente o utilizar instancias existentes.
Crear un archivo .env con tu configuración (ver sección de Configuración).
Ejecutar la aplicación con Air para recarga en caliente:
Ventana de terminal
```
air
```
O sin recarga en caliente:
Ventana de terminal
```
go run cmd/api/main.go
```

Configuración

La aplicación utiliza un archivo de configuración ubicado en config/config.yaml. Puedes sobrescribir estos ajustes usando variables de entorno:

app:
  name: saas-auth-api
  version: 0.1.0
  env: development
  port: 3000

database:
  host: localhost
  port: 5432
  user: postgres
  password: postgres
  name: saas_auth
  sslmode: disable
  max_open_conns: 20
  max_idle_conns: 5
  conn_max_lifetime: 30m

redis:
  host: localhost
  port: 6379
  password: ""
  db: 0

jwt:
  secret: supersecretkey-change-in-production
  access_ttl: 15m
  refresh_ttl: 24h

auth:
  password_salt: change-this-in-production
  api_key_prefix: sk-
  api_key_length: 32
  rate_limit:
    enabled: true
    requests: 100
    duration: 1m

Mapeo de variables de entorno:

APP_ENV → app.env
APP_PORT → app.port
DB_HOST → database.host
DB_PORT → database.port
DB_USER → database.user
DB_PASSWORD → database.password
DB_NAME → database.name
REDIS_HOST → redis.host
REDIS_PORT → redis.port
REDIS_PASSWORD → redis.password
JWT_SECRET → jwt.secret

Migraciones de Base de Datos

Las migraciones se ejecutan automáticamente cuando se inicia la aplicación. Los archivos de migración se encuentran en el directorio migrations.

Para ejecutar migraciones manualmente, puedes usar la herramienta CLI de golang-migrate:

# Instalar la herramienta de migración
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# Ejecutar migraciones
migrate -path ./migrations -database "postgres://postgres:postgres@localhost:5432/saas_auth?sslmode=disable" up

Pruebas

Ejecutar Pruebas Unitarias

go test ./tests/unit/...

Ejecutar Pruebas de Integración

go test ./tests/integration/...

Ejecutar Pruebas de Extremo a Extremo

go test ./tests/e2e/...

Documentación de la API

Puedes ver la documentación de la API en la interfaz Swagger accediendo al endpoint /docs cuando ejecutas la aplicación.

Flujo de Trabajo de Desarrollo

Crear una nueva rama para tu función o corrección:
Ventana de terminal
```
git checkout -b feature/mi-funcion
```
Realizar tus cambios y escribir pruebas.
Ejecutar pruebas para asegurarte de que todo funciona:
Ventana de terminal
```
go test ./...
```
Confirmar tus cambios con un mensaje descriptivo:
Ventana de terminal
```
git commit -m "Agregar mi nueva función"
```
Enviar tu rama y crear una solicitud de extracción.

Solución de Problemas

Problemas Comunes

Conexión rechazada a PostgreSQL o Redis
- Asegúrate de que los servicios estén ejecutándose
- Verifica que el host y el puerto sean correctos en la configuración
- Comprueba que ningún firewall esté bloqueando las conexiones
La recarga en caliente no funciona
- Verifica que Air esté instalado y configurado correctamente
- Asegúrate de que el archivo .air.toml exista en la raíz del proyecto
Problemas con tokens JWT
- Verifica que el secreto JWT esté configurado correctamente
- Comprueba los tiempos de expiración de los tokens en la configuración
Fallo en la migración de la base de datos
- Verifica la configuración de conexión a la base de datos
- Asegúrate de que el usuario de la base de datos tenga los permisos necesarios
- Busca errores de sintaxis en los archivos de migración

Registros y Depuración

En modo de desarrollo, los registros de la aplicación son detallados e incluyen información detallada sobre solicitudes, consultas a la base de datos y errores. Puedes ajustar el nivel de registro en el archivo de configuración.

Para habilitar información de depuración adicional, establece la siguiente variable de entorno:

APP_ENV=development

Estructura del Código

El proyecto sigue un enfoque de arquitectura limpia con la siguiente estructura:

cmd/api: Punto de entrada de la aplicación
config: Archivos de configuración
docs: Documentación de la API
internal: Núcleo de la aplicación
- apiKey: Gestión de claves API
- auth: Servicio de autenticación
- role: Gestión de roles y permisos
- user: Gestión de usuarios
migrations: Archivos de migración de base de datos
pkg: Paquetes compartidos
- config: Carga de configuración
- database: Conexión a base de datos y repositorios
- logger: Utilidades de registro
- middleware: Middlewares HTTP
- validator: Validación de entrada
tests: Conjunto de pruebas
- e2e: Pruebas de extremo a extremo
- integration: Pruebas de integración
- unit: Pruebas unitarias